DB2 Server for VSE & VM: Database Administration

Appendix B. CMS EXECs

SQLINIT EXEC

The SQLINIT EXEC initializes a user machine for application server access. With this EXEC, users specify the application server they wish to access and any special options. Each user must run the SQLINIT EXEC.
Note: The user machine must be initialized regardless of whether you are operating in single user mode or multiple user mode.

Initializing a User Machine

Before a user can run any DB2 Server for VM application program, use the DBS Utility, run the preprocessors, or use ISQL:

The user machine must have read access to a database machine's production minidisk (Q-disk), read/write access to its own work minidisk (A-disk), and be able to communicate with the database machine (by IUCV or APPC/VM).
For Information about providing minidisk access to user machines and allowing user machines to communicate with the database machine, see the DB2 Server for VM System Administration manual.
The user must log on and enter IPL CMS (if this was not done during the logon procedure).
The user must initialize the user machine for application server access using the SQLINIT EXEC. The syntax and options of the SQLINIT EXEC are discussed below.
Note: Because the SQLINIT EXEC may issue the CMS NUCXLOAD and CMS NUCXDROP commands, it should not be run in the CMS/DOS environment.

Figure 59 shows the format of the SQLINIT EXEC.

Figure 59. SQLINIT EXEC

>>-SQLINIT----+------------------------------------------+----->< | .-------------------------------------. | | V | | +---+---------------------------------+--+-+ | +-Dbname--(--server_name--)-------+ | | +-dcssID--(--dcss_id--)-----------+ | | | .-No--. | | | +-SYNChronous--(--+-Yes-+---)-----+ | | | .-SQLDS--. | | | +-Protocol--(--+-AUTO---+---)-----+ | | | '-DRDA---' | | | | .-8-------. | | | +-QryBlksize--(--+-integer-+---)--+ | | | .-No--. | | | +-DBCS--(--+-Yes-+---)------------+ | | +-CHARNAME--(--charname--)--------+ | | | .-ISO---. | | | +-DATEformat--(--+-USA---+---)----+ | | | +-EUR---+ | | | | +-JIS---+ | | | | '-LOCal-' | | | | .-ISO---. | | | +-TIMEformat--(--+-USA---+---)----+ | | | +-EUR---+ | | | | +-JIS---+ | | | | '-LOCal-' | | | | .-Yes--. | | | +-WorkUnit--(--+-No---+---)-------+ | | | .-00--. | | | +-TraceRA--(--+-nn--+---)---------+ | | | .-0000--. | | | +-TraceDRRM--(--+-nnnn--+---)-----+ | | | .-0--. | | | +-TraceCONV--(--+-n--+---)--------+ | | '-SSSNAME--(--string--)-----------' | +-STack------------------------------------+ +-QueRY------------------------------------+ '-RESET------------------------------------'

The parameters of the SQLINIT EXEC are as follows:

Dbname

specifies the application server to be accessed. For the DBNAME keyword, you can use any initial substring (for example, D, DB, DBN, DBNA, or DBNAM). If DBNAME is omitted, the name of the last application server specified is used as a default. If SQLINIT cannot determine the last application server accessed, you are prompted to reissue the SQLINIT EXEC with the DBNAME parameter specified. The application server can be either:

A DB2 Server for VM application server
Any application server that supports IBM's implementation of the Distributed Relational Database Architecture (DRDA) protocol.

dcssID

specifies the name of the bootstrap package that contains the saved segment ID of the RA and ISQL components. This parameter should be specified only if you want to use a specific saved segment for the database manager code; otherwise, it should be omitted. If you specify DCSSID, you must specify DBNAME.

You can specify ID instead of DCSSID for the keyword. No other abbreviation is valid. For more information about using saved segments for the database manager code, refer to the DB2 Server for VM System Administration manual.

DCSSID identifies a bootstrap package that invokes RA or ISQL code that resides in a discontiguous saved segment. If DCSSID is not specified, the dcss_id value from the resid SQLDBN file on the production disk is used. If the resid SQLDBN file is not available, and you are in a VM/ESA environment, the dcss_id value from the SQLDCSID DEFAULT file (if available) is used. If neither value is available, SQLDBA SQLRMBT and SQLDBA SQLISBT are used. See SQLINIT, SQLSTART, Bootstrap Modules and SQLDBN files for more information on this topic.
Note: In a VM/ESA environment, resid may or may not be the same as server_name.

SYNChronous

determines whether synchronous or asynchronous communication is used between the user and database machines. Synchronous communication performs better than asynchronous communication but has the following restriction: you cannot use SQLHX or CANCEL to cancel SQL statements. The only way to end an LUW is to use the DB2 Server for VM FORCE operator command, or to re-IPL CMS.

Use synchronous communication primarily when running a well tested production application against local application servers. The default value for SYNCHRONOUS is NO.

Protocol

indicates the application requester access protocol to be used for communicating with the application server.

If you specify the SQLDS option, the SQLDS protocol is used for communication between a DB2 Server for VM application requester and a DB2 Server for VM application server. If this option is specified, the application requester cannot connect to a non-DB2 Server for VM application server. Use this option if both the application server and the application requester are part of DB2 Server for VM system and both use the same default CCSIDs. SQLDS is the default value.
Note: If PROTOCOL(SQLDS) is specified, the CCSID defaults set for the application requester with the SQLINIT EXEC are not used; the CCSIDs set for the application server are used.

If you specify the AUTO option, the application requester uses the SQLDS protocol when communicating with a DB2 Server for VM application server and the DRDA protocol when communicating with other application servers. If both the application requester and the application server use AUTO protocol but have different default CCSIDs, CCSID conversion is done correctly for requests and replies. The AUTO option lets you access both like and unlike systems without changing the PROTOCOL option and reissuing SQLINIT. You should use this option in the following cases:

The user needs access to both like and unlike systems.
The CCSID defaults are not the same on the application server and the application requester. For correct CCSID conversion the application server must also use AUTO protocol.
You need an LUWID associated with each task so that you can easily trace a task back to its originating site.

If you specify the DRDA option, the application requester will use the DRDA protocol when communicating with a like or unlike application server. If the database machine is running code prior to Version 3 Release 3, the SQLDS protocol is forced for that connection. Of the three options, DRDA has the greatest performance overhead and storage requirements.

Notes:

The PROTOCOL value is ignored in single user mode and the SQLDS protocol is used for the connection.
The DRDA and AUTO options can only be specified if:
- The DRDA facility is installed on the DB2 Server for VM application requester
- The other application server to which you want to connect supports IBM's implementation of the DRDA protocol.

QryBlksize

specifies the block size of the returned rows of data when blocking performs FETCHes. The number is specified in denominations of 1K and can range anywhere from 1K to 32K. The default value is 8K.

Note:

The QRYBLKSIZE parameter is ignored when the SQLDS protocol is used for the connection.

DBCS

specifies whether DBCS character handling of SO/SI pairs is done or not. This value is used by ISQL, the DBS Utility, and the preprocessors instead of the value currently found in the SYSTEM.SYSOPTIONS table. If NO is specified, keywords are converted from lowercase to uppercase by ISQL and the DBS Utility. If YES is specified, error checking is done on DBCS data by ISQL, the DBS Utility, and the preprocessors. The default value for DBCS is NO.

CHARNAME

specifies the CCSID values (CCSIDSBCS, CCSIDMIXED, and CCSIDGRAPHIC) used by the application requester, and is used to determine how to fold characters from lowercase to uppercase. Its value must be a valid character name, such as those found in the CHARNAME column of the SYSTEM.SYSCCSIDS table. CHARNAME is supported for the DRDA and AUTO PROTOCOL options. The DB2 Server for VM product is shipped with CHARNAME of the user machine initially set to INTERNATIONAL.

The SQLPREP EXEC, the DBS Utility, and the Resource Adapter use the CHARNAME value for folding support in both single user mode and multiple user mode. See the DB2 Server for VSE & VM Application Programming manual for information on the SQLPREP EXEC.

DATEformat

specifies the date format. The default is ISO. This parameter is for information only. It represents the date format in which the user wants to see date values returned.

TIMEformat

specifies the time format. The default is ISO. This parameter is for information only. It represents the time format in which the user wants to see time values returned.

WorkUnit

specifies whether CMS Work Unit support is to be used for an application. The default is Yes.

TraceRA

specifies the parts of the Resource Adapter (RA) that are to be traced and the level of the trace. The positional digits correspond to the following Resource Adapter subcomponents and functions:

RA control flow
Communications.

When 0 is specified, tracing is turned off. When 1 is specified, tracing is done in limited detail. When 2 is specified, tracing is done in greater detail. The default value for TRACERA is 00.

Note: A data stream trace is obtained by tracing the communications subcomponent.

The following CMS FILEDEF command was entered to define the default trace output file:

     FILEDEF ARITRAC TAP2 SL (BLKSIZE 4096 NOCHANGE PERM

You can enter a different CMS FILEDEF command to override the default. The options you specify on your CMS FILEDEF command will not be overridden unless you reenter a CMS FILEDEF command to change them.
Note: The trace output, requested using the TRACERA, TRACEDRRM, and TRACECONV parameters, is stored in a single file.

TraceDRRM

specifies the parts of the DRRM component that are to be traced and the level of the trace. The positional digits correspond to the following DRRM subcomponents and functions:

Parser
Generator
Dictionary
RDIIN Manager.

When 0 is specified, tracing is turned off. When 1 is specified, tracing is done in limited detail. When 2 is specified, tracing is done in greater detail. The default value for TRACEDRRM is 0000.

The following CMS FILEDEF command was entered to define the default trace output file:

     FILEDEF ARITRAC TAP2 SL (BLKSIZE 4096 NOCHANGE PERM

Notes:

The TRACEDRRM parameter is ignored when the SQLDS protocol is used for the connection.
The trace output, requested using the TRACERA, TRACEDRRM, and TRACECONV parameters is stored in a single file.

TraceCONV

specifies that the data conversion component is to be traced and the level of the trace.

When 0 is specified, tracing is turned off. When 1 is specified, tracing is done in limited detail. When 2 is specified, tracing is done in greater detail. The default value for TRACECONV is 0.

The following CMS FILEDEF command was entered to define the default trace output file:

     FILEDEF ARITRAC TAP2 SL (BLKSIZE 4096 NOCHANGE PERM

SSSNAME

specifies the name of the status shared segment. This parameter is optional. For more information on defining the status shared segment for the DB2 Server for VM system, refer to the DB2 Server for VM System Administration manual.

STack

places all values currently set for the parameters of the SQLINIT EXEC, except DCSSID, onto the CMS stack in the same sequence as shown for QUERY.

QueRY

displays all values currently set for the parameters of the SQLINIT EXEC, except DCSSID. It also displays the resource adapter code release level, CCSID values, LDATELEN value, and LTIMELEN value. (See SQLGLOB EXEC for information about LDATELEN and LTIMELEN.)

Note:

The value returned for CHARNAME is valid only if the value specified for the PROTOCOL parameter is not SQLDS. If the PROTOCOL parameter value is SQLDS, the CHARNAME value returned for the application requester is the same as the CHARNAME value of the application server to which it is connected (even if they are not the same).

The following is sample output from an SQLINIT QUERY.

+--------------------------------------------------------------------------------+
|ARI0717I Start SQLINIT EXEC: 05/29/92 14:52:40 EDT.                             |
|SELECTED TABLE IS: SQL/DS                                                       |
| DBNAME=SQLDBA                                                                  |
| DBCS=NO                                                                        |
| SYNCHRONOUS=NO                                                                 |
| DATEFORMAT=ISO                                                                 |
| TIMEFORMAT=ISO                                                                 |
| TRACERA=00                                                                     |
| LDATELEN=0                                                                     |
| LTIMELEN=0                                                                     |
| RELEASE=3.3.0                                                                  |
| WORKUNIT=NO                                                                    |
| QRYBLKSIZE=8                                                                   |
| PROTOCOL=SQLDS                                                                 |
| CHARNAME=INTERNATIONAL                                                         |
| CCSIDSBCS=500                                                                  |
| CCSIDMIXED=0                                                                   |
| CCSIDGRAPHIC=0                                                                 |
| TRACEDRRM=0000                                                                 |
| TRACECONV=0                                                                    |
| SSSNAME=                                                                       |
|ARI0796I End SQLINIT EXEC: 05/29/92 14:52:40 EDT                                |
+--------------------------------------------------------------------------------+

RESET

resets all values currently set for the parameters of the SQLINIT EXEC, except DCSSID. The next time the SQLINIT EXEC is invoked, the defaults are used.

The SQLINIT EXEC parameter values are stored in the CMS LASTING GLOBALV file. Each time the SQLINIT EXEC is run, the parameter values are appended to the LASTING GLOBALV file. To maintain the LASTING GLOBALV file size, duplicate entries can be removed. Subsequently, when the user reenters the SQLINIT EXEC, the parameter value is established as follows:

If the user specifies a parameter on the SQLINIT EXEC, that parameter value is used.
If a parameter is not specified on the SQLINIT EXEC, the value stored in the LASTING GLOBALV file is used. That is, the default is the value used on the most recent SQLINIT EXEC.
If there are no values in the LASTING GLOBALV file (no values were specified on a previous SQLINIT EXEC, or SQLINIT RESET has reset the entries to blanks in the LASTING GLOBALV file), the application server-wide defaults established by the SQLGLOB EXEC are used.
If nothing is available, that is, if no application server-wide defaults established by the SQLGLOB EXEC exist, the SQLINIT EXEC will supply hardcoded defaults, except for the DBNAME parameter.

The parameter values remain in the LASTING GLOBALV file until explicitly changed through a subsequent SQLINIT EXEC with new parameters. SQLINIT RESET resets the entries to blanks, for any SQLINIT EXEC parameter values currently stored in the LASTING GLOBALV file.

The LASTING GLOBALV file is left on the user's A-disk. This means that users do not have to run the SQLINIT EXEC every time they log on. (This also means that users do not need to run the SQLINIT EXEC from their PROFILE EXECs.) The only times the user needs to rerun the SQLINIT EXEC are:

When the user wants to change the default application server
When the user wants to change any of the SQLINIT EXEC parameter values.

SQLINIT, SQLSTART, Bootstrap Modules and SQLDBN files

The SQLINIT EXEC provides for a user's program to communicate with the database machine by copying to the user's A-disk the following bootstraps:

   dcss-id SQLRMBT Q  --->  ARISRMBT MODULE A
   dcss-id SQLISBT Q  --->  ARISISBT MODULE A

The bootstrap modules reside on the production minidisk (Q-disk).

Prior to Version 3 Release 1, the SQLINIT EXEC used the ARISRMBT module to obtain default SQLINIT EXEC values. The SQLINIT EXEC now uses the LASTING GLOBALV file instead of this bootstrap module to obtain default values. The bootstrap module is still produced to maintain compatibility with load modules generated prior to Version 3 Release 1.

The ARISRMBT module is for the resource adapter, but it is incomplete. The resource adapter needs to know the name of the database machine with which it is to communicate.
Note: In a VM/ESA environment, the resource adapter only needs to know the database (resource) name.

The resource adapter also needs to know the default DCSSID. At this time ARISRMBT does not contain this information. The SQLINIT EXEC uses a CMS file called a SQLDBN file to locate information about a database.

The SQLDBN file is created by the SQLSTART EXEC. When the SQLSTART EXEC is invoked, it starts the database manager code in a particular machine to access a particular application server. The SQLSTART EXEC creates a CMS file on the production minidisk to record this information (if the CMS file does not already exist). The name of the file is taken from the DBNAME parameter if the resid is the same as the server-name; otherwise, the resid will be resolved using the RESID NAMES file. The filetype is SQLDBN. So, suppose you log on the SQLDBA database machine and enter:

   SQLSTART DBNAME(DB01) DCSSID(MYBOOT)

The SQLSTART EXEC accesses or creates the DB01 SQLDBN Q file.

DB01 contains the following information:

The server-name of the application server being accessed (DB01)
The name of the database machine that is accessing the application server (SQLDBA)
Note: The name of the database machine is not needed to complete the bootstrap in a VM environment.
The name of the bootstrap or DCSSID being used (MYBOOT).

When the database machine is shut down, the resid SQLDBN file remains on the production minidisk. (The name of the file is taken from the DBNAME parameter if the resid is the same as the server-name; otherwise, the resid will be resolved using the RESID NAMES file.) It is updated whenever a database machine is started to access the application server and one of the following is true:

The DCSSID specified on the SQLSTART EXEC is different from the one stored in the SQLDBN file
The AMODE specified on the SQLSTART EXEC is different from the one stored in the SQLDBN file
The DBNAME specified on the SQLSTART EXEC is different from the one stored in the SQLDBN file
The database machine trying to access the application server is different from the one that last created the SQLDBN file.

The SQLINIT EXEC uses these SQLDBN files to complete the resource adapter bootstrap module.

That is, the SQLINIT EXEC looks for the SQLDBN file having the resid that corresponds to the DBNAME parameter. If the DBNAME is greater than 8 bytes, it uses the SQLDCSID DEFAULTS file. Otherwise, the SQLINIT EXEC reads the information in the SQLDBN file and then generates the complete resource adapter bootstrap on the work minidisk:

   ARISRMBT MODULE A        resid SQLDBN Q       ARISRMKC TEXT Q
   -------------------------------------------------------------
                     |
                     V
             ARISRMBT MODULE A

The new module is called ARISRMBT. It will replace any existing ARISRMBT MODULE on the user's A-disk. ARISRMBT serves two purposes:

It identifies where the resource adapter code is to be loaded
It tells the resource adapter where to direct its communications.

Note the resid SQLDBN files will not be available to user machines that:

Access an application server that resides on a different processor
Access an application server that does not own the Production (Q) minidisk to which the user has a link.

If the SQLDBN file is not available, the SQLINIT EXEC looks for the SQLDCSID DEFAULT file for a default saved segment (DCSSID). If the SQLDBN file or SQLDCSID DEFAULT file is not found on the Production (Q) disk, the default SQLDBA SQLRMBT and SQLDBA SQLISBT bootstrap modules are used. If the dcss-id from the default SQLDBN file is not the one desired, specify the dcss-id on the SQLINIT EXEC to override it.
Note: The SQLDCSID DEFAULT file is only used in a VM environment. The SQLDCSID DEFAULT file is created by the SQLGENLD EXEC. See the DB2 Server for VM System Administration manual for more information on saved segments.

The ISQL bootstrap module, on the other hand, only identifies where the ISQL code is to be loaded. Because ISQL uses the resource adapter also, there is no need to identify the database machine in the ISQL bootstrap.

When an application initially calls the database manager, the bootstraps are executed to load the resource adapter and to help establish communication with the database machine. The database name is used for APPC/VM communication in VM environments.

Note that the bootstrap modules are left on the user's A-disk. This means that a user does not have to run the SQLINIT EXEC every time he or she logs on. (This also means that users do not need to run the SQLINIT EXEC from their PROFILE EXECs.) The only times the user needs to rerun SQLINIT are:

When the user wants to change the default application server. If for any reason the bootstraps are not valid, it is detected and a message is issued to the user.
When the user wishes to use bootstraps that have been defined after running the SQLINIT EXEC.
For example, if bootstrap modules are defined, the user runs the SQLINIT EXEC, and then new bootstrap modules are defined, the user will have to run the SQLINIT EXEC again to take advantage of the new bootstrap modules.

When the DBNAME parameter is not specified on the SQLINIT EXEC, the name of the application server last accessed will be obtained from the ARISRMBT module residing on the user's A-disk. New versions of the ARISRMBT and ARISISBT modules will then be generated to reflect the information stored in the SQLDBN file for that application server.

You can run the SQLINIT EXEC any number of times from within another EXEC.

SQLGLOB EXEC

Use the SQLGLOB EXEC to set the default parameter values for the SQLINIT EXEC, except DCSSID, for your local DB2 Server for VM application server. The default values will only be used for application requests that have linked to the production disk of the local application server. The syntax of the SQLGLOB EXEC is similar to that of the SQLINIT EXEC.

The SQLGLOB EXEC creates a file on the production disk, called SQLGLOB DEFAULTS, containing all the default values for the SQLINIT EXEC, except DCSSID. If a user runs the SQLINIT EXEC without specifying some of the parameter values and these values are not stored in the LASTING GLOBALV file, then the missing parameter values are taken from the SQLGLOB DEFAULTS file that was created with the SQLGLOB EXEC. The syntax of the SQLGLOB EXEC is shown in Figure 60.

Figure 60. SQLGLOB EXEC

>>-SQLGLOB----+------------------------------------------+----->< | .-------------------------------------. | | V | | +---+---------------------------------+--+-+ | +-Dbname--(--server_name--)-------+ | | | .-No--. | | | +-SYNChronous--(--+-Yes-+---)-----+ | | | .-SQLDS--. | | | +-Protocol--(--+-AUTO---+---)-----+ | | | '-DRDA---' | | | | .-8-------. | | | +-QryBlksize--(--+-integer-+---)--+ | | | .-No--. | | | +-DBCS--(--+-Yes-+---)------------+ | | +-CHARNAME--(--charname--)--------+ | | | .-ISO---. | | | +-DATEformat--(--+-USA---+---)----+ | | | +-EUR---+ | | | | +-JIS---+ | | | | '-LOCal-' | | | | .-ISO---. | | | +-TIMEformat--(--+-USA---+---)----+ | | | +-EUR---+ | | | | +-JIS---+ | | | | '-LOCal-' | | | | .-0-------. | | | +-LDATELEN--(--+-integer-+---)----+ | | | .-0-------. | | | +-LTIMELEN--(--+-integer-+---)----+ | | | .-Yes--. | | | +-WorkUnit--(--+-No---+---)-------+ | | | .-00--. | | | +-TraceRA--(--+-nn--+---)---------+ | | | .-0000--. | | | +-TraceDRRM--(--+-nnnn--+---)-----+ | | | .-0--. | | | +-TraceCONV--(--+-n--+---)--------+ | | '-SSSNAME--(--string--)-----------' | +-STack------------------------------------+ +-QueRY------------------------------------+ '-RESET------------------------------------'

The parameters of the SQLGLOB EXEC are as follows:

Dbname

A DB2 Server for VM application server
Any application server that supports IBM's implementation of the Distributed Relational Database Architecture (DRDA) protocol.
Note: Access to non-DB2 Server for VM application servers is only possible if the DRDA facility is installed on the DB2 Server for VM application requester.

SYNChronous

determines whether synchronous or asynchronous communication is used between the user and database machines. Synchronous communication performs better than asynchronous communication but has the following restriction: you cannot use SQLHX or CANCEL to cancel SQL statements. The only ways to end an unwanted LUW is to use the FORCE command, or to re-IPL CMS.

Use synchronous communication primarily when running a well tested production application against local application servers. The default value for SYNCHRONOUS is NO.

Protocol

indicates the application requester access protocol to be used for communicating with the application server.

If you specify the AUTO option, the application requester uses the SQLDS protocol when communicating with DB2 Server for VM application servers and the DRDA protocol when communicating with other application servers. If both the application requester and the application server use AUTO protocol but have different default CCSIDs, CCSID conversion is done for requests and replies. The AUTO option lets you access both like and unlike systems without changing the PROTOCOL option and reissuing SQLINIT. You should use this option in the following cases:

The user needs access to both like and unlike systems.
The CCSID defaults are not the same on the application server and the application requester. For correct CCSID conversion the application server must also use AUTO protocol.
You need an LUWID associated with each task so that you can easily trace a task back to its originating site.

Notes:

The PROTOCOL value is ignored in single user mode and the SQLDS protocol is used for the connection.
The DRDA and AUTO options can only be specified if:
- The DRDA facility is installed on the DB2 Server for VM application requester
- The other application server to which you want to connect supports IBM's implementation of the DRDA protocol.

QryBlksize

specifies the block size of the returned rows of data when blocking performs FETCHes. The number is specified in denominations of 1K and can range anywhere from 1K to 32K. The default value is 8K.

Note:

The QRYBLKSIZE parameter is ignored when the SQLDS protocol is used for the connection.

DBCS

CHARNAME

specifies the CCSID values (CCSIDSBCS, CCSIDMIXED, and CCSIDGRAPHIC) used by the application requester, and determines how to fold characters from lowercase to uppercase. Its value must be a valid character name, such as those found in the CHARNAME column of the SYSTEM.SYSCCSIDS table. CHARNAME is supported for the DRDA and AUTO PROTOCOL options. The DB2 Server for VM product is shipped with CHARNAME of the user machine initially set to INTERNATIONAL.

DATEformat

specifies the date format. The default is ISO. This parameter is for information only. It represents the date format in which the user wants to see date values returned.

TIMEformat

specifies the time format. The default is ISO. This parameter is for information only. It represents the time format in which the user wants to see time values returned.

LDATELEN

gives the length of the local date format. The values may range from 10 to 254, and 0. The default is 0, which indicates that LOCAL format is not available.

LTIMELEN

gives the length of the local time format. The values may range from 8 to 254, and 0. The default is 0, which indicates that LOCAL format is not available.

WorkUnit

specifies whether CMS Work Unit support is to be used for an application. The default is Yes. CMS Work Units are supported in VM environments only.

TraceRA

specifies the parts of the Resource Adapter (RA) that are to be traced and the level of the trace. The positional digits correspond to the following Resource Adapter subcomponents and functions:

RA control flow
Communications.

When 0 is specified, tracing is turned off. When 1 is specified, tracing is done in limited detail. When 2 is specified, tracing is done in greater detail. The default value for TRACERA is 00.

The following CMS FILEDEF command was entered to define the default trace output file:

     FILEDEF ARITRAC TAP2 SL (BLKSIZE 4096 NOCHANGE PERM

TraceDRRM

specifies the parts of the DRRM component that are to be traced and the level of the trace. The positional digits correspond to the following DRRM subcomponents and functions:

Parser
Generator
Dictionary
RDIIN Manager.

When 0 is specified, tracing is turned off. When 1 is specified, tracing is done in limited detail. When 2 is specified, tracing is done in greater detail. The default value for TRACEDRRM is 0000.

The following CMS FILEDEF command was entered to define the default trace output file:

     FILEDEF ARITRAC TAP2 SL (BLKSIZE 4096 NOCHANGE PERM

Notes:

The TRACEDRRM parameter is ignored when the SQLDS protocol is used for the connection.
The trace output, requested using the TRACERA, TRACEDRRM, and TRACECONV parameters is stored in a single file.

TraceCONV

specifies that the data conversion component is to be traced and the level of the trace.

When 0 is specified, tracing is turned off. When 1 is specified, tracing is done in limited detail. When 2 is specified, tracing is done in greater detail. The default value for TRACECONV is 0.

The following CMS FILEDEF command was entered to define the default trace output file:

     FILEDEF ARITRAC TAP2 SL (BLKSIZE 4096 NOCHANGE PERM

SSSNAME

specifies the name of the status shared segment. This parameter is optional, and is intended for use with products such as the IBM SystemView Information Warehouse DataHub Support/VM software. For more information on defining the status shared segment for the DB2 Server for VM system, refer to the DB2 Server for VM System Administration manual.

STack

places all values currently set for the parameters of the SQLGLOB EXEC onto the CMS stack in the same sequence as shown for QUERY.

QueRY

displays all values currently set for the parameters of the SQLGLOB EXEC. It also displays the resource adapter code release level and CCSID values. The following is sample output from an SQLGLOB QUERY.

+--------------------------------------------------------------------------------+
|ARI0717I Start SQLGLOB EXEC: 05/29/92 10:27:36 EDT.                             |
|DBNAME=SQLDBA                                                                   |
|DBCS=NO                                                                         |
|SYNCHRONOUS=NO                                                                  |
|DATEFORMAT=ISO                                                                  |
|TIMEFORMAT=ISO                                                                  |
|TRACERA=00                                                                      |
|LDATELEN=0                                                                      |
|LTIMELEN=0                                                                      |
|RELEASE=3.3.0                                                                   |
|WORKUNIT=NO                                                                     |
|QRYBLKSIZE=8                                                                    |
|PROTOCOL=SQLDS                                                                  |
|CHARNAME=INTERNATIONAL                                                          |
|CCSIDSBCS=500                                                                   |
|CCSIDMIXED=0                                                                    |
|CCSIDGRAPHIC=0                                                                  |
|TRACEDRRM=0000                                                                  |
|TRACECONV=0                                                                     |
|SSSNAME=                                                                        |
|ARI0796I End SQLGLOB EXEC: 05/29/92 10:27:36 EDT                                |
+--------------------------------------------------------------------------------+

RESET

resets all values currently set for the parameters of the SQLGLOB EXEC. The next time the SQLGLOB EXEC is run, the defaults are used.

SQLCIREO EXEC

This EXEC reorganizes the indexes on the catalog tables. The following diagram shows the format of the SQLCIREO EXEC.

Figure 61. SQLCIREO EXEC

>>-SQLCIREO--Dbname---(--dbname--)----+----------------------+--> '-dcssID--(--ssid--)---' >-----+-------------------------+------------------------------>< '-PARM--(--parameter--)---'

Dbname

specifies the name of the database for which you want to reorganize the catalog indexes. Any initial substring for DBNAME can be used as the keyword (for example DB or D).

dcssID

specifies the name of a bootstrap package that identifies a saved segment. You can use DCSSID or ID for the keyword. If not specified, DCSSID defaults to SQLDBA. The SQLDBA bootstrap package causes the database manager code to be loaded into the DMSFREE area.

PARM

specifies additional DB2 Server for VM initialization parameters. If you specify the PARM parameter, it must follow the other SQLCIREO parameters.

The valid initialization parameters are:

ARCHPCT=n

CHARNAME=name

CHKINTVL=n

DUMPTYPE=F|N|P

LOGMODE=A|L|N|Y

NCSCANS=n

NDIRBUF=n

NPAGBUF=n

PARMID=name

SLOGCUSH=n

SOSLEVEL=n

TRACCONV=n

TRACDBSS=nnnnnnnnnnn

TRACDRRM=nnnn

TRACDSC=nn

TRACEBUF=n

TRACRDS=nnnnnnn

TRACWUM=n

TRACSTG=n

Initialization parameters are described in the DB2 Server for VM System Administration manual and the DB2 Server for VSE & VM Operation manual.

SQLCIREO automatically supplies the initialization parameters DBNAME (based on what you supply in the EXEC parameter DBNAME), SYSMODE=S, and STARTUP=I.

To avoid the processing involved in switching log modes, use the same LOGMODE that you normally use.

Because the catalog index reorganization utility runs in single user mode, the only way to trace it is with the TRACDBSS, TRACDSC, and TRACWUM initialization parameters. (The TRACE operator command cannot be used in single user mode.)

If you are using tracing, you may want to enter your own CMS FILEDEF and LABELDEF commands before invoking SQLCIREO. These optional CMS FILEDEF and LABELDEF commands are described in the VM/ESA: CMS Application Development Reference for your VM system.

For example, to reorganize the indexes for the PRODX database, you might enter:

   SQLCIREO D(PRODX) PARM(LOGMODE=A)

The catalog index reorganization utility directs messages to SYSPRINT. If you do not supply a FILEDEF command for SYSPRINT, SQLCIREO assigns SYSPRINT to the terminal. This FILEDEF command directs the utility's messages to the CMS file REORG PRT A:

   FILEDEF SYSPRINT DISK REORG PRT A (RECFM FBA LRECL 121 BLOCK 1210

The utility prints informational messages that describe what actions it has taken. Packages are not invalidated if they use an index reorganized by the SQLCIREO utility.

If the catalog index reorganization utility abnormally ends, all changes it has made to the database are rolled back. You should rerun the utility after correcting the problem.

SQLDBID EXEC

The SQLDBID EXEC displays the name of the default application server that has been established by the SQLINIT EXEC.

Figure 62 shows the format of the SQLDBID EXEC.

Figure 62. SQLDBID EXEC

>>-SQLDBID----+------+----------------------------------------->< +-LIFO-+ '-FIFO-'

The SQLDBID EXEC resides on the production minidisk. The SQLDBID EXEC displays the name of the default application server that will be accessed if the resource adapter bootstrap on the A-disk is used.

The SQLDBID EXEC does no more than display information. If the name of the application server displayed is not the one you want to access, you must rerun the SQLINIT EXEC.

If you specify the LIFO or FIFO parameters, the information provided by the SQLDBID EXEC is stacked onto the most recently created buffer of the program stack (system provided data queue). If you specify the FIFO parameter, the information is stacked on a first in, first out basis. If you specify the LIFO parameter, the information is stacked on a last in, first out basis. If neither parameter is specified, message ARI0320I, specifying the application server name, is issued.

SQLRMEND EXEC

The SQLRMEND EXEC manages the communication links between an application program and an application server. It does this in two ways:

If you have more than one program called from an EXEC, SQLRMEND can ensure the integrity of each program by dropping the link used by the current program, or dropping the resource adapter code which drops all links between all programs and all application servers they access
If you have one program, SQLRMEND can drop the resource adapter code to free storage from your virtual machine.
If your program runs the CMS subset, a ROLLBACK or COMMIT of all LUWs is prevented. This is to ensure that any LUWs in the native CMS MODE are not affected.

Usually the resource adapter code and control blocks are not dropped and outstanding work is not committed until the end of the VM command. When programs are invoked from within EXECs, the "end of command" is at the end of the EXEC, not the end of the program. If you want to drop the resource adapter code or perform COMMIT/ROLLBACK processing at the end of a program (not at the end of the EXEC), you must run the SQLRMEND EXEC.

Figure 63 shows the format of the SQLRMEND EXEC.

Figure 63. SQLRMEND EXEC

.-COMMIT---. .-RELEASE--. >>-SQLRMEND----+-ROLLBACK-+---+-KEEP-----+--------------------->< '-ALL------'

The SQLRMEND EXEC resides on the production minidisk.

The SQLRMEND EXEC can be used to drop the DB2 Server for VM resource adapter code and its control blocks from within the DMSFREE (user free storage) area of a user's virtual machine. It allows users who invoke more than one program from within an EXEC to free the storage used by the resource adapter. The storage can then be used by other programs.

The SQLRMEND EXEC can also be used to perform COMMIT/ROLLBACK processing on all outstanding work. It allows users who invoke more than one program from within an EXEC to COMMIT or ROLLBACK all outstanding work before the next program is executed.

You may have separate logical units of work active at one time. You could do this by having one or more programs running in separate CMS Work Units. When you use SQLRMEND in this situation, the second option (RELEASE, KEEP, or ALL) determines which CMS Work Units are affected.
Note: You cannot use COMMIT ALL or ROLLBACK ALL in CMS subset mode to prevent the user from affecting any work done previously in a normal CMS mode. The SQLRMEND EXEC will not allow these parameters in CMS subset mode.

COMMIT RELEASE

is the default. Specifies the currently active LUW within the active work unit is to be committed, the communication link to be released. Resource adapter code is dropped only if there is just one CMS Work Unit.

If you have more than one CMS Work Unit, only the current LUW is committed, and the link between the program and the database it is accessing is dropped.

COMMIT KEEP

specifies the active LUW within the active work unit is to be committed and the communication link and the resource adapter code are to be kept.

COMMIT ALL

specifies all active LUWs for all suspended and active work units are to be committed, the communication link(s) to be released, and the resource adapter code is to be dropped.

ROLLBACK RELEASE

specifies the active LUW in the active work unit is to be rolled back and the communication link is to be released. Resource adapter code is dropped only if there is just one CMS Work Unit.

If you have more than one CMS Work Unit, the current link between the program and the application server it is accessing is dropped, and the current logical unit of work is rolled back.

ROLLBACK KEEP

specifies the currently active LUW in the active work unit is to be rolled back and that the communication link and the resource adapter code are to be kept.

ROLLBACK ALL

specifies all active LUWs for all suspended and active work units are to be rolled back, the communication link(s) to be released, and the resource adapter code is to be dropped.

COMMIT

is equivalent to COMMIT RELEASE.

RELEASE

is equivalent to COMMIT RELEASE.

ROLLBACK

is equivalent to ROLLBACK RELEASE.

KEEP

is equivalent to COMMIT KEEP.

ALL

is equivalent to COMMIT ALL.

The KEEP option will keep the communication link. Therefore if you want to access an application server again from within the EXEC, your next program will be able to use the same SQL connection (user ID and application server) without issuing an explicit CONNECT.

Unless you are maintaining more than one CMS Work Unit, the RELEASE option will drop the communication link and the resource adapter code. Only the storage used for the resource adapter control blocks will be freed. If you want to access the DB2 application server again from within the EXEC, you do not need to enter anything to get the resource adapter code back into storage. Just invoke the DB2 Server for VM application. The resource adapter code will automatically be reloaded.

If you can have more than one CMS Work Unit, the RELEASE option drops the current link. Logical units of work in other CMS Work Units are still active.

Example

The following example is a portion of an EXEC that runs in a VM system, and invokes two programs. The second program runs in a separate CMS Work Unit. After it has completed, the SQLRMEND EXEC is invoked with the COMMIT ALL option, which commits the logical units of work active in each program, drops both links, and frees the storage used by the resource adapter.

   *
   *
   *
EXEC SQLINIT DB(DB01)     <Set up access to DB01 in first work unit
SQLPROG1                  <Run program that accesses DB01
EXEC SQLINIT DB(DB02)     <Set up access to DB02 in second work unit
SQLPROG2                  <Run program that accesses DB02
EXEC SQLRMEND COMMIT ALL  <commits both logical units of work, drops
                                 both links, and drops resource adapter

The SQLINIT EXEC is invoked to switch application servers for the second program.

ARISDBHD EXEC

The ARISDBHD EXEC deletes SQL/DS HELP text, including administrator supplied topics, for one or more languages. It does not delete the message repository.

To run the ARISDBHD EXEC, you must have:

Read access to the SQL/DS service minidisk or SFS directory
Read access to the SQL/DS production minidisk or SFS directory
The connect password for SQLDBA.

>>-ARISDBHD----Dbname(dbname)----------------------------------><

The parameters of the ARISDBHD EXEC are as follows:

Dbname(dbname): Replace dbname with the name of the database in which the HELP text is to be deleted.

When you run the ARISDBHD EXEC:

Specify which HELP text languages to delete.
Confirm that you want to delete the HELP text for the specified languages.
Execute the delete procedure.

Step 1

When you invoke the ARISDBHD EXEC, you will be prompted for the connect password for SQLDBA. After entering the password, the contents of the SYSLANGUAGE table are reformatted and displayed. Specify the language key for each language whose HELP text you wish to delete (separated by commas or blanks) or ALL to specify all HELP text for all languages in the database.

If you decide to stop the procedure at this point, enter QUIT.

Each time you select a language, it is flagged on the screen; a null entry will process your selections.

Step 2

The languages that you indicated for deletion are displayed on the next screen. Confirm that you want to delete all these languages by entering YES. To exit from the procedure without deleting any HELP text languages, enter NO.

Step 3

When prompted, enter the owner ID and virtual address of the CMS HELP text for the language specified.

If you know that there is no CMS HELP text for the language specified, enter SKIP to bypass the language.

If you accidentally delete the CMS HELP text for a different language by entering the wrong virtual address, you can restore the environment by executing the ARISDBMA EXEC for the deleted language and rerunning this EXEC with the correct address.

If you wish to delete an entire language (both the messages and the HELP text), use the ARISDBLD EXEC instead. The ARISDBHD EXEC deletes both ISQL help and CMS help. This EXEC displays a list of currently installed languages, which may contain languages that have already had their help deleted but are still active (that is, are listed in the SYSLANGUAGE table and have the appropriate message repository available). You will be prompted to select the HELP text languages for deletion. You should not specify languages whose HELP text has already been deleted. Since this EXEC cannot be used to delete a message repository, the SYSLANGUAGE table and the ARISNLSC MACRO will not be updated in any way. This EXEC will not affect the default language setting.

ARISDBLD EXEC

The ARISDBLD EXEC deletes the SQL/DS messages and HELP text, including administrator supplied topics, for one or more languages.

To run the ARISDBLD EXEC, you must have:

Read access to the SQL/DS service minidisk or SFS directory
Read access to the SQL/DS production minidisk or SFS directory
The connect password for SQLDBA.

>>-ARISDBLD----Dbname(dbname)----------------------------------><

The parameters of the ARISDBLD EXEC are as follows:

Dbname(dbname): Replace dbname with the name of the database in which the messages and HELP text are to be deleted.

When you run the ARISDBLD EXEC it prompts you to:

Specify which languages to delete
Determine which is to become the new default language, if the current default language is to be deleted, and two or more languages will remain on the system
Confirm that you want to delete the messages and HELP text for the specified languages.

Step 1

When you invoke the ARISDBLD EXEC, you will be prompted for the connect password for SQLDBA. After entering the password, the contents of the SYSLANGUAGE table are reformatted and displayed. Specify the language key for each language whose HELP text you wish to delete (separated by commas or blanks).

If you decide to stop the procedure at this point, enter QUIT.

Each time you select a language, it is flagged on the screen; a null entry will process your selections.

Step 2

To delete the current default language with two or more languages remaining on the system, you must specify which of the remaining languages will be the new default language. When the current default language is flagged for deletion, a list of the remaining languages and keys is displayed. Specify the key for the new default language.

If only one language remains on the system, it will automatically become the new default language.

Step 3

The languages that you flagged for deletion are displayed on the next screen. Confirm that you want to delete all these languages by entering YES. To exit from the procedure without deleting any HELP text languages, enter NO.

Step 4

When prompted, enter the owner ID and virtual address of the CMS HELP text for the language specified.

If you know that there is no CMS HELP text for the language specified, enter SKIP to bypass the language.

A minimum of one language must be left on the ARISNLSC macro and the SQLDBA.SYSLANGUAGE table; it is not possible to delete all the languages.

For each language being deactivated, the following occurs:

The ARISNLSC MACRO is updated. If the current default language has been marked for deletion, you must specify a new default language.
The message repository for this language is deleted from the production minidisk or directory.
The ISQL HELP text is deleted by updating the SYSTEXT2 table.
The ARISDBMC EXEC is invoked to delete CMS help.

SQLLEVEL EXEC

The SQLLEVEL EXEC displays the SQL/DS release level that is installed. For example:

*** SQL/DS VERSION 7 RELEASE 1 MODIFICATION 0 ***

To run the SQLLEVEL EXEC, you must have:

Read access to the SQL/DS service minidisk or SFS directory
Read access to the SQL/DS production minidisk or SFS directory.

>>-SQLLEVEL----+---------+------------------------------------->< '-RELMOD--'

The parameters for the SQLLEVEL EXEC are as follows:

RELMOD: If you include this parameter, the EXEC places the version, release, and modification levels in the CMS stack. (These values are all integers.)

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]