connectionService()

The vgLib.connectionService() system function provides two benefits:

When you use vgLib.connectionService() to create a new connection, specify the isolation level by setting the vgVar.sqlIsolationLevel system variable. If you are running in VisualAge® Generator compatibility mode and vgVar.sqlIsolationLevel is 0, the new connection has an isolation level of repeatableRead. Otherwise the new connection uses serializableTransaction. For more information, see the sqlLib connect() function.

vgLib.connectionService() is for use only in programs migrated from VisualAge Generator and EGL 5.0. The function is supported (at development time) if the EGL preference VisualAge Generator compatibility is selected or (at generation time) if the VAGCompatibility build descriptor option is set to YES.

For new programs, use these system functions instead:

vgLib.connectionService() does not return a value.

Syntax

  vgLib.connectionService(
    userID CHAR(8) in,
    password CHAR(8) in,
    serverName CHAR(18) in
    [, product CHAR(8) inOut,
       release CHAR(8) inOut
    [, connectionOption STRING in
    ]])
userID
UserID used to access the database. The argument is required, but is ignored for COBOL generation. See the "Compatibility" section for this topic.
password
Password used to access the database. The argument is required, but is ignored for COBOL generation.

This password is encrypted automatically if you pass a string literal to the function. For more information, see "Encrypting your passwords" in the EGL Programmer's Guide. Also see the "Compatibility" section in this topic.

serverName
Specifies a connection and uses that connection to assign values to the arguments product and release, if those arguments are included in the invocation of vgLib.connectionService().
The argument serverName is required. Any of the following values are valid:
blanks (no content)
If a connection is in place, vgLib.connectionService() maintains that connection. If a connection is not in place, the result (other than to assign values) is to return to the connection status in effect at the beginning of a run unit; for more information, refer to the EGL Generation Guide.
RESET
In relation to COBOL, RESET commits changes, closes cursors, releases locks, disconnects from the current database, and returns to the connection status that is in effect at the beginning of a run unit. Nevertheless, if you intend to specify RESET in this case, invoke sysLib.commit() or sysLib.rollback() before invoking vgLib.connectionService().

In relation to a Java™ program, RESET reconnects to the default database; however, if the default database is not available, the connection status remains unchanged.

For more information about the default database, refer to the EGL Generation Guide.

databaseName
Identifies a database.
If the code is running as a COBOL program, the following statements apply:
  • The value of databaseName must be a value in the location column in the SYSIBM.LOCATIONS table, which is in the DB2® UDB subsystem (in CICS®, this subsystem is attached to the CICS region)
  • Specifying a database closes all cursors, releases locks, ends any existing connection, and connects to the requested database. Nevertheless, if you intend to specify a value for databaseName, invoke sysLib.commit() or sysLib.rollback() before invoking vgLib.connectionService()
If the code is running as a Java program, the following statements apply:
  • The physical database name is found by looking up the vgj.jdbc.database.server property, where server is the name of the server specified in the vgLib.connectionService() call. If this property is not defined, the server name that is specified in the vgLib.connectionService() call is used as is.
  • The format of the database name is different for J2EE connections than for non-J2EE connections:
    • If you generated the program for a J2EE environment, use the name to which the datasource is bound in the JNDI registry; for example, jdbc/MyDB. This situation occurs if the J2EE build descriptor option was set to YES.
    • If you generated the program for a non-J2EE JDBC environment, use a connection URL; for example, jdbc:db2:MyDB. This situation occurs if the J2EE option was set to NO.
product
Receives the database product name. The argument, if any, must be a CHAR(8) variable.

To determine the string received when your code connects to a particular database, review the product documentation for the database or driver; or run your code in a test environment and write the received value to a file.

release
Receives the database release level. The argument, if any, must be a CHAR(8) variable.

To determine the string received when your code connects to a particular database, review the product documentation for the database or driver; or run your code in a test environment and write the received value to a file.

connectionOption
This parameter is ignored if you are generating a program for COBOL. The following values are valid:
D1A
The 1 in the option name indicates that only a one-phase commit is supported, and the A indicates that any disconnect is automatic. This option features the following characteristics:
  • You can connect to only one database at a time
  • A commit or rollback ends an existing connection
D1C
The 1 in the option name indicates that only a one-phase commit is supported, and the C indicates that a disconnect takes place on a commit, provided no cursors are open with HOLD. Characteristics of this option are as follows:
  • You can connect to only one database at a time
  • A commit or rollback ends an existing connection
D1E
The default value. The 1 in the option name indicates that only a one-phase commit is supported, and the E indicates that any disconnect must be explicit. In this case, a commit or rollback has no effect on an existing connection.
If you are generating a Java program, the following statements apply:
  • A connection to a database does not close cursors, release locks, or end an existing connection. However, if the run unit is already connected to the same database, the effect is equivalent to specifying DISC, and then D1E.
  • You can use multiple connections to read from multiple databases, but you can update only one database in a unit of work because only a one-phase commit is available.
DISC
Disconnect from the specified database. Disconnecting from a database causes a rollback and releases locks, but only for that database.
DCURRENT
Disconnect from the currently connected database. Disconnecting from a database causes a rollback and releases locks, but only for that database.
DALL
Disconnect from all connected databases. Disconnecting from all databases causes a rollback in those databases, but not in other recoverable resources.
SET
Set a connection current. (By default, the connection most recently made in the run unit is current.)

The following values are tolerated for compatibility with VisualAge Generator, but are equivalent to D1E: R, D2A, D2C, D2E.

Error considerations

vgLib.connectionService() sets the sqlData system variables in both sqlLib and sysVar:
  • sqlData.sqlerrd[]
  • sqlData.sqlca
  • sqlData.sqlcode
  • sqlData.sqlerrmc (available in COBOL code only)
  • sqlData.sqlwarn[]

Example

The following example shows how to use the vgLib.connectionService() function:

  vgLib.connectionService(myUserid, myPassword, 
    myServerName, myProduct, myRelease, "D1E");

Compatibility

Table 1. Compatibility considerations for connectionService()
Platform Issue
Java generation The Tomcat J2EE server ignores the userID and password from the vgLib.connectionService() function and uses the values from its server configuration.

Feedback