connect()

The sqlLib.connect() system function creates a named connection to a database at run time, and makes that connection active.

Each run unit has a single current connection. By default, the connection has the name you specify for the database; you can change the name by using the sqlLib.defineDatabaseAlias() function.

The sqlLib.connect() function overrides the default SQL connection that you create through the New Connection wizard in the workbench. For more information on this wizard, see Creating an SQL database connection in the EGL Programmer's Guide. If you are migrating code from VisualAge® Generator or EGL version 5, see connectionService().

The sqlLib.connect() function does not return a value, but it does set the system variables in sqlLib.sqlData. See sqlLib.sqlData (EGL system variable).

Syntax

  sqlLib.connect(
    database STRING in,
    userID STRING in,
    password STRING in
    [, disconnectOption DisconnectKind in
    [, isolationLevel IsolationLevelKind in
    [, commitControl CommitControlKind in]]]] )
database
The database string can have one of the following values:
"RESET"
Returns the database connection to its original status. The exact meaning of the command depends on your environment, your database management software, and other factors. For more information, see Creating an SQL database connection in the EGL Programmer's Guide.
databaseName
The name of your database. The name varies depending on your environment, your database management software, and other factors. For more information, see Creating an SQL database connection in the EGL Programmer's Guide.
If your code is running as a Java™ program, the following statements apply:
  • You can find the physical database name 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 J2EE was set to NO.
userID
User ID that is used to access the database. The argument is required, but is ignored for COBOL generation. See the "Compatibility" section for this topic.
password
Password that is used to access the database. The argument is required, but is ignored for COBOL generation.

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

disconnectOption
This parameter is meaningful only for Java generation. The value is an enumeration, which must be one of the following keywords (do not use quotation marks or a variable):
explicit (the default)
The connection remains active after the program invokes sysLib.commit() or sysLib.rollback(). To release connection resources, a program must issue sqlLib.disconnect() .

If you use type1 as the value of commitScope, the value of the disconnectOption parameter must be set (or allowed to default) to explicit.

automatic
A commit or rollback ends an existing connection.
conditional
A commit or rollback automatically ends an existing connection unless a cursor is open and the hold option is in effect for that cursor. For information about the hold option, see open considerations for SQL.
isolationLevel
Indicates the level of independence between database transactions. This parameter is meaningful only for Java generation. The value for this property comes from the IsolationLevelKind enumeration:
default
Use the default isolation level of the JDBC driver, unless you are running in VisualAge Generator compatibility mode, in which case use the value of vgVar.sqlIsolationLevel (see sqlIsolationLevel). Driver vendors typically use repeatableRead, but check your documentation to be sure. This is the same behavior that you see if you do not specify this parameter.
readUncommitted
Use the most lenient isolation level, which means that the program is faster but might not detect the real state of the database.
readCommitted
Use a less lenient isolation level.
repeatableRead
Use a stricter isolation level.
serializableTransaction
Use the strictest isolation level, which means that the program is slower but detects the changes made by other programs running at the same time.

For more information, refer to the JDBC documentation from Sun Microsystems, Inc.

commitControl
Specifies whether a commit occurs after every change to the database. Ignored in COBOL code generated by EGL.
The following values are valid:
  • noAutoCommit (the default) The commit is not automatic, which typically results in the program running faster. For information about the rules of commit and rollback in this case, see Logical unit of work.
  • autoCommit Updates take effect immediately.

You can switch from autoCommit to noAutoCommit temporarily. For information, see beginDatabaseTransaction().

Example

The following is an example of the sqlLib.connect() function:

  sqlLib.connect(myDatabase, myUserid, myPassword);

Compatibility

Table 1. Compatibility considerations for connect()
Platform Issue
COBOL generation All sqlLib.connect() parameters, with the exception of database, are ignored.
Java generation The Tomcat J2EE server ignores the userID and password from the sqlLib.connect() function and uses the values from its server configuration.
J2EE To default to the user ID and password associated with the data source (defined for the JNDI name), use blanks or the empty string ("") for userID and password.

Feedback