Installing and Configuring Data Studio

This section describes the installation and configuration steps to use Data Studio. It also explains the steps to configure servers for debugging PL/SQL Functions.

This section contains the following topics:

Installing Data Studio

Configuring Data Studio

Providing Location to Create Log File

Controlling Exception and Error Logs

Description of the Log Message

Different Types of Log Level

Installing Data Studio

Data Studio can be run after decompression of the package.

Follow the steps below to install Data Studio:

  1. Unzip the required package (32-bit or 64-bit) to the program files (x86) or program files folder respectively. If the user prefers to install in other folder, then the admin should control the folder access permissions to users.

    You will see the following files and folders:

  2. Locate and double-click the Data Studio.exe to launch Data Studio.

    The UserData folder is created after the first user launches Data Studio. Refer to Getting Started in case of any error while launching Data Studio.

To create a new database connection, refer to Adding a Connection.

Configuring Data Studio

Steps to configure Data Studio using Data Studio.ini file:

Restart Data Studio to view parameter changes. Invalid parameters added in the configuration file are ignored by Data Studio. All the following mentioned parameters are not mandatory.

List of configuration parameters used in Data Studio:

Table 1 Configuration parameters

Parameter

Description

Value Range

Default Value

-startup

Defines the JAR files required to load Data Studio. This information varies based on the version used.

N/A

plugins/org.eclipse.equinox.launcher_1.3.100.v20150511-1540.jar

--launcher.library

Defines the libraries required to load Data Studio. This information varies based on the version used.

N/A

plugins/org.eclipse.equinox.launcher.win32.win32.x86_1.1.300.v20150602-1417

or

plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.1.300.v20150602-1417 based on the package used

-clearPersistedState

Removes any cached state of the user interface and reloads Data Studio

N/A

N/A

NOTE:

It is recommended to add this parameter.

–consoleLineCount

Defines the maximum number of lines to be displayed in the Messages window.

1 - 5000

1000

-logfolder

Used to create the log folder. The user can specify the path to save logs. If the default value "." is used, then the folder is created in Data

Studio\UserData\<user name>\logs. Refer to Providing Location to Create Log File for more information.

N/A

-

-loginTimeout

Defines the connection wait time in seconds. Based on the duration value entered Data Studio will try to connect beyond which it throws a time-out error/connection failed error

N/A

180

-data

Defines the instance data location for the session.

N/A

@none

@user.home/MyAppWorkspace

Eclipse workspace is created in this location while Data Studio is being launched.

@user.home refers to C:/Users/<username>

Eclipse log files are available in @user.home/MyAppWorkspace/.metadata

N/A

N/A

-detailLogging

Defines the criteria with reference to logging error messages.

Set to True to log all error messages.

Set to False to log only error messages explicitly mentioned by Data Studio.

Refer to Controlling Exception and Error Logs for more information.

This parameter is not added by default and it can be set manually if logging is required.

True/False

False

-logginglevel

Creates the log files based on the value specified. If the value provided is arbitrary or empty, log files will be created using WARN value. Refer to Different Types of Log Level for more information.

This parameter is not added by default and it can be set manually if logging is required.

FATAL, ERROR, WARN, INFO, DEBUG TRACE, ALL, OFF

WARN

-focusOnFirstResult

Defines auto focus behavior for Result window.

Set to false to automatically set focus to the last opened Result window.

Set to true to disable the automatic set focus.

True/False

False

NOTE:
  • All the above parameters must be added before -vmargs.
  • -startup and --launcher.library must be added as first and second parameter respectively.

-vmargs

Specifies the start of virtual machine arguments.

NOTE:

-vmargs must be the last parameter in the configuration file.

N/A

N/A

-vm

<file name (javaw.exe) with relative path to Java executable>

Defines the relative path to Java executable

N/A

N/A

-Dosgi.requiredJavaVersion

Defines the minimum java version required to run Data Studio. This value must not be modified.

N/A

1.8

Note: Recommended Java version is 1.8.0_141

-Xms

Defines the initial heap space that Data Studio consumes. This value must be in multiples of 1024 and greater than 40 MB and less than or equal to -Xmx size. Append the letter k or K to indicate kilobytes, m or M to indicate megabytes, g or G to indicate gigabytes. Few examples:

  • -Xms40m
  • -Xms120m

Refer to Java documentation for more information.

N/A

-Xms40m

-Xmx

Defines the maximum heap space that Data Studio consumes. This value can be modified based on the available RAM space. Append the letter k or K to indicate kilobytes, m or M to indicate megabytes, g or G to indicate gigabytes.

Few examples:

  • -Xmx1200m
  • -Xmx1000m

Refer to the Java documentation for more information.

N/A

-Xmx1200m

-OLTPVersionOldST

It allows the user to configure the OLTP with ealier versions. User can log in to gsql and run SELECT VERSION() and update the Version in the -OLTPVersionOldST parameter in the ini file.

N/A

-

-OLTPVersionNewST

It allows the user to configure the OLTP with later versions. User can log in to gsql and run SELECT VERSION() and update the Version in the -OLTPVersionNewST parameter in the ini file.

N/A

-

-testability

This parameter is used to enable testability features. For the current version after this function is enabled:

  • The user can copy content of last triggered auto-suggest operation using the Ctrl+Space shortcut key.
  • when Include Analyze is selected, Execution Plan and Cost is displayed in tree and graphical view.

This parameter is available by default and needs to be added manually for testing.

True/False

False

-Duser.language

Defines the language settings for Data Studio. This parameter is added after the language setting is changed.

zh/en

N/A

-Duser.country

Defines the country settings for Data Studio. This parameter is added after the language setting is changed.

CN/IN

N/A

-Dorg.osgi.framework.bundle.parent=ext

This parameter specifies which class loader is used for boot delegation.

boot, app and ext

boot

-Dosgi.framework.extensions=org.eclipse.fx.osgi

This parameter is used to specify a list of framework extension names. Framework extension bundles are fragments of the system bundle (org.eclipse.osgi). As a fragment, user can provide extra classes with the framework to use.

N/A

N/A

  • The user should not change the Dorg.osgi.framework.bundle.parent=ext and Dosgi.framework.extensions=org.eclipse.fx.osgi parameters.
  • If user sees the message - SocketException : Bad Address: Connect

    Then the user should check if the client connection to the server is being established through IPv6 or IPv4 protocol. Based on the user preference, the connection can be established by providing the following statements in the .ini file

    -Djava.net.preferIPv4Stack=true

    -Djava.net.preferIPv6Stack=false

    Table 2 are supported:

    The top row and left column represent various node types attempting to communicate. An x indicates that these nodes can communicate with each other.

Table 2 Communication scenario

(Nodes)

V4 Only

V4/V6

V6 Only

V4 Only

x

x

No Communication Possible

V4/V6

x

x

x

V6 Only

No Communication Possible

x

x

Providing Location to Create Log File

  1. Open the Data Studio.ini file.
  2. Provide the path for the -logfolder parameter.

    For example:

    -logfolder=c:\test1

    In this case, the Data Studio.log file is created in the c:\test1\<user name>\logs path.

    If any of the users does not have access to the path mentioned in the Data Studio.ini file, then Data Studio closes with the below pop-up message.

The Data Studio.log file will be created in the Data Studio\UserData\<user name>\logs path if:

  • The path is not provided in the Data Studio.ini file.

    For example: -logfolder=.

  • The path provided does not exist.

Refer to the server manual for detailed information.

You can use any text editor to open and view the Data Studio.log file.

Controlling Exception and Error Logs

The stack running details of exception, error or throw-able are controlled based on the program argument parameter. This parameter is configured in the Data Studio.ini file.

-detailLogging=false

If the flag value is true, then the stack trace details of exception, error or throw-able will be saved in the log file.

If the flag value is false, then no stack trace details will be saved in the log file.

Description of the Log Message

The description of the log message is as follows:

When the Data Studio.log file reaches the maximum file size of 10000 KB, it will create a new file and save as Data Studio.log.1 automatically and the logs in Data Studio.log are moved to Data Studio.log.1. When Data Studio.log file reaches the maximum file size again, it will create a new file and save as Data Studio.log.2. Latest logs are always written in Data Studio.log file. This process continues till Data Studio.log.5 reaches the maximum file size and the cycle restarts. The Data Studio deletes the old log file that is Data Studio.log.1. For example, the Data Studio.log.5 renames to Data Studio.log.4, the Data Studio.log.4 renames to Data Studio.log.3 and so on.

To enable performance logging in the server log file, the configuration parameter log_min_messages must be enabled and value must be set as debug1 in the configuration file data/postgresql.conf, that is, log_min_messages = debug1.

Different Types of Log Level

The different types of log levels that are displayed in the Data Studio.log file are as follows:

  • TRACE: The TRACE level provides more detailed information than the DEBUG level.
  • DEBUG: The DEBUG level indicates the granular information events that are most useful for debugging an application.
  • INFO: The INFO level indicates the information messages that highlight the progress of the application.
  • WARN: The WARN level indicates potentially harmful situations.
  • ERROR: The ERROR level indicates error events.
  • FATAL: The FATAL level indicates event(s) which cause the application to abort.
  • ALL: The ALL level turns on all the log levels.
  • OFF: The OFF level turns off all the log levels. This is opposite to ALL level.
    • If the user enters an invalid value to log level, then log level will be set to WARN.
    • If the user does not provide any log level, then log level will be set to WARN.

The logger outputs all messages equal to or greater than its log level.

The order of the standard log4j levels is as follows:

Table 3 Logging Level

-

FATAL

ERROR

WARN

INFO

DEBUG

TRACE

OFF

FATAL

ERROR

WARN

INFO

DEBUG

TRACE

ALL

- Log file created      - Log file not created