connectionService()

  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.

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

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