This section discusses the following topics:
Each database machine has its own operator console called the DB2 Server for VM operator console. The user who operates this console is referred to as the database operator.
When more than one database machine is active, there is more than one database operator console. With VM facilities, a single person can operate many database machines.
For example, one person can operate many database machines by running the virtual machines disconnected. This common operator can reconnect to the various machines as needed.
Another way to have one operator is to use the VM Single Console Image Facility or the Programmable Operator Facility. These facilities allow the VM system operator to operate all the database machines. To learn more about the single console image facility and the programmable operator facility, refer to the VM/ESA: CP Programming Services or the VM/ESA: Planning and Administration manuals.
The database manager can operate in one of two modes: multiple user mode, or single user mode.
In multiple user mode, one or more users or applications concurrently access the same database. The database manager runs in a virtual machine while one or more applications run in other virtual machines. Users specify the database they want to access by running the SQLINIT EXEC. This EXEC establishes a default database for each user. For example, a user who first wants to access a database called TEST, then use ISQL, would enter:
SQLINIT DB(TEST) ISQL
The initialization parameter SYSMODE=M defines this mode.
In single user mode, the database manager and only one application program run in the same virtual machine. The application server is started, the program name is passed as a parameter to the database manager, the application is run, and the application server terminates. The initialization parameter SYSMODE=S defines this mode.
Figure 8 identifies the initialization parameters that apply when the database manager is operating in multiple user mode, and lists their defaults. A discussion of the appropriate settings for these parameters follows.
Figure 8. Multiple User Mode Initialization Parameters
A database machine can own more than one database. When starting the application server, specify the name of the database that is to be accessed by the database machine. Note that DBNAME is not specified in the parameter list of the SQLSTART command as an initialization parameter. Figure 9 shows the DBNAME parameter specified correctly.
This parameter specifies the name of the bootstrap package to be used. It is not needed if saved segments are not being used. For more information on saved segments and specifying the DCSSID parameter, see Chapter 8, Saved Segments. Figure 9 shows the DCSSID parameter specified correctly. For more information on the use of this parameter, see Starting the Application Server in Multiple User Mode.
This parameter specifies the type of addressing the database manager runs in: 31-bit addressing or 24-bit addressing. Note that AMODE is not specified in the parameter list of the SQLSTART EXEC as an initialization parameter. Figure 9 shows the AMODE parameter specified correctly. For more information on the use of this parameter, see Starting the Application Server in Multiple User Mode.
This parameter is used to specify either single(S) or multiple(M) user mode. Set it to M to initialize the database manager for multiple user mode operation. This is the default mode. You will NOT normally specify this parameter as SQL EXECs set this parameter for you automatically.
This parameter specifies how the database will be started:
For more information, see Restoring the Database.
This parameter can be used to specify a CMS file containing the values for the other initialization parameters. Application program parameters (user parameters) cannot be included. Specify only the file name for PARMID. The database manager assumes that the file type is SQLPARM and the file mode is *. The * tells CMS to search all accessed minidisks (A to Z). Figure 9 shows an example startup that uses the PARMID parameter.
Figure 9. Starting in Multiple User Mode with a CMS File
SQLSTART DBNAME(SQLDBA) DCSSID(MYBOOT) AMODE(31) PARM(PARMID=WARM1,LOGMODE=A) |
This parameter identifies the database name as a LOCAL resource (DBMODE=L),
a GLOBAL resource (DBMODE=G), or non-APPC/VM (DBMODE=N) for a particular session. If the DBMODE parameter is not specified, the resource authorization specified in the VM directory of the database machine is used. Consider the following when specifying the DBMODE parameter:
For more information about directory entries, see VM Directory Control Statements.
This parameter specifies the types of protocols that the application server can handle. It has two options on the SQLSTART EXEC: SQLDS and AUTO.
When PROTOCOL=SQLDS is specified, the DB2 Server for VM application server allows access from DB2 Server for VM application requesters only. These application requesters and application server can be in either a local or remote environment. This option is the default.
When PROTOCOL=AUTO is specified, the DB2 Server for VM application server allows access from DB2 Server for VM and non-DB2 Server for VM application requesters. This parameter can only be specified if the DRDA code has been installed. It is used with the SYNCPNT parameter to control the DRDA environment. For more information, see the description of the SYNCPNT parameter and see Chapter 15, Using a DRDA Environment.
On the application server, the PROTOCOL parameter is specified using the SQLSTART EXEC. On the application requester, the SQLINIT EXEC also has a PROTOCOL parameter. When a connection is made between the application requester and the application server, the combination specified by these parameters determines whether the DRDA protocol or the SQLDS protocol is to be used for that connection.
You should be aware of the performance impacts of the chosen protocol. For a detailed explanation on protocols, see the DB2 Server for VSE & VM Performance Tuning Handbook.
For a list of restrictions when using the DRDA protocol, see Appendix H, DRDA Considerations. For information on the SQLINIT EXEC, see the DB2 Server for VSE & VM Database Administration manual.
This section discusses the following:
Use the CHARNAME parameter to specify the CCSIDs to be used as the application server defaults. The default CCSIDs determine the character sets and code pages to be used to interpret statements and return results.
The valid CHARNAME values you can specify are ENGLISH (CCSID=37), INTERNATIONAL (CCSID=500), and all the values that are in the CHARNAME column of the SYSTEM.SYSCCSIDS catalog table.
The database manager obtains the CCSIDs associated with the CHARNAME by looking up the row of the SYSTEM.SYSCCSIDS catalog table where the CHARNAME column matches the CHARNAME parameter. It also obtains the classification and translation tables associated with the CHARNAME by looking up the row of the SYSTEM.SYSCHARSETS catalog table where the NAME column matches the CHARNAME parameter. The classification table is used to identify valid characters in identifiers. The translation table is used to indicate how to fold ordinary lowercase identifiers to uppercase.
For CHARNAMEs ENGLISH and INTERNATIONAL, their CCSID values, the classification table and the translation table are stored internally. The rows in SYSTEM.SYSCCSIDS and SYSTEM.SYSCHARSETS for these CHARNAMEs are for reference purposes only and are not used by the database manager.
During startup, if you do not specify the CHARNAME parameter, the application server uses the same CHARNAME that was used the last time it was started. The values stored in the rows where SQLOPTION equals CHARNAME, CCSIDSBCS, CCSIDMIXED, and CCSIDGRAPHIC are for reference purposes only. They reflect the current values associated with the system. The only way to change the default values is by starting the application server with a different CHARNAME parameter. Any updates to the values in the SYSTEM.SYSOPTIONS table are ignored during startup.
When you specify a value for the CHARNAME parameter that is different from the current application server default CHARNAME, you are prompted to choose whether or not you want to change the application server default CHARNAME. If you specify YES and have supplied a valid CHARNAME value, the database manager updates the application server default values for CHARNAME, CCSIDSBCS, CCSIDMIXED, and CCSIDGRAPHIC.
It also modifies the CCSID attribute of all character columns that are part of the catalog tables to the application server default CCSID. The CCSID attribute of character columns that are not part of the catalog tables are not modified. If the value for CCSIDMIXED is not zero, this value is used as the application server default CCSID. If the value for CCSIDMIXED is zero, then the application server default CCSID is the value of CCSIDSBCS.
Note that the tables which have their CCSID modified when the CHARNAME is changed include:
When a CHARNAME is changed, the following should be considered:
The following query lists all such view packages:
SELECT CREATOR, TNAME, PLABEL
FROM SYSTEM.SYSACCESS
WHERE TABTYPE = 'V'
AND VALID = 'N'
This query is useful in that owners of affected views can be notified to drop and recreate their view before they try and use the view and get an error (SQLCODE=-835, SQLSTATE=56049, with SQLERRD1 set to -833).
The following query lists all such packages:
SELECT CREATOR, TNAME, PLABEL
FROM SYSTEM.SYSACCESS
WHERE TABTYPE = 'X'
AND VALID = 'N'
This query is useful in that owners of affected packages can be notified to rebind the packages instead of having them dynamically repreprocessed at run time. The DBS utility REBIND PACKAGE command can be used to rebind the packages listed.
To check if all the above activities have been done, run the following query:
SELECT CREATOR, TNAME, PLABEL
FROM SYSTEM.SYSACCESS
WHERE VALID = 'N'
If there are no rows found, all packages have been either recreated, reloaded, rebound or dynamically repreprocessed and the VALID column value for the package in SYSTEM.SYSACCESS has been changed to "Y".
Note that CCSID conversion of the data in catalog tables does not occur: only the CCSID attribute of the columns is modified. If you change the application server default CHARNAME, system objects of the character data type (for example, table names and column names) stored in the catalog may be displayed differently. The reason for this is that a code point may represent different characters in different code pages.
If you want to change the application server default CHARNAME, the default will not be changed if:
When the application server is started, it records the application server default values for CHARNAME, CCSIDSBCS, CCSIDMIXED, and CCSIDGRAPHIC in the SYSTEM.SYSOPTIONS catalog table. To obtain these values, you can query the table. For example, to determine the name of the character set that is currently in use, issue:
SELECT VALUE
FROM SYSTEM.SYSOPTIONS
WHERE SQLOPTION = 'CHARNAME'
For more information about character sets, see Chapter 13, Choosing a National Language and Defining Character Sets.
You can use the SET LANGUAGE command from the operator console to choose a national language so that DB2 Server for VM messages can be received in the selected language. For more information see National Language Support for Messages and HELP Text.
This parameter enables the accounting facility. When ACCOUNT=D is specified, accounting records are generated and directed to the VM system accounting file. If the default value of ACCOUNT=N is specified, accounting information is not generated.
For a complete description of the accounting facility, see Chapter 11, Using the Accounting Facility.
This parameter specifies whether or not a sync point manager (SPM) will be used to coordinate DRDA2 DUOW two-phase commit and resynchronization activity. It is only meaningful when PROTOCOL=AUTO.
If Y is specified, the server will use a sync point manager, if possible, to coordinate two-phase commits and resynchronization activity. If N is specified, the server will not use an SPM to perform two-phase commits. If N is specified, the database manager is limited to multi-read, single-write distributed units of work and it can be the single write site. If Y is specified, but the database manager finds that a sync point manager is not available, then the server will operate as if N was specified.
The default is SYNCPNT=Y, if PROTOCOL=AUTO.
This two digit parameter specifies what information is displayed and what level of detail is displayed. If 0 is specified, nothing is displayed. If 1 is specified, the minimum information is displayed. If 2 is specified, more detail is displayed. The positional digits correspond to the following informational displays: the first is checkpoint performance information and the second is counter information to be displayed at system shutdown.
If the first option is 1, then format 1 of message ARI2052I is displayed every time a checkpoint occurs. This is useful in determining how often checkpoints occur. If the first option is 2, then format 2 of message ARI2052I is displayed every time a checkpoint occurs. This is useful in determining if checkpoint processing is causing a performance problem.
If the second option is 1, then the "COUNTER *" operator command is issued just before the application server is shutdown. This is useful for performance tuning. If the dataspaces feature is being used, "COUNTER POOL *" command is also issued.
The SET command changes the value of this parameter without having to stop and restart the application server. For more information on the SET operator command, see the DB2 Server for VSE & VM Operation manual.
This parameter determines if the application server will accept users that have already been verified by another system. If SECALVER=Y, verified users will be accepted. The requester only needs to send a user ID to be validated. If SECALVER=N, verified users will not be accepted. The requester must send a user ID and password to be verified.
| Note: | This parameter is only used when validating users are connecting via TCP/IP or when users send the ACCSEC and SECCHK DRDA datastreams in their connect request. |
This parameter determines if the application server will validate a user ID and password for connect authority using an external security manager or by checking the DB2 SYSUSERAUTH catalog table. If SECTYPE=ESM an external security manager will be used to validate the user ID and password. The external security manager must support the RACROUTE application programming interface. If SECTYPE=DB2, the user ID and password are validated by checking the SYSUSERAUTH catalog table.
| Note: | This parameter is only used when validating users are connecting via TCP/IP or when users send the ACCSEC and SECCHK DRDA datastreams in their connect request. |
This parameter specifies the TCP/IP port number that the application server will use to listen for incoming TCP/IP connect requests.
If this parameter is not specified, TCP/IP support will be initialized and the ETC SERVICES file on the TCP/IP client disk will be searched to determine the port number that the application server will use.
If this parameter is specified with a non-zero value, TCP/IP support will be initialized and the value specified will be used as the port number that the application server will use.
If this parameter is specified with a value of 0, TCP/IP support will not be initialized.
This parameter defines the maximum number of real agents that the database manager can actively handle at any one time, limiting the number of users that can be supported by the database manager. The value of NCUSERS is usually less than the number of connected users anticipated, because not all users will be accessing data at the same time. This value directly affects the size of the virtual machine required.
The number of NCUSERS is limited because some static agent storage for each real agent is obtained below 16 megabytes. See Table 37.
Figure 10 provides guidelines for setting the NCUSERS parameter. Because these are only guidelines, you should modify them to concur with the activity on your system. For additional information, see the DB2 Server for VSE & VM Performance Tuning Handbook.
Figure 10. Guidelines for the NCUSERS Parameter
NCUSERS= 1 for each 1-2 users of ISQL (or other query products)
+ 1 for each 1-25 non-ISQL users
(variable on transaction workload)
+ 1 for each 2-5 application program developers
|
If you have application programs that maintain multiple logical units of work in separate CMS work units, each additional work unit used by an application at one time must be counted as an additional user.
Each ISQL user can generate a high level of system activity. If you set NCUSERS so that all ISQL users can be active at the same time (NCUSERS=number of ISQL users), you minimize the time that any one user must wait for services. However, if this number is large, it may cause the database manager to be overloaded. To prevent this, you should also set the MAXCONN parameter of the VM OPTION directory control statement, which limits the number of users and the number of DASDs that a given virtual machine can access. For information on this parameter, see Inter-Machine Communications.
Application developers typically do a considerable amount of other activity (such as CMS file editing or output scanning). These users require less service from the database manager, so NCUSERS can be lowered accordingly.
If you are using VSE guest sharing, the NCUSERS of the VM database machine should be increased by the number required for the VSE guest. The demand for services from CICS transaction processing can vary widely, depending on the nature of the transactions.
The demand for services from batch application programs can also vary considerably. If you have online or interactive activity on the database manager, consider limiting the amount of concurrent SQL batch processing.
| Note: | When the application server is started, there may be one or more in-doubt logical units of work (LUWs). The value of NCUSERS must be large enough to handle these. When they have been resolved, the DB2 Server for VM agent structures are used to handle new users. The creation and use of agent structures for resolving in-doubt LUWs takes precedence over all new user logical units of work. For more information about in-doubt LUWs, see Resolving In-Doubt Transactions. |
This parameter defines the maximum number of packages in an LUW, and together with the value specified for NCUSERS, determines the size of the package cache. The size of the package cache limits the number of packages that can be present in storage simultaneously. (Package cache size = NPACKAGE x NCUSERS.) The default value of NPACKAGE is 10, and that for NCUSERS is 5, giving a default package cache of 50, allowing 50 packages to be present in storage simultaneously.
In general, increasing the size of the package cache improves performance of the database manager. However, do not increase it to the point where system paging becomes too great. For more information, see the DB2 Server for VSE & VM Performance Tuning Handbook.
This parameter defines the percentage of the package cache that is used in the calculation of the package cache threshold. The size of the threshold determines the number of loaded packages that are kept in storage at the end of an LUW. (Threshold = NPACKPCT percent of package cache.) If the threshold is exceeded, the loaded packages are freed and returned to the package cache.
The default values for NPACKPCT and the package cache are 30 and 50 respectively, giving a threshold of 15. In general, increasing the size of the threshold improves performance. For more information, see the DB2 Server for VSE & VM Performance Tuning Handbook.
This parameter specifies the number of 4096-byte data pages kept in storage buffers at one time. The number of data buffers you want depends on the number of active users and the nature of their request. The default for NPAGBUF assumes an average of four buffer pages for each potentially active user (NCUSERS x 4), plus ten buffer pages for the buffering of catalog and log information.
In general, increasing NPAGBUF improves the performance of the database manager. However, increasing it also requires an increase in the size of the database machine. Also -- and more importantly -- it can cause an increase in the paging rate of the system. It is more efficient to let the database manager do more I/O operations than it is to let the system do more paging; database I/O operations are overlapped whereas system paging operations are not. Therefore do not increase NPAGBUF to the point where system paging becomes too great.
For more information about NPAGBUF, see the DB2 Server for VSE & VM Diagnosis Guide and Reference manual.
This parameter determines the number of 512-byte directory pages to be kept in storage. Increasing it reduces the number of I/O operations. Again, bigger is better, until you either run out of virtual storage or cause too much system paging. Each directory page addresses 128 data pages.
When you set NPAGBUF and NDIRBUF, you have to choose how to split buffer space between data pages and directory pages. At least initially, you should set them to the same value. Issue the COUNTER commands to see the actual I/O activity; then adjust NPAGBUF and NDIRBUF.
For more information about NDIRBUF, see the DB2 Server for VSE & VM Diagnosis Guide and Reference manual.
NLRBU specifies the maximum number of lock request blocks allowed for one active user, while NLRBS specifies the number allowed for all active users. (Usually, two lock request blocks are used for every lock that a user holds.)
The database manager can perform lock escalations, increasing the granularity of data being locked from either row or page level to dbspace level. In general, you only need to change the default values of NLRBU and NLRBS if contention problems occur. Increasing them reduces the number of lock escalations performed by the database manager.
When either the NLRBU limit for a user is reached or the NLRBS limit is approached, lock escalation occurs. This results in fewer locks being required, and lock request blocks being freed. This in turn reduces the opportunities to share data. For example, when locking is done at a row level, many users may be updating the same dbspace at the same time. When it is escalated to the dbspace level, only one user can update rows in that dbspace. Everyone else must wait until that person's update is committed or rolled back.
Escalation can also cause deadlocks. A deadlock occurs when two or more LUWs are in wait states and dependent on the completion of LUWs that are also in wait states. For example, suppose two users are updating tables in a dbspace. When the lock size is escalated to a dbspace level, both users can be locked out, with each waiting for the other to complete an LUW. The database manager resolves situations like these by rolling back the newest LUW. For more about locking, see the DB2 Server for VSE & VM Application Programming manual.
If the default values for NCUSERS (5) and NLRBU (1000) are used, the database manager defines 2520 lock request blocks, each of which requires 24 bytes; 60480 bytes of virtual storage are required for lock request blocks. With these defaults, one application could use 1000 lock request blocks and four other applications could simultaneously use an average of 370 lock request blocks each, before causing an escalation.
Even though two lock request blocks are needed for each lock, the default values allow a large number of locks for each application. With the defaults, one application could use 500 locks while four other applications use an average of 185 locks each.
You should use the NLRBU and NLRBS default values at first, and increase them if users either are experiencing delays when they access the database manager, or if they are receiving SQLCODEs of -911, -912, or -915 (rollbacks that occur because of deadlock, insufficient lock request blocks for the database manager, or insufficient lock request blocks for a user application, respectively).
| Note: | These SQLCODEs may also be received during preprocessing, as the locks are required then as well. |
To test the frequency of lock escalations and of deadlocks, use the COUNTER operator command. Specify both the ESCALATE and the LOCKLMT counters to get the number of successful escalations and the number of unsuccessful escalation attempts respectively. (An escalation can fail if the LUW that reached the lock limit is rolled back because of a deadlock, or if a sufficient number of lock request blocks cannot be freed.) For example, suppose the operator issues the command COUNTER ESCALATE LOCKLMT a few times a day and normally receives results in the range of 10 to 150 for ESCALATE, and 0 to 5 for LOCKLMT. If, one day, the results are 428 for ESCALATE and 23 for LOCKLMT, a locking problem would be indicated.
In addition, the SHOW LOCK MATRIX command can be used to display information about lock request block usage to determine whether unexpected delays are caused by locking; to monitor how the database manager is using lock request blocks; and to determine the lock request blocks required for a single application or for a run of a preprocessor.
One of the values displayed is called MAX USED BY LUW: the maximum number of lock request blocks used by any one application during an LUW. (When any LUW starts to exceed NLRBU and the escalation process occurs, MAX USED BY LUW is set to zero.) All this information can help you determine the required values for NLRBU and NLRBS.
To establish the lock request block requirements for running a preprocessor, or for an application that is causing contention problems:
If necessary, reset NLRBS. For example, suppose NLRBU is set to 1100, and two users will run their applications -- each requiring 1100 lock request blocks -- at the same time. Also assume that any other application requires about 500 lock request blocks. If NCUSERS is 5, then set NLRBS to at least 3700 (1100 for each of two applications and 500 for each of three additional applications).
If an application requires more lock request blocks than you have virtual storage for, you should consider the following alternatives:
For more information about locking problems and how to solve them, see the DB2 Server for VSE & VM Diagnosis Guide and Reference manual.
This parameter determines how the dispatcher selects the order in which agents get serviced by the database manager.
To set it, you need to understand how the dispatcher works. Only one agent at a time can be serviced; the other agents wait in a queue. Within this queue, agents are prioritized according to their estimated resource consumption: those estimated to consume the least are placed at the top, while those estimated to consume the most are placed at the bottom.
When the active agent returns to the dispatcher, the next agent at the top of the queue is dispatched. Every time an agent is dispatched, the database manager reevaluates the priority of the remaining agents, and requeues them according to their new priorities.
A pure priority dispatcher can present some problems, however. If many short-running LUWs are present, the longer-running ones may never get serviced: they are always at the bottom of the queue. To avoid this problem, fair-share auditing is used, whereby all the agents in the queue are checked periodically to see if they are receiving adequate service. When one is found that is not, its priority is changed and it is moved to the top of the queue.
If fair-share auditing is done frequently, the dispatcher tends to operate more like a round-robin dispatcher: agents get equal service because those at the bottom of the queue get bumped to the top more frequently. If it is done infrequently, the dispatcher tends to operate more like a priority dispatcher: agents get prioritized service because long-running agents are forced to wait at the bottom of the queue longer. (Eventually, fair-share auditing causes these agents to get service.)
The DISPBIAS parameter determines how often fair-share auditing is done. When it is set low (near 1), fair-share auditing is done frequently, and the dispatcher operates more in round-robin mode. When it is set high (near 10), fair-share auditing is done infrequently, and the dispatcher operates more in priority mode.
Initially, you should use the DISPBIAS default of 7. If your long-running LUWs are getting poor service, you may want to use a lower value; if your ISQL users are often waiting for long-running applications to complete, you may want to use a higher value. You can use the SET operator command to change the value of DISPBIAS without having to stop and restart the application server. See the DB2 Server for VSE & VM Operation manual for more information on the SET operator command.
| Note: | Any changes you make using the SET command are only in effect while the application server is running. If you stop and restart the application server, it will use the settings you specified in the startup procedure. |
You may be tempted to set DISPBIAS to 10 to get good response time for ISQL users. Keep in mind, however, that a long-running LUW can hold a large number of locks. If other users are waiting for those locks, they must wait until the application frees them. If the application is waiting at the bottom of the queue, everyone is waiting. In this situation, you would want to have fair-share auditing occur more frequently, so the long-running unit can free the resources it has locked. The default of seven represents a balance between the interests of long-running and short-running LUWs.
This parameter determines the number of internal control scan blocks kept for accessing tables and indexes. These blocks can vary in size and number depending on the type of query being performed. This discussion is concerned with long-running requests that might be queries or database change operations.
Scan control blocks contain positioning information related to a query. The positioning information can result from a user-defined cursor or by an internal cursor created by RDS. If an index is involved in the query, the size of the scan control block depends on the key size for that index. An average scan control block is assumed to be 50 bytes (32 bytes for control information, and an average key length of 18 bytes).
The maximum table size to hold the scan control block entries for each agent is 32 kilobytes (32768 bytes). This can contain 655 entries of 50-byte scan control blocks, which in general, is enough to support 255 user-declared cursors. If, however, the key lengths for indexes are long, the scan table supports fewer user cursors. For example, if the key length for a given index associated with a cursor is 255 bytes, an entry would require 287 (255 + 32) bytes, and the maximum number of cursors possible using that index would be 114 (32 kilobytes divided by 287). That number would be reduced if the DB2 Server for VM requests caused internal cursors to be created. Internal cursors are always smaller than 50 bytes, and cannot use index keys.
If you have many complex requests, you may have to increase NCSCANS. If it is not set to a high enough value, users will get SQLCODE -522. For information on the virtual storage used by NCSCANS, see Initial Virtual Storage Requirements of Components.
This parameter specifies a general lock wait timeout period for any SQL application, and especially as the way to avoid global deadlocks for DUOW applications.
The range of the LTIMEOUT value is 0 to 99999 seconds. The value of zero indicates that no lock timeout should be enforced for agents connected to this database. This is the default value for a database.
A nonzero lock timeout value will cause any agents waiting for a lock to have their current transaction rolled back when the lock timeout period has expired. The agent will notify the application that a lock timeout has occurred with SQLCODE -911 (SQLSTATE 40001). A reason code will be returned to indicate whether it is a deadlock or lock timeout situation (reason code 2 for a deadlock situation and reason code 68 for a lock timeout situation). The lock timeout period begins at the moment an agent requests a lock on any database resource. The full lock timeout period is allowed for each lock request.
The lock timeout control parameter should be adjusted in those environments where lock contention between applications has started to affect the desired performance and concurrency levels.
If a lock timeout is required for your environment, it is recommended that your starting value be equivalent to the maximum period of time that you want an application to wait for a lock.
| Note: | The LTIMEOUT parameter is changed through the SET operator command. The timeout value will affect any users currently in LOCK WAIT. If a user has been in a LOCK WAIT for 100 seconds and the value of LTIMEOUT is set to a value less than 100, that user will receive a timeout. For more information on the SET operator command, see the DB2 Server for VSE & VM Operation manual. |
If lock timeout control is activated, you should ensure that all applications recognize and can handle the -911 SQLCODE that may be received as the result of a lock timeout initiated rollback.
| Note: | New units of work that are waiting to begin because a log archive is running or is scheduled to run are in a lock wait. The SHOW LOCK WANTLOCK operator command shows these units of work waiting to acquire an IX lock on the database. Because log archives can potentially take a significant amount of time to complete, units of work in this particular type of lock wait are ignored by the lock timeout function. |
This parameter specifies the number of times a stored procedure is allowed to terminate abnormally, after which a STOP PROC ACTION REJECT is performed against the procedure and all subsequent SQL CALL statements for that procedure are rejected. Note that a timeout that occurs while waiting for a stored procedure server to be assigned for an SQL CALL statement is not included in this count.
PROCMXAB must be an integer between 0 and 255. The default, 0, means that the first abend of a stored procedure causes SQL CALLs to that procedure to be rejected. For production systems, you should accept the default.
This parameter specifies:
The default for PTIMEOUT is 180.
This parameter determines whether archives will be taken for the database and the log. Specify LOGMODE=A to maintain an archive of the database, LOGMODE=L to maintain an archive of the log, and LOGMODE=Y if you want logging but do not want the log archived.
LOGMODE=A allows you to restore the database and apply the current log. LOGMODE=L allows you to maintain a database archive as well as log archives. The database archive followed by the log archives are applied during restore, then the current log is applied.
Use LOGMODE=A or L if it is important to protect the database against media (DASD) failures; otherwise use LOGMODE=Y.
| Note: | Each sequence of log archives must be preceded by a database archive, so if you use LOGMODE=L, you must occasionally take a database archive. You do not need to switch to LOGMODE=A to do so. |
For more information on LOGMODE, see Choosing a Log Mode.
This parameter determines how often a checkpoint is taken. A checkpoint is an internal operation in which data and status information is written to permanent (DASD) storage, and a summary status record is written to the log. A checkpoint causes two important events:
As updates to data occur, duplicate copies of changed data pages are maintained. These copies (called shadow pages) are kept in the storage pools of the pages that were changed. A checkpoint frees the shadow pages, and thereby frees the storage pool space where they are kept.
If LOGMODE=Y, a checkpoint typically frees log space by moving the logical beginning of the log forward to the beginning of the oldest LUW still active at the time of the checkpoint. If LOGMODE=A or L, log space is only freed when an archive is taken; not on every checkpoint.
Checkpoints are taken periodically: however, by the time one is taken, there may be a large amount of data to be committed. If a failure should occur before it is committed, much processing may need to be redone after the database is restored.
The CHKINTVL parameter lets you take checkpoints at predetermined intervals. Its value is specified in terms of the number of log pages written between checkpoints. You can use the SET operator command to change the value of CHKINTVL without having to stop and restart the application server. See the DB2 Server for VSE & VM Operation manual for more information on the SET operator command.
By setting it low, you minimize the risk of filling the log or storage pools. However, because checkpoints are time-consuming operations that suspend SQL processing until they are completed, they should be taken infrequently. For more information on setting CHKINTVL, see the DB2 Server for VSE & VM Performance Tuning Handbook.
This parameter defines the point at which the log cushion is entered and log-full processing begins. Its value is expressed in terms of the percentage of the log size. The default of 90 means that when the log is 90% full, log-full processing will be initiated.
In log-full processing, the oldest active LUWs are rolled back until enough log space is freed to bring the percentage of the log in use below the SLOGCUSH level. Ideally, checkpoints and archiving would continually free log space so that the log would never reach the SLOGCUSH level.
If the log should become 100% full, the database manager would end abnormally, so you should set SLOGCUSH to a value that allows log-full processing to take effect (free some log space) before this happens. If the database manager is ending with log-full conditions, you may want to lower the SLOGCUSH value or increase the size of your log minidisks.
This parameter can be used to define a point at which an archive is automatically initiated.
It is used only when LOGMODE=A or L is specified. Like SLOGCUSH, its value is expressed in terms of a percentage of the log.
Archives free up log space; however, they take some time to complete. If the SLOGCUSH value is reached during an online archive operation, all SQL processing is suspended until the archive is done. For this reason, it is best to ensure that archives are initiated in time to finish before the log fills to the SLOGCUSH percentage. This is done by setting the value of ARCHPCT lower than the value of SLOGCUSH.
When the log becomes full to the ARCHPCT value, a message is issued to the database machine operator to mount an archive tape and identify the virtual address (cuu) of the tape drive. The database manager then takes a database or log archive depending on whether you have LOGMODE set to A (database) or L (log).
If LOGMODE=L, the operator can also direct the log archive to disk. For more information, see Log Archiving to Disk.
Normally, the operator explicitly archives the database or the log before the ARCHPCT value is reached, by issuing one of the archive commands. If the ARCHPCT is reached, meaning that the log is almost full, the action that the database manager takes depends on the LOGMODE that is in effect. See
Table 5 for a summary of these actions.
Table 5. Summary of Activity When ARCHPCT Level Is Reached
| LOGMODE Parameter | Activity When ARCHPCT is Reached |
|---|---|
| A | An operator message is issued that requests a database archive. |
| L | An operator message is issued that requests a log archive. |
| Y | Because the log cannot be archived, the value for ARCHPCT is ignored. When the log is full it wraps. If an LUW spans the entire log, a ROLLBACK WORK is forced for that LUW. |
| Note: | To see how full the log is, you can issue the SHOW LOG command. For a description of this command, see the DB2 Server for VSE & VM Operation manual. |
This parameter defines the storage cushion for storage pools.
Its value is expressed as a percentage of space remaining in a storage pool. In multiple user mode processing (and single user mode processing where LOGMODE is not N), if any storage pool gets full to the point where only the SOSLEVEL percentage of storage pool pages is still free, a checkpoint is taken to free any shadow pages in use.
If, following this, only enough pages are freed to bring the number of free pages just above the SOSLEVEL, frequent checkpointing could occur. For more information, see the DB2 Server for VSE & VM Diagnosis Guide and Reference manual. If, however, the number of free storage pool pages is still at or below SOSLEVEL, message ARI0202I is issued once to inform the user that the number of free pages left in the storage pool is fewer than the SOSLEVEL. This message is also issued once in single user mode with LOGMODE=N, but no checkpoint is taken.
Attention: If message ARI0202I is received, it indicates some action may be needed to prevent imminent filling of the storage pool.
One possible action is to stop the application server and extend that storage pool with the SQLADBEX EXEC. However, you can remedy the situation without stopping the application server if you have set SOSLEVEL high enough to give you adequate warning. When the message is received, proceed to remove unneeded data from the storage pool, either by dropping dbspaces or tables, or by reorganizing the data with a smaller percentage of free space for each page. In order to do this, you must have adequate warning to schedule the necessary processing.
This parameter defines whether or not dumps are to be taken, and the amount of information to be dumped if they are.
DUMPTYPE=N indicates that a dump is not taken.
DUMPTYPE=F gives you a full dump of the virtual machine, as well as any saved segments it uses. This occurs on some error conditions and trace points.
DUMPTYPE=P gives you a partial dump of the database machine on certain error conditions. A dump is not taken when a limit error (message ARI0039E) or hardware error (message ARI0041E) occurs, or when a user specification error is detected.
(If you specify the DUMP keyword in the TRACE ON command, DUMPTYPE=P also generates partial dump output to the trace file for a specified trace point in the database manager.) The partial dump provides a dump of control blocks and other dynamically obtained virtual storage in the database machine.
You can use the SET operator command to change the value of DUMPTYPE without having to stop and restart the application server. See the DB2 Server for VSE & VM Operation manual for more information on the SET operator command.
| Note: | Any changes you make using the SET command are only in effect while the application server is running. If you stop and restart the application server, it will use the settings you specified in the startup procedure. |
For more information on dumps, see the DB2 Server for VSE & VM Diagnosis Guide and Reference manual.
This parameter specifies whether or not special recovery commands are processed at startup.
Only set it to Y when you have a DBSS processing error or a severe user error. For more information on this parameter, see the discussion on starting the application server to recover from DBSS errors in the DB2 Server for VSE & VM Diagnosis Guide and Reference manual.
call the trace facilities during startup (as opposed to the TRACE operator command). Except for TRACWUM and TRACDRRM (which are not supported in single user mode), they are used primarily for tracing in single user mode, but can be set in multiple user mode if you want to start tracing as soon as possible. For information about tracing, refer to the DB2 Server for VSE & VM Operation manual.
This parameter specifies the amount of memory (in kilobytes) to allocate to the trace buffer. Specifying a nonzero value causes trace output to be stored in a fixed size buffer in memory. Trace records are stored in wrap-around mode in this buffer, and when tracing is turned off, the contents of the buffer are written to disk or to tape (as specified by the ARITRAC FILEDEF statement). The trace buffer is only created if you specify TRACEBUF with at least one of the startup initialization parameters TRACRDS, TRACDBSS, TRACDSC, TRACCONV, TRACDRRM, TRACWUM, or TRACSTG; it is not created if the TRACEBUF default (n=0) is specified. A suggested size for the trace buffer is 100 kilobytes or more. If you do not specify TRACEBUF and tracing is requested, trace records are written directly to disk or tape as the trace points are processed.
Figure 11 identifies the initialization parameters that apply when the database manager is operating in single user mode.
Figure 11. Single User Mode Initialization Parameters
Most of the considerations for setting these parameters are the same as those described under Multiple User Mode Initialization Parameters, with the following exceptions:
If LOGMODE=N, database changes are only committed when a checkpoint is explicitly taken (with COMMIT WORK statements).
The ARCHPCT parameter cannot be specified if LOGMODE=N.
The database manager can use tape files for recording archive and trace information. You can also use tape files with the DATALOAD/DATAUNLOAD and RELOAD/UNLOAD facilities of the DBS utility. (It is also possible to use tape files for the DB2 Server for VM preprocessors, but this is unusual.)
For the archive and trace tape files, the IBM-supplied EXECs that starts these facilities provide default CMS FILEDEF commands for the needed tapes. These default FILEDEFs are shown under the descriptions of the EXECs that call them.
You can also take log archives to disk. For more information, see Log Archiving to Disk.
For the DBS utility tape files, you must supply your own CMS FILEDEF commands. You can also specify LABELDEF commands. You should use the LABELDEF command for multivolume standard label tapes.
To specify your own FILEDEF and LABELDEF commands, issue them before invoking the EXEC that calls the facility. When an IBM-supplied EXEC issues a CMS FILEDEF command for tape files, it uses the NOCHANGE parameter. This means that any FILEDEF (or LABELDEF) that you supply before running the EXEC overrides the default.
The database manager uses the CMS simulation of OS QSAM for its tape support. The database manager also provides additional support, as follows:
The following sections discuss considerations for using tape support.
When using unlabeled tape output files, you should be aware of the following:
When using standard label tapes, you should ensure that the mounted tape volume (or volumes) contain volume labels (VOL1) and file labels (HDR1). These labels must be recorded in the same tape density as specified (or allowed to take the default) when creating the new file. If you do not ensure that the labels are recorded in the same density as specified when creating the new file, tape OPEN processing fails.
You can use the CMS TAPE command to check whether a volume contains a volume label (and display the label's contents) with the DVOL1 keyword. (You must supply the TAPn parameter as appropriate.)
You can also use the CMS TAPE command to create a volume label (VOL1) and dummy HDR1 label with the WVOL1 keyword. (Once again, you must supply the TAPn and DEN parameters as appropriate.) The tape volume label must be recorded in the same density as the file to be created. (The density of the volume label must match the CMS FILEDEF command DEN parameter value.)
You should specify LABELDEF commands for your tape files so that processes that use tapes (such as RESTORE) can verify that the correct tape is mounted. This is particularly advisable when working with multivolume tape files.
| Note: | If you are processing multivolume tape files, you should use a different VOLID for each tape volume so that the system can verify that the correct tape is mounted. To do this, enter VOLID ? with the LABELDEF command. CMS prompts you for the individual VOLIDs. For more information on the LABELDEF command, see the VM/ESA: CMS Command Reference manual for your VM system. |
For single-volume tape files, you can use the following CMS FILEDEF command tape label options:
The database manager does not support nonstandard labels or standard user labels (except with the FILEDEF BLP parameter as described in the preceding list). Therefore, you must not specify tape label options SUL or NSL in the CMS FILEDEF command.
In addition to the FILEDEF command, you should specify a LABELDEF command for multivolume standard label tapes. This enables CMS to verify that the correct tape is mounted when a multivolume tape file is being processed.
If you have two tape drives available, you can specify an alternate tape drive in the FILEDEF command (this is only supported with labelled tapes). This causes tape drives to be switched automatically when end-of-tape is reached. If you are using a single tape drive you must mount a new tape when end-of-tape is reached.
The following is an example of FILEDEF and LABELDEF commands for a database archive:
TAPE WVOL1 ARCD1 (TAP1 TAPE WVOL2 ARCD2 (TAP2 LABELDEF ARIARCH VOLID ? DMSLBD441R Enter VOLID information: ARCD1 DMSLBD441R Enter VOLID information: ARCD2 DMSLBD441R Enter VOLID information: FILEDEF ARIARCH TAP1 SL 1 (ALT TAP2 |
This LABELDEF statement assumes that the archive requires two tape drives. If it requires more, you are prompted to enter more VOLIDs during the archive procedure.
For spanned-record files, omit the LRECL value from the CMS FILEDEF command. If specified, it is ignored.
There are no other special considerations for spanned-record input files.
For spanned-record output files:
| Note: | Files written in RECFM=VB format can be read with the RECFM specification of either VBS or VB. |
| Note: | Files written in RECFM=VS format can be read with the RECFM specification of either VS or VBS. |
The block size for database archive file output and log archive file output is always 28 kilobytes.
Many of the database manager facilities use SYSIN, SYSPRINT, and SYSPUNCH files. The IBM-supplied EXECs that call these facilities often contain parameters that allow you to assign these files to various devices. These EXEC parameters generate CMS FILEDEF commands for the files internally.
In many instances, however, the EXECs provide for only the most common files. If you want something that is not an option in an EXEC parameter, you can issue a FILEDEF command before running the EXEC. For example, to assign SYSIN to tape for the DBS utility, you must issue a CMS FILEDEF command before running the DBS utility EXEC (SQLDBSU).
Many of the usual VM assignments for SYSIN, SYSPRINT, and SYSPUNCH are valid for DB2 Server for VM use. The following list summarizes the valid assignments:
Except for the virtual printer files and terminal output, the files can be fixed blocked. A CMS FILEDEF command for a SYSPRINT file can specify RECFM FBA (or FB) and BLKSIZE nnnn. The nnnn must be some multiple of 121. If you specify RECFM in the SYSPRINT FILEDEF, you must specify FA or FBA (unless you want the ANSI carriage control characters printed). The value FA is the default.
The DBS utility and ISQL support other print file logical record sizes. In addition, ISQL supports other devices. For more specific information, refer to the DB2 Server for VSE & VM Database Services Utility and the DB2 Server for VSE & VM Interactive SQL Guide and Reference manuals.
Remember that normal CMS defaults on FILEDEF commands apply. Specifically, if the file is a CMS file, and you do not specify a file mode, CMS uses A1. If you specify only a file mode letter, CMS uses a file mode number of 1. If you specify * for the file mode, CMS searches all accessed minidisks (A to Z) for a file with the specified file name and file type.
You start the application server in multiple user mode so that one or more applications can concurrently access the same application server.
To start the application server in multiple user mode:
| Note: | You cannot run the database manager in a CMS batch machine. |
Figure 12 shows the format of the SQLSTART EXEC.
>>-SQLSTART----Dbname(server_name)---+------------+------------->
'-dcssID(id)-'
>-----+-----------+---+------------------+---------------------><
'-AMODE(nn)-' '-PARM(parameters)-'
|
The parameters for the SQLSTART EXEC are:
After initial installation and database generation, the only application server you have is named SQLDBA. If you add more databases, you can specify other names for DBNAME.
If specified, DCSSID must precede the PARM parameter. You can specify ID instead of DCSSID for the keyword. No other abbreviation is valid. For more information on starting the application server to use saved segments, refer to Chapter 8, Saved Segments.
The value specified for the AMODE parameter is saved in the resid SQLDBN file. If AMODE is not specified in the SQLSTART EXEC, the resid SQLDBN file is checked, and the AMODE value found in the resid SQLDBN file is used. If this file does not exist or does not contain an AMODE value, AMODE(31) is used and this value is saved in the resid SQLDBN file. The database manager continues to use this value until a different value is specified.
When AMODE is specified in the SQLSTART EXEC, this parameter must precede the PARM parameter. No abbreviation of AMODE is valid.
Single user mode applications and user exits will be invoked in the same addressing mode as the database manager. If you have such applications that do not support 31-bit addressing, you must do one of the following:
For more information on converting your program, see the VM/ESA: CMS Application Migration Guide. For more information on single user mode, see Starting the Application Server in Single User Mode. For more information on user exits, see Chapter 14, Creating Installation Exits.
Note that the preprocessors and the DBS utility must run in 24-bit addressing mode. In single user mode, if the database manager is running AMODE(31), the AMODE is automatically switched to AMODE(24) before invoking the preprocessor or DBS utility. The AMODE is then switched back to AMODE(31) after control is returned to the database manager.
The resource adapter always runs AMODE(31) in XA mode or XC mode regardless of the mode the database manager is running in.
| Note: | For users moving from the database manager on VSE to the database
manager on VM. The same parameters that are supported on VSE are
supported on VM. The exceptions are the DSPLYDEV and DBPSWD
parameters.
The database manager on VM ignores the DSPLYDEV parameter. Instead, SQLSTART always issues SP CON START HOLD (unless the database manager is already spooled START), and all output (except dumps) goes to the console. Dumps go to the virtual printer or reader. This implementation is different because, on the VSE operating system, there is only one operator console and one SYSLST for each partition. In VM, all machines usually have their own console and virtual printer. The DBPSWD parameter was used in VSE to specify a VSAM password. This parameter does not apply to the database manager on VM, and is ignored if specified. |
During its processing, SQLSTART issues these CMS FILEDEF commands for the trace and archive files:
FILEDEF ARIARCH TAP1 SL (NOCHANGE PERM FILEDEF ARITRAC TAP2 SL (NOCHANGE PERM FILEDEF ARILARC TAP3 SL (NOCHANGE PERM
To override these FILEDEF commands, issue your own before running SQLSTART. You must use the ddnames ARITRAC, ARIARCH, and ARILARC for the trace, database archive, and log archive files, respectively. Standard label, unlabeled, single volume, and multivolume tapes are supported. For more information on tape support, see Tape Support.
If you are using standard label tape files for tracing, database archiving, or log archiving, you can optionally submit CMS LABELDEF commands before running the SQLSTART EXEC. This allows you to specify values to be used for file header label checking and creation. You should supply CMS LABELDEF commands to ensure that you have the proper tape files and volumes mounted. You must use the LABELDEF command for multivolume standard label tapes. For more information, see the VM/ESA: CMS Command Reference manual.
Do not specify any VOLID parameter on your LABELDEF (or FILEDEF) commands for log archiving (ddname ARILARC). Because more than one log archive file can be read or created during one database-manager session, you should use different VOLIDs for the different files.
You can take log archives to disk rather than tape by changing the FILEDEF of ARILARC. For more information on directing log archives to disk, see Log Archiving to Disk.
It is possible to direct the trace output to a memory buffer or to a CMS file rather than to a tape. This may be convenient if you often use the security audit trace. For more about directing trace output to a memory buffer or to a CMS file, see the DB2 Server for VSE & VM Operation manual.
When the application server is started in multiple user mode, and the user machine is initialized (with the SQLINIT EXEC), SQL application programs can be started by normal means (such as the CMS LOAD or START commands).
For more information on running application programs, see the DB2 Server for VSE & VM Application Programming manual.
| Note: | If you plan to run your application programs in both multiple user mode and single user mode, you should follow the protocols discussed in the section CALL/RETURN Protocols for Application Programs in Single User Mode. |
An application program running in single user mode runs in the same machine as the application server, and is under its control. (In this situation, the user machine and the database machine are actually the same machine.) To run a single user mode application program, start the application server in single user mode (SYSMODE=S) and provide the program name as an initialization parameter (PROGNAME=name). For PROGNAME specify the name you would specify if running the program in multiple user mode. The program is loaded and control is passed to it after the application server is started. For single user mode, only the TEXT files need to be available. If you choose this method, you should put the files in a TXTLIB, because the database manager does not issue INCLUDE commands. It is preferable to create a module using the CMS LOAD/GENMOD commands, especially if the program is to be used frequently.
Your application is invoked in the same addressing mode as the database machine. If your single user mode application program does not support 31-bit addressing, you must do one of the following:
For more information on converting your program, see the VM/ESA: CMS Application Migration Guide.
Attention: The value specified for the AMODE parameter is saved in the resid SQLDBN file between invocations of the SQLSTART EXEC. If AMODE is not specified, the resid SQLDBN file is checked, and the last value is used. If you only want AMODE(24) for single user mode applications, be sure to specify AMODE(31) when restarting in multiple user mode. When running AMODE(24) option, you cannot use any storage above 16M.
Some administrative tasks (such as adding dbextents and adding dbspaces) are performed by running IBM-supplied EXECs in single user mode. These EXECs call the SQLSTART command with the appropriate parameters.
Figure 13 shows how to run an application program in single user mode. When the application server is started, it passes control to the application program specified by the PROGNAME parameter. All other initialization parameters are allowed to default. You may want to specify some single user mode initialization parameters. For information on single user mode initialization parameters, see Figure 11.
Figure 13. Starting in Single User Mode
SQLSTART DB(SQLDBA) PARM(SYSMODE=S,PROGNAME=name) |
| Note: | The PROGNAME parameter is not needed when STARTUP=C|E|L|S|I|M is specified. These startups specify the operation to be performed, so a program name is not needed. Moreover, the database manager provides separate EXECs for each of these situations, one of which must be used instead of SQLSTART. (Each of these EXECs calls SQLSTART at the proper time.) |
During its processing, SQLSTART issues these CMS FILEDEF commands for the trace, database archive, and log archive files:
FILEDEF ARIARCH TAP1 SL (NOCHANGE PERM FILEDEF ARITRAC TAP2 SL (NOCHANGE PERM FILEDEF ARILARC TAP3 SL (NOCHANGE PERM
To override these FILEDEF commands, issue your own before running SQLSTART. You must use the ddnames ARITRAC, ARIARCH, and ARILARC for the trace, database archives, and log archives, respectively. Specify the PERM option on your FILEDEF commands if the application program is written in a language other than Assembler. Standard label, unlabeled, single volume, and multivolume tapes are supported. For more information on tape support, see Tape Support.
If you are using standard label tape files for tracing, database archiving, or log archiving, you can optionally submit CMS LABELDEF commands before running the SQLSTART EXEC. This allows you to specify values to be used for file header label checking and creation. You should supply CMS LABELDEF commands to ensure that you have the proper tape files and volumes mounted. You must use the LABELDEF command for multivolume standard label tapes. For more information, see the VM/ESA: CMS Command Reference manual.
You should not specify VOLID parameters on any LABELDEF or FILEDEF commands you issue for the log archive files. Because more than one tape file can be created during a database manager run, you should use different VOLIDs for the different tape files.
It is possible to direct the trace output to a CMS file rather than to a tape. This may be convenient if you often use the security audit trace. For more information about tracing, see the DB2 Server for VSE & VM Operation manual.
In addition to the FILEDEFs for archiving and tracing, SQLSTART issues the following FILEDEF command for a user LOADLIB:
FILEDEF ARIUSRDD DISK USERLIB LOADLIB * (NOCHANGE
If you want to specify a different LOADLIB, issue your own FILEDEF command before calling SQLSTART. You must use the ddname ARIUSRDD on the FILEDEF command to identify a user LOADLIB to the database manager. Note that the file mode used in the FILEDEF is *. Remember to access the minidisk containing your LOADLIB ahead of other minidisks that contain USERLIB LOADLIBs.
If you use AMODE(24), the application program must be RMODE 24. If it is not, and the program is loaded above 16M, the database manager issues message ARI0021E.
The application program can be a module, or it can reside in a LOADLIB (or, conceivably, a saved segment).
Because the database manager does not know where the user program is (and there are many ways to load a program in VM), the database manager tries a sequence of VM commands to load the program. The following sequence is used:
Because not all of the above VM load functions return the entry point, you should code your program so the entry point is the same as the load point. Only LOADMOD and NUCXLOAD return the program's entry point. When the database manager finds a program with the name specified in the PROGNAME initialization parameter and successfully loads the program, the search sequence ends. Control is passed to the program with a BALR instruction.
For example, suppose you have two programs on your A-disk. One is named MYPROG MODULE A; the other is named MYPROG TEXT A. If you run SQLSTART with PROGNAME=MYPROG, the program loaded is MYPROG MODULE A. The database manager tries the LOADMOD command before the LOAD command. If you want to load MYPROG TEXT A, you must either rename it and change the PROGNAME parameter value accordingly, or you must rename (or erase) MYPROG MODULE A.
If the database manager does the entire search sequence, and a not found indication is received from each of the load functions, four messages are issued:
If the database manager receives an insufficient storage indication from any of the load functions, the same four messages are issued, but the reason code in message ARI0042I is 8 (not 4).
If the load of the user program fails for a reason other than those discussed above, the database manager issues message ARI0026E. Following that message is one or more occurrences of message ARI0047E. Message ARI0047E has the format:
xxxxxxxx- Reason Code=nnn
The type of load is indicated in xxxxxxxx. The xxxxxxxx can be LOADMOD, NUCXLOAD, SEGMENT LOAD, FETCH, or LOAD. The system return code from that load is in nnn. This message is followed by either message ARI0039E or ARI0040E, depending on the type of error. Following that message is ARI0042I with a reason code of 0 (the reason code is given earlier in message ARI0047E), and finally by message ARI0043I with a return code of 516.
Note that, for a NUCXLOAD or SEGMENT LOAD, the database manager must do more than issue those commands.
For NUCXLOAD, the sequence of NUCEXT QUERY, NUCXDROP, NUCXLOAD, and NUCEXT QUERY may be processed to load the code. Thus, the reason code displayed in message ARI0047E can be a return code from NUCEXT QUERY or NUCXDROP. (The return code is not necessarily from a NUCXLOAD.) You should check the DB2 Server for VM Messages and Codes manual for return codes from NUCEXT QUERY and NUCXDROP as well as NUCXLOAD.
The database manager follows this process when attempting to load a program with NUCXLOAD:
A similar process is done for code that is to be loaded into a saved segment.
The database manager does a SEGMENT FIND instruction to get the code load address and length. The SEGMENT LOAD instruction is then issued. Thus, the reason code displayed in message ARI0047E can be a return code from the SEGMENT FIND (not necessarily the SEGMENT LOAD) instruction. You should check the DB2 Server for VM Messages and Codes manual for return codes from SEGMENT FIND as well as SEGMENT LOAD.
The database manager follows this procedure when attempting to load a program with the SEGMENT LOAD macro:
ARI0047E SEGMENT LOAD - Reason Code=XXX
In addition to the loading sequence, you should be aware of the following when preparing to run a single user mode program:
If you start the application server in single user mode, you can also specify user parameters to be passed to the application program using the PARM keyword of the SQLSTART EXEC. The SQLSTART EXEC purges the CMS program and console stacks. Thus, any program run in single user mode cannot rely on console or program stack input.
Place a slash (/) between the database manager initialization parameters and the user parameters, as shown in Figure 14.
Figure 14. Starting in Single User Mode and Providing User Parameters
SQLSTART DB(SQLDBA) PARM(SYSMODE=S,PROGNAME=PROG1/parm1,parm2) |
| Note: | Only the first 130 characters of the command line are read by CMS. The exception to this rule occurs when SQLSTART is called from a user-written EXEC; then CMS reads the first 256 characters. If you specify many initialization parameters and user parameters, they will not fit on the command line. Thus, you must use a CMS file for some of the parameters. Because user parameters cannot be specified in a CMS file, you should specify the initialization parameters in the CMS file, and the user parameters on the command line. |
The user parameters are passed to the application program with register 0. Register 0 points to an area called NPLIST, which contains three addresses, which point to:
The user parameter string is untokenized: it has not been separated into individual user parameters. This pointer scheme is similar to the one that the EXEC 2 interpreter uses when running programs. Figure 15 shows how register 0 points to the user parameters.
Figure 15. Passing User Parameters to a User Application Program
The length of the parameters can be obtained by subtracting the BEGARGS address from the ENDARGS address. If there are no user parameters, the ENDARGS address is equal to the BEGARGS address (ENDARGS - BEGARGS = 0.) Both addresses, in this situation, point to the next byte after the name of the application.
User parameters are not displayed along with the initialization parameters. User parameters cannot be specified in a DB2 Server for VM parameter data set.
In single user mode, an application is called using normal CALL/RETURN protocols, as follows:
| Note: | This same protocol can also be used by programs running in multiple user mode. |
Register 0 was discussed in the previous section. A program written in C, PL/I, COBOL, or FORTRAN requires an interface routine to process the user parameters.
Upon entry, the application program must store the registers in the DB2 Server for VM save area, and restore them before returning control to the database manager. Failure to do so causes unpredictable results.
An abnormal termination exit is set to intercept abnormal termination conditions, including program checks. If the user program establishes its own abnormal end exit, the user exit overrides the DB2 Server for VM abnormal end exit.
The abnormal end exit is set (with CMS ABNEXIT) to intercept abnormal end conditions (including program checks). If the user program establishes an abnormal end exit (for example, with ABNEXIT, STAE, SPIE), the user program gets control
before the DB2 Server for VM abnormal end exit does. (However, STAE and SPIE are not supported in 31-bit addressing mode.) When the user program completes its abnormal end processing, it should return control to the CMS abnormal end routine. The CMS abnormal end routine then passes control to the DB2 Server for VM abnormal end routine. The application programmer must be careful when processing abnormal end conditions. These possibilities must be considered:
If you determine that processing cannot continue, you should reset your abnormal end exit, clear the abnormal end exit, and return control to the CMS abnormal end routine. The CMS routine then passes control to the DB2 Server for VM abnormal end routine.
The DB2 Server for VM abnormal end routines sever the IUCV links to the database minidisks, and close the trace file if tracing was activated. This same processing is also done when, upon completion, the user program returns control to the database manager. The database manager does not have to do this processing (for example, if the program does not return control to the database manager). If the IUCV links to the database minidisks are not severed, VM severs the links when you log off the database machine. (This also is true if the database machine abnormally ends.) If tracing or accounting were active, their output files may not have had the last buffers written. If the output files were on tape, no tape mark was written. You can then write tape marks with the CMS TAPE command.
The database manager uses eye-catcher technique for determining when a specific module is in error. The eye-catcher is displayed in the DB2 Server for VM mini-dump. A user program can use the same technique in single user mode, assuming that the DB2 Server for VM abnormal termination exit has not been overridden by a user abnormal end exit. A suggested coding example in assembler language is shown in Figure 16.
Figure 16. Use of an Eye-catcher by an Application Program
USING *,15
B SKIPEYE BRANCH AROUND EYE-CATCHER
DC AL1(16) LENGTH OF CHARACTER STRING
DC CL8'progname' PROGRAM NAME EYE-CATCHER
DC CL8'&SYSDATE' DATE PROGRAM COMPILED
DS 0H
SKIPEYE EQU *
STM 14,12,12(13) SAVE DB2 Server for VM REGISTERS
BALR 12,0 ESTABLISH BASE REGISTERS
DROP 15
USING *,12
LA 11,MYSAVEAR GET ADDRESSABILITY TO MY SAVE AREA
ST 11,8(13) SAVE ADDRESS OF SAVE AREA IN DB2 Server for VM SAVE AREA
ST 13,MYSAVEAR+4 SAVE ADDRESS OF DB2 Server for VM SAVE AREA IN SAVE AREA
LR 13,11 SET REGISTER 13 TO MY SAVE AREA
*
Body of the Application Program
*
EXIT L 15,RETCOD SET RETURN CODE (OR SET TO ZERO)
L 13,4(13) GET DB2 Server for VM SAVE AREA
L 14,12(13) GET DB2 Server for VM REGISTER 14
LM 0,12,20(13) GET OTHER DB2 Server for VM REGISTERS
BR 14 RETURN TO DATABASE MANAGER
|
Notes:
When starting the application server, you can change the default parameter values in either of two ways:
You can also combine the two methods. Parameters specified in the CMS file override the default values. Parameters specified on the SQLSTART EXEC override both the default values and those specified in the CMS file. A user who has a CMS file with an incorrect parameter value can override the value in error with a correct specification on the SQLSTART EXEC.
When all the values of the initialization parameters have been resolved, the final values (or defaults, if no values have been overridden) are displayed on the DB2 Server for VM operator's console.
When you specify parameters on the SQLSTART EXEC, separate each parameter with a comma or blank. For example:
SQLSTART DBNAME(SQLDBA) PARM(DUMPTYPE=F,LOGMODE=A) SQLSTART DBNAME(SQLDBA) PARM(DUMPTYPE=F LOGMODE=A)
Because CMS reads only the first 130 positions of the CMS command line, you may choose to set up your initialization parameters in one or more CMS files. Such an arrangement allows you to specify more user parameters (if any) when running application programs in single user mode. User parameters (those for the application program itself), cannot be specified in a CMS file, and must be specified in the PARM field of the SQLSTART EXEC. If you plan to use user parameters, refer to Specifying User Parameters.
You can also call the SQLSTART EXEC from within a user-written EXEC.
You can store various parameters in a CMS file that has a file type of SQLPARM, and a fixed record length of 80 bytes. To have the database manager use the file, specify the file name in the PARMID initialization parameter. Each file can start the application server for a slightly different environment. Figure 17 shows a parameter file.
Figure 17. Example of an Initialization Parameter File
LOGMODE=A,NDIRBUF=20, NPAGBUF=20, DUMPTYPE=F COMMENT -- FULL VIRTUAL MACHINE DUMP NCSCANS=20 |
The rules for specifying parameters in a CMS file are a little different from the rules for specifying parameters on the SQLSTART EXEC: