File and database words enable programs to access or manipulate system and database resources, as shown in the next table.
System word/Usage | Description |
---|---|
recordName.resourceAssociation
recordName.resourceAssociation = "myFile" | Contains the system resource name associated with the record recordName and allows for a dynamic change to that name |
sysLib.commit
sysLib.commit() | Calls services to save recoverable file, database, and message queue updates since the last commit |
sysLib.connect
sysLib.connect (database, userID, password, disconnectOption, isolationLevel) | Allows a program to connect to a database at run time |
sysLib.connectionService
sysLib.connectionService (userID, password, serverName, product, release, connectionOption) | Allows a program to connect or disconnect to a database at run time and receives (optionally) the database product name and release level; but this function is supported only when you have requested compatibility with VisualAge Generator |
sysLib.disconnect
sysLib.disconnect (database) | Disconnects from the specified database or (if no database is specified) from the current database |
sysLib.disconnectAll
sysLib.disconnectAll() | Disconnects from all the currently connected databases |
sysLib.queryCurrentDatabase
sysLib.queryCurrentDatabase (product, release) | Returns the product and release number of the currently connected database |
sysLib.rollback
sysLib.rollback() | Calls system services to back out recoverable file, database, and message queue updates since the last commit point |
sysLib.setCurrentDatabase
sysLib.setCurrentDatabase (database) | Makes the specified database the currently active one |
sysVar.commitOnConverse
sysVar.commitOnConverse | Determines whether to cause a commit and a release of resources in a text application, before a non-segmented program issues a converse statement |
sysVar.errorCode
sysVar.errorCode |
Receives a status code after any of the following events:
(For an overview that includes details on sysVar.errorCode,
see Exception handling.)
|
sysVar.mqConditionCode
sysVar.mqConditionCode | Contains the completion code from an MQSeries API call following an add or scan I/O operation for an MQ record |
sysVar.sqlca
sysVar.sqlca | Contains the entire SQL communication area (SQLCA) returned for the last SQL I/O operation |
sysVar.sqlcode
sysVar.sqlcode | Contains the return code for the most recently completed SQL I/O operation |
sysVar.sqlerrd
sysVar.sqlerrd[index] | Is a static 6-element array, where each element contains the corresponding SQL communication area (SQLCA) value that was returned from the last SQL I/O option |
sysVar.sqlerrmc
sysVar.sqlerrmc | Contains the substitution variables for the error message associated with the return code in sysVar.sqlcode |
sysVar.sqlIsolationLevel
sysVar.sqlIsolationLevel | Indicates the level of independence of one database transaction from another, as is meaningful only if you are generating Java output |
sysVar.sqlState
sysVar.sqlState | Contains the SQL state value for the most recently completed SQL I/O operation |
sysVar.sqlwarn
sysVar.sqlwarn[index] | Is a static 11-element array, where each element contains a warning byte returned in the SQL communications area (SQLCA) for the last SQL I/O operation and where the index is one greater that the warning number in the SQL SQLCA description; sqlwarn[2], for example, refers to SQLWARN1 |
Related concepts
MQSeries support
SQL support
Related reference
EGL statements
Exception handling
Function invocations
System words
System words in alphabetical order
When your program does an I/O operation against a record, the I/O is done on the physical file whose name is in the record-specific variable recordName.resourceAssociation. The variable is initialized in accordance with the resourceAssociation part used at generation time; for details, see Resource associations and file types. You can change the system resource name at run time by placing a different value in resourceAssociation.
In most cases, you must use the syntax recordName.resourceAssociation. You do not need to specify a record name, however, if EGL can determine the record that you intended, as is true in each of these cases:
You can use resourceAssociation as any of the following:
The characteristics of resourceAssociation are as follows:
The value moved into recordName.resourceAssociation must be a valid system resource name for the system and file type that were specified when the program was generated. If more than one record specifies the same file name, modification of resourceAssociation for any record with that file name changes the setting of resourceAssociation for all records in the program with the same file name.
If a system resource identified in the setting of resourceAssociation is open when that record-specific variable is modified, the system resource that was in that variable is closed in the following circumstance: an I/O option runs against a record that has the same EGL file name as the record that qualifies resourceAssociation.
If two programs are using the same EGL file name, each of the record-specific resourceAssociation variables must contain the same value. Otherwise the previously opened system resource is closed when a new one is opened.
A comparison of resourceAssociation with another value tests true only if the match is exact. If you initialize resourceAssociation with a lowercase value, for example, the lowercase value matches only a lowercase value.
The value that you place in resourceAssociation remains unchanged for purposes of comparison.
You can set the system resource name either at generation or at runtime:
If a system resource is shared by multiple programs, each program that accesses the resource must set resourceAssociation to refer to the same resource. Also, if two programs in the same run unit access the same logical file, each program must set resourceAssociation to the same system resource name at generation time to ensure that both programs access the same system resource at run time.
The system resource name for MQ records defines the queue manager name and queue name. Specify the name in the following format:
queueManagerName:queueName
As shown, the names are separated with a colon. However, queueManagerName and the colon can be omitted. The system resource name is used as the initial value for the record-specific resourceAssociation item and identifies the default queue associated with the record. For further details, see MQSeries support.
Platform | Compatibility considerations |
---|---|
iSeries COBOL | The filetype must be SEQ or VSAM. The value can be moved to
resourceAssociation in one of the following ways:
When you modify the value in resourceAssociation, the iSeries OVRDBF command has this effect:
The value set in resourceAssociation is propagated from the call level and is changed to all its subordinate call levels. The value is not propagated if the file previously was opened by the program. |
Java platforms | None. |
if (process = 1) myrec.resourceAssociation = "myFile.txt"; else myrec.resourceAssociation = "myFile02.txt"; end
Related concepts
MQSeries support
Resource associations and file types
Related reference
File and database (system words)
The system function sysLib.commit saves updates that were made to databases and MQSeries message queues since the last commit. A generated Java program or wrapper also saves the updates done by a remote, CICS-based COBOL program (including updates to CICS recoverable files), but only when the call to the remote COBOL program involves a client-controlled unit of work, as described in luwControl in callLink element.
In most cases, EGL performs a single-phase commit that affects each recoverable manager in turn. On CICS for z/OS, however, sysLib.commit results in a CICS SYNCPOINT, which performs a two-phase commit that is coordinated across all resource managers.
sysLib.commit releases the scan position and the update locks in any file or databases, but an exception is in effect for COBOL programs, when the option cursorWithHold is used during database access; for details on the exception, see prepare and open.
When you use sysLib.commit with MQ records, the following statements apply:
You can enhance performance by avoiding unnecessary use of sysLib.commit. For details on when an implicit commit occurs, see Logical unit of work.
If the program issued SQL statements, sysLib.commit results in an SQL COMMIT WORK. If the program has not issued SQL requests, sysLib.commit results in the equivalent of an iSeries COMMIT command.
sysLib.commit();
Related concepts
Logical unit of work
MQSeries support
Run unit
SQL support
Related reference
File and database (system words)
luwControl in callLink element
prepare
open
sysVar.commitOnConverse
sysVar.segmentedMode
Setting the system variable sysVar.commitOnConverse to 1 causes a commit and a release of resources in a text application, before a non-segmented program issues a converse. The default value is 0 for non-segmented programs and 1 for segmented programs.
You can use sysVar.commitOnConverse in any of these ways:
Other characteristics of sysVar.commitOnConverse are as follows:
For details on using this variable, see Segmentation.
Related concepts
Segmentation in text applications
Related reference
converse
The system function sysLib.connect allows a program to connect to a database at run time. This function does not return a value.
If your code is running as a COBOL program, the following statements apply:
If your code is running as a Java program, the following statements apply:
If you use type1 as the value of commitScope, the value of parameter disconnectOption must be the word explicit, as is the default.
If you use type1 as the value of commitScope, the value of parameter disconnectOption must be set (or allowed to default) to the word explicit.
The following words are in order of increasing strictness, and as before, you cannot use quotes and cannot use a variable:
For details, see the JDBC documentation from Sun Microsystems, Inc.
sysLib.connect sets the following system variables:
sysLib.connect(myDatabase, myUserid, myPassword);
Related concepts
Logical unit of work
Run unit
SQL support
Related tasks
Syntax diagram
Setting up a J2EE JDBC connection
Understanding how a standard JDBC connection is made
Related reference
Database authorization and table names
Default database
File and database (system words)
Java run-time properties (details)
open
sqlDB
sysLib.disconnect
sysVar.sqlerrd
sysVar.sqlca
sysVar.sqlcode
sysVar.sqlerrmc
sysVar.sqlwarn
The system function sysLib.connectionService provides two benefits:
When you use sysLib.connectionService to create a new connection, specify the isolation level by setting the system variable sysVar.sqlIsolationLevel.
sysLib.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 build descriptor option VAGCompatibility is set to yes.
For new programs, use these system functions instead:
sysLib.connectionService does not return a value.
The argument serverName is required and must be an item of type CHAR and length 18. Any of the following values are valid:
In relation to a Java program, RESET reconnects to the default database; but if the default database is not available, the connection status remains unchanged.
For further details, see Default database.
If your code is running as a COBOL program, the following statements apply:
If your code is running as a Java program, the following statements apply:
To determine the string that will be 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.
To determine the string that will be 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.
If you are generating a non-CICS COBOL program, you can access only one database at a time, and you must explicitly request a disconnect to release the resources from a previous connection (if any) or to connect to a different database.
If you are generating a Java program, the following statements apply:
The 1 in the option name indicates that only a one-phase commit is supported, and the A indicates that any disconnect is automatic. Characteristics of this option are as follows:
The following values are supported for compatibility with VisualAge Generator, but are equivalent to D1E: R, D1C, D2A, D2C, D2E.
sysLib.connectionService sets the following system variables:
sysLib.connectionService(myUserid, myPassword, myServerName, myProduct, myRelease, "D1E");
Related concepts
Logical unit of work
Run unit
SQL support
Related tasks
Syntax diagram
Setting up a J2EE JDBC connection
Understanding how a standard JDBC connection is made
Related reference
Database authorization and table names
Default database
File and database (system words)
Java run-time properties (details)
sqlDB
sysVar.sqlca
sysVar.sqlcode
sysVar.sqlerrd
sysVar.sqlerrmc
sysVar.sqlIsolationLevel
sysVar.sqlwarn
The system function sysLib.disconnect disconnects from the specified database or (if no database is specified) from the current database.
Before disconnecting, invoke sysLib.commit or sysLib.rollback.
Related reference
sysLib.commit
sysLib.connect
sysLib.connectionService
sysLib.rollback
System words in alphabetical order
The system function sysLib.disconnectAll disconnects from all the currently connected databases.
Before disconnecting, invoke sysLib.commit or sysLib.rollback.
Related reference
sysLib.connect
sysLib.connectionService
System words in alphabetical order
The system function sysLib.queryCurrentDatabase returns the product and release number of the currently connected database.
To determine the string that will be 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.
To determine the string that will be 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.
Related reference
System words in alphabetical order
The system function sysLib.rollback reverses updates that were made to databases and MQSeries message queues since the last commit. That reversal occurs in any EGL-generated application.
A rollback occurs automatically when a program ends as a result of an error condition.
When you use sysLib.rollback with MQ records, the following statements apply:
Platform | Compatibility considerations |
---|---|
iSeries, USS, Windows 2000, Windows NT | Reverses changes to relational databases and MQSeries message queues, as well as changes made to remote server programs that were called using client-controlled unit of work. |
sysLib.rollback();
Related concepts
Logical unit of work
MQSeries support
SQL support
Related reference
File and database (system words)
The system function sysLib.setCurrentDatabase makes the specified database the currently active one.
Related reference
sysLib.connect
sysLib.connectionService
System words in alphabetical order
The system variable sysVar.sqlca contains the entire SQL communication area (SQLCA). As noted later, the current values of a subset of fields in the SQLCA are available to you after your code accesses a relational database.
You can use sysVar.sqlca in these ways:
In order to refer to specific fields in the SQLCA, you must move sysVar.sqlca to a base record. The record must have a structure as specified in the SQLCA description for your database management system. Use the base record if you pass the SQLCA contents to a remote program so that the contents will be converted correctly to the remote system data format.
For specific information about the fields that are available in sysVar.sqlca, refer to the following topics:
The characteristics of sysVar.sqlca are as follows:
myItem = sysVar.sqlca;
Related concepts
Segmentation in text applications
SQL support
Related reference
File and database (system words)
sysVar.sqlcode
sysVar.sqlerrd
sysVar.sqlerrmc
sysVar.sqlState
sysVar.sqlwarn
The system variable sysVar.sqlcode contains the return code for the most recently completed SQL I/O operation. The code is obtained from the SQL communications area (SQLCA) and can vary with the relational database manager.
You can use sysVar.sqlcode in these ways:
The characteristics of sysVar.sqlcode are as follows:
rcitem = sysVar.sqlcode;
Related concepts
Segmentation in text applications
SQL support
Related reference
File and database (system words)
The system array sysVar.sqlerrd is a static 6-element array, where each element contains the corresponding SQL communication area (SQLCA) value that was returned from the last SQL I/O option. The value in sysVar.sqlerrd[3], for example, is the third value and indicates the number of rows processed for some SQL requests.
Of the elements in sysVar.sqlerrd, only sysVar.sqlerrd[3] is refreshed by the database management system for Java code or at debugging time.
You can use a sysVar.sqlerrd element in these ways:
The characteristics of each element in the sysVar.sqlerrd array are as follows:
myItem = sysVar.sqlerrd[3];
Related concepts
Segmentation in text applications
SQL support
Related reference
File and database (system words)
The system variable sysVar.sqlerrmc contains the error message associated with the return code in sysVar.sqlcode. sysVar.sqlerrmc is obtained from the SQL communications area (SQLCA) and can vary with the relational database manager.
sysVar.sqlerrmc has no meaning for the JDBC environment.
You can use sysVar.sqlerrmc in these ways:
The characteristics of sysVar.sqlerrmc are as follows
sysVar.sqlerrmc is defined as a fixed-length text string.
myItem = sysVar.sqlerrmc;
Related concepts
Segmentation in text applications
SQL support
Related reference
File and database (system words)
sysVar.sqlca
The system variable sysVar.sqlIsolationLevel indicates the level of independence of one database transaction from another, and is meaningful only if you are generating Java output.
For an overview of isolation level and of the phrases repeatable read and serializable transaction, see the JDBC documentation available from Sun Microsystems, Inc.
sysVar.sqlIsolationLevel 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 build descriptor option VAGCompatibility is set to yes.
For new development, set the SQL isolation level in the sysLib.connect.
The following values of sysVar.sqlIsolationLevel are in order of increasing strictness:
You can use this variable in any of these ways:
Characteristics of sysVar.transactionID are as follows:
Related reference
sysLib.connect
The system variable sysVar.sqlState contains the SQL state value for the most recently completed SQL I/O operation. The code is obtained from the SQL communications area (SQLCA) and can vary with the relational database manager.
You can use sysVar.sqlState in these ways:
The characteristics of sysVar.sqlState are as follows:
rcitem = sysVar.sqlState;
Related concepts
Segmentation in text applications
SQL support
Related reference
Exception handling and status (system words)
File and database (system words)
The system array sysVar.sqlwarn is a static 11-element array, where each element contains a warning byte returned in the SQL communications area (SQLCA) for the last SQL I/O operation and where the index is one greater that the warning number in the SQL SQLCA description. The system variable sysVar.sqlwarn[2], for example, refers to SQLWARN1, which indicates whether characters in an item were truncated in the I/O operation.
Of the elements in sysVar.sqlwarn, only the system variable sysVar.sqlwarn[2] is refreshed by the database management system for Java code or at debugging time.
You can use sysVar.sqlwarn in these ways:
The characteristics of each element in the sysVar.sqlwarn array are as follows:
sysVar.sqlwarn[2] contains W if the last SQL I/O operation caused the database manager to truncate character data items because of insufficient space in the program's host variables. You can use logical expressions to test whether the values in specific host variables were truncated. For details, see the references to trunc in Logical expressions.
When the host variable is a number, no truncation warning is given. Fractional parts of a number are truncated with no indication. When DB2 UDB is used, if the non-fractional part of a number does not fit into a user variable, the database manager returns -304 in sysVar.sqlcode.
Also when DB2 is used, sysVar.sqlwarn[7] contains W if an adjustment was made to correct a result that was not valid from an arithmetic operation on date or time values.
In the following example, my-char-field is a field in the SQL row record just processed and lost-data is a function that sets an error message indicating that information for my-char-field was truncated.
if (sysVar.sqlwarn[2] = 'W') if (my-char-field is trunc) lost-data(); end end
Related concepts
Segmentation in text applications
SQL support
Related reference
File and database (system words)
Logical expressions
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.