This section discusses the following topics:
In single user mode, the application server stops itself when the task is completed. In multiple user mode, the operator stops it by issuing the SQLEND operator command. In both modes, the database files and the trace file (if active) are closed. The SQLEND command is described in the DB2 Server for VSE & VM Operation manual.
The SQLEND command can be entered from the operator console of a database machine. Its format is shown in Figure 18. The ARCHIVE, LARCHIVE, and UARCHIVE parameters are used to initiate archive activities after the database has been shut down, and are discussed in the next section. The NORMAL parameter is used to shut down the database when all work in progress is completed. The QUICK parameter is used to stop all work in progress and shut down immediately. The TRCPURGE parameter is used if you want to purge the contents of the trace buffer at DB2 Server for VM shut down. You can also specify the DVERIFY parameter to do a directory verification.
Figure 18. SQLEND Operator Command
.-NORMAL---.
>>-SQLEND----+----------+---+----------+---+-----------+-------><
+-ARCHIVE--+ '-DVERIFY--' '-TRCPURGE--'
+-LARCHIVE-+
+-UARCHIVE-+
'-QUICK----'
|
Do not issue SHUTDOWN from the VM console as it shuts down VM and causes the database manager to end abnormally.
The SQLEND command can be set up to enable the operator to take a database or log archive after all DB2 Server for VM activity has stopped. The following parameters are available for archiving:
Attention: User archive facilities are available for the database, but not the log. Never attempt to use user facilities to archive a log.
The most appropriate time to take an archive is at shutdown, so consider setting up a procedure for periodic SQLENDs with the ARCHIVE, UARCHIVE, or LARCHIVE parameters, as needed.
For both database and log archives, online archives are disruptive to users. Taking archives during SQLEND avoids this disruption. In addition, database archives taken at SQLEND contain data that is consistent, whereas those started by operator ARCHIVE commands or triggered by ARCHPCT typically contain uncommitted or incomplete data, and require information from the log to make the data consistent. (Consistency is not a problem for log archives regardless of when they are taken, because the database manager always waits until all LUWs end before taking the checkpoint on which the log archive is based.)
To determine the best recovery procedures for your installation, see Recovering from DASD Failures that Damage the Database.
If the operator specifies ARCHIVE or UARCHIVE when LOGMODE=Y, the database manager automatically switches the LOGMODE to A. To resume running with LOGMODE=Y, the operator must do a COLDLOG. See Switching Log Modes.
Should you decide not to take an archive at shutdown, specify NORMAL or QUICK. During a normal shutdown, the database manager allows all active LUWs to finish before ending. During a quick shutdown, the application server ends immediately: in-progress LUWs receive a negative SQLCODE and are rolled back the next time the application server is started.
| Note: | A User Archive will NOT be consistent if it is taken following an SQLEND QUICK shutdown. |
If you are running with LOGMODE=L, and request a database archive, and if there is data in the log, then the database manager takes a log archive before taking the database archive. This log archive is written to tape. However, you can direct it to disk if you change the FILEDEF for the log archive file, or if you direct the log archive to disk when you archive it. For more information on directing log archives to disk, see Log Archiving to Disk.
Database archives are written to tape. When running a database archive, the database manager displays external label information for you to write on the tape if you are archiving to tape. It then requests that you mount the required volumes. If you are archiving to disk, you should respond by typing the virtual device address.
Unless you have issued your own CMS FILEDEF command before starting the application server, the virtual device address for database archives is 181. The virtual device address for log archives (either explicitly requested or automatically created) is 183. See Archiving Procedures for more information.
When the SQLEND command is issued with the NORMAL, ARCHIVE, LARCHIVE, or UARCHIVE parameters, a shutdown is not initiated until all users are disconnected from the application server. The database manager displays a message showing how many agents are still active. (An agent is an internal representation for a user.) As each agent becomes inactive, another message is displayed with an updated count.
The initial count displayed in the message includes all active user agents. When users who are inactive (not allocated to a real agent) disconnect from the database manager, no message is displayed to indicate a reduction in agents; the message is issued only when a user disconnects from the database manager while still allocated a real agent. This results in gaps in the updated count messages.
After issuing an SQLEND command, and before shutdown commences, the operator can issue a SHOW ACTIVE command to find out who is still using the database manager. Users who are connected with no active LUW can prevent the database manager from performing shutdown operations. For example, an ISQL user can end an LUW and then leave the terminal without exiting from ISQL. To determine whether inactive users are preventing
the shutdown operation, use the SHOW USERS operator command to determine which users are still active. For more information on the SHOW commands, see the DB2 Server for VSE & VM Operation manual.
If the SQLEND command is issued with the QUICK parameter, all in-progress work ends and return code 508 is displayed on the console. This command can be issued at any time, even following an SQLEND issued with another parameter.
The DVERIFY parameter determines whether the database manager checks for inconsistencies in the directory. It can be specified with the other parameters, but is ignored if you specify QUICK. It should be specified each time the database is archived (using either DB2 Server for VM or user facilities); if it is not, any inconsistency in the directory will be recorded in the database archive, so a subsequent restore operation using that archive would fail.
Even if you have not requested a database archive, you should periodically verify the directory (perhaps every few days, depending on the volume of update activity). Otherwise, inconsistencies may surface later. For example, an inconsistency can cause an abnormal end during checkpoint processing. Early detection reduces data loss.
If an error is found in the directory, a message is displayed. If this happens, and you had specified ARCHIVE, the archive is not taken. If you had specified UARCHIVE (a database archive using user facilities), then when you are prompted to take the archive, do not do so. However, if you had specified LARCHIVE, the log archive is taken; the inconsistency in the directory does not affect the log, so the log archive is still valid. For information on recovering from directory verification errors, see the DB2 Server for VSE & VM Diagnosis Guide and Reference manual.
If you are supporting an online (CICS) environment, you should stop the online support before ending the application server, in order to clean up CICS transaction processing efficiently. To stop the online support, enter the CIRR or CIRT transaction. For more information on the effect of a shutdown on online applications, see Stopping the Online Support -- The CIRT Transaction and Removing Connections -- The CIRR Transaction.
| Note: | For DB2 Server for VSE, each link from the Online Support requires a dedicated agent, whether or not these agents are actually active. SQLEND NORMAL will not terminate these connections. |
Many of the IBM-supplied EXECs described in this chapter (and throughout the manual) access the DB2 Server for VM production and service minidisks. These EXECs often must write to and read from those minidisks.
Depending on the tasks you are trying to do and the virtual machine you are using, you can be prompted for the read, write, or multiple access passwords for the minidisks.
You should always be prepared to supply the passwords for the production and service minidisks before you run the IBM-supplied EXECs.
| Note: | DB2 Server for VM users should not know the passwords for the production and service minidisks, or any other database machine minidisks. |
Advanced Program-to-Program Communication/Virtual Machine (APPC/VM) is used by software to communicate between user and database machines, regardless of their physical locations. The Inter-User Communication Vehicle (IUCV) is limited to communications between two virtual machines residing on the same processor.
Internally, the database manager uses NCUSERS to determine the number of agent structures to create. Each agent structure serves one user at a given time. (That is, one user who is within an LUW.) Processing time is divided among the agent structures. You can think of an agent structure as equivalent to a user for whom the database manager is currently doing work. Thus, NCUSERS controls the number of concurrent users (agent structures) using the database manager.
As discussed earlier, each agent structure uses virtual storage and produces some processor overhead. If NCUSERS is set too high for your particular system configuration, the database manager may become overloaded and perform poorly. To determine the optimal NCUSERS setting for your installation, use the guidelines given in NCUSERS.
The optimum number for NCUSERS is usually less than the total number of users planned for a database. Thus, the number of connected users trying to access a database machine usually far exceeds the number specified for NCUSERS. For example, if there are 80 users and only 8 agent structures, all 80 users would be competing for those structures.
To solve this problem, the number of connected users can exceed the number specified for NCUSERS. The number of users that can be connected is related to a value called MAXCONN.
The MAXCONN parameter of the VM OPTION directory control statement determines the maximum number of IUCV connections allowed for a virtual machine. For inter-machine communications, the virtual machine is the database machine. MAXCONN has a default value of 16.
The database manager uses APPC/VM (or IUCV) to access the database minidisks (including the directory, the logs, and the dbextents) and to communicate with user machines. Thus, the number of users that can be connected to a database machine is equal to the value of MAXCONN minus the number of minidisks for the database currently being accessed. On a VM/ESA operating system, the number of users that can be connected is decreased by one more because the DB2 Server for VM machine makes an additional connection to CP system service *IDENT. It is further reduced by one if the special TCP/IP communications real agent is active.
Usually, MAXCONN is set when a database machine is defined. (For more information, see Adding a Primary Database Machine.) This initial setting is based on an estimate of the number of minidisks that make up the database and the number of users. As these conditions change, MAXCONN should be readjusted.
Because the number of connected users can exceed the number of real agents, the database manager uses another mechanism to keep track of users that are not assigned to real agents. This mechanism is called the pseudo-agent structure.
The number of pseudo-agents is equal to the value of MAXCONN minus the number of minidisks for the database currently being accessed. Initially, these pseudo-agents are placed on an available queue.
When an APPC/VM (or IUCV) CONNECT to the database manager is issued, the user is assigned to a pseudo-agent, and placed in an in-use queue. When a user issues a statement (for example, SELECT), the user machine sends a message to the database machine. At this time, the user's pseudo-agent is assigned to a real agent, if one is available. If none is available at the moment, that user's pseudo-agent is placed in a first-in, first-out wait queue. When a real agent becomes available, the first pseudo-agent in the wait queue is assigned to that real agent.
When the user performs any action that results in the end of an LUW (for example COMMIT or ROLLBACK), that user's pseudo-agent is deallocated from the real agent. An exception occurs when there are no waiting pseudo-agents and the user has sent another message to the database machine. When a pseudo-agent is deallocated from a real agent, it is placed on an inactive queue until and unless the user sends another message. At that time the pseudo-agent is placed at the end of the wait queue, unless a real agent is available. When a pseudo-agent is deallocated from a real agent, the first waiting pseudo-agent on the wait queue is allocated to the available real agent.
A pseudo-agent is deallocated from a user when the connection to the database manager is severed (for example, COMMIT WORK RELEASE or end-of-program).
The database manager does not verify that the users are allocated to real agents; that is, it does not determine whether the real agent has received a message recently (is active). A user can tie up a real agent by being inactive. For example, a user can start an LUW and leave the terminal unattended. In this situation, the DB2 Server for VM operator can use the FORCE command to end the LUW.
Pseudo-agents that are not attached to real agents have no effect on performance other than the use of extra virtual storage.
Pseudo-agents can affect shutdown procedures. When the DB2 Server for VM operator issues any SQLEND command (except SQLEND QUICK), the database manager does not end (or begin the archive process) until all users (owners of pseudo-agents) are disconnected. All users can complete their work and disconnect from the database manager (unless forced off by the VM system operator or by the DB2 Server for VM operator).
You can determine inactive but connected users by issuing the SHOW USERS command.
The SHOW ACTIVE command is inappropriate because it displays information about agent structures. It does not tell you whether inactive users are holding pseudo-agents.
| Note: | The DB2 Server for VM operator can force (with the FORCE command) only those users attached to real agents. Only the VM system operator can force (log off) those users who are waiting for real agents or who have inactive pseudo-agents. The alternative is for the DB2 Server for VM operator to issue the SQLEND QUICK command, which immediately stops the application server and disconnects all users. |
In some situations, you may want to limit the number of users who can connect to the database manager. For example, if your installation has 100 DB2 Server for VM users, you may want only 50 of them on at a time for performance reasons. Lower the MAXCONN parameter to decrease the number of users. This places a limit on the number of connected users. Users who try to access the database manager when the limit is reached receive a message indicating that they cannot access the database.
The database manager's use of APPC/VM does not preclude users from using both APPC/VM and SQL statements in the same application program in either single user mode or multiple user mode.
For more information about how the database manager uses APPC/VM and IUCV, see the DB2 Server for VSE & VM Diagnosis Guide and Reference manual.