PQO: Managing the PQO network
Overview
After you have defined the Parallel Query Option/204 network as described in PQO: Defining a PQO network, you need to be aware of certain tasks involved in managing the daily operation of the network. These tasks are performed by the network administrator, system administrator, or system manager, and include:
- Controlling the network
- Monitoring network activity
- Using the Model 204 audit trail
- Interpreting communications errors
Controlling the network
You use the following types of Model 204 commands to control the PQO network:
- LU 6.2 network administration commands
- BUMP system control command
These commands are described in the sections that follow.
Using the LU 6.2 network administration commands
The basic set of network administration commands used to control the operation of the PQO network are also used for Horizon. The commands shown in the following table are useful for controlling utilization of resources in the network.
| Command | Description |
|---|---|
| [OPEN | CLOSE] LINK | Enables/disables the link specified in a DEFINE LINK command (allocates/releases internal resources). If a link is closed after a service subsystem has been successfully started, that subsystem remains available to the client (although the link must be reopened before the client can reaccess it). |
| [STOP | START] LINK | Halts/resumes operation of the link specified in a DEFINE LINK (deactivates/activates sessions). |
| [STOP | START] PROCESSGROUP |
Halts/resumes operation of a processgroup specified in a DEFINE PROCESSGROUP command (enables processgroup redefinition). If a processgroup is stopped after a service subsystem has been successfully started, that subsystem remains available to the client (although the processgroup must be restarted before the client can reaccess it). |
| MODIFY PROCESSGROUP | Modifies an operational PROCESSGROUP definition (overrides current parameter settings). |
The Model 204 network administration commands require User 0, system manager, or system administrator privileges. See Horizon network management for information about using the LU 6.2 network administration commands.
Using the OPEN LINK command
Use the OPEN LINK command to establish the connections for a PQO conversation. Both the link on the client and the corresponding link on the server must be opened before a client user can access remote server files. The syntax of the OPEN LINK command is the standard Horizon network OPEN LINK syntax. For information about using the OPEN LINK command, see [[Horizon network management.
Using the BUMP command
Use the BUMP command to log out a PQO user or to log out all users of a subsystem.
Bumping a user
The BUMP command operates differently depending on whether it is issued by a client or a server system manager.
If the client issues a BUMP command for a user with an open remote file, the client and service threads are freed in the following way:
| Client |
|---|
| 1. Soft restart processing for the user begins. |
| 2. Files opened by the user are closed. |
| 3. The user is logged out. |
| 4. Soft restart processing for the user ends. |
| Server |
|---|
| 1. The user's service thread is logged out. |
| 2. Soft restart processing for the user begins. |
| 3. Local files opened by the user are closed. |
| 4. The user is logged out. |
| 5. Soft restart processing for the user ends. |
If the server issues a BUMP command for a remote user with a server file open, the service and client threads are freed in the following way:
| Server |
|---|
| 1. Soft restart processing for the user begins. |
| 2. Local files opened by the user are closed. |
| 3. The user is logged out. |
| 4. Lost session message is issued. |
| 5. Soft restart processing for the user ends. |
| Client |
|---|
| 1. User query of the remote file receives lost session and communication error messages. |
| 2. User can open remote file again. |
Bumping all users of a subsystem
To bump all users of a specified subsystem, use the SUBSYSTEM argument of the BUMP command. The syntax is as follows:
Syntax
BUMP SUBSYSTEM subsysname
Model 204 schedules all users in the subsystem to be bumped, except those in nonbumpable states such as BACKOUT.
You can also bump all local users of a remote service subsystem. Use the client LOCATION name with BUMP SUBSYSTEM. The syntax is as follows:
Syntax
BUMP SUBSYSTEM subsysname FROM location
where:
location is the value of the client CCAIN LOCATION parameter (which is also the value of the CLNT field in the LOGWHO command output), or is the symbolic name specified by the process definition.
Monitoring network activity
The Model 204 commands used to check on the activity in the PQO network are shown in the following table.
| Command | Description |
|---|---|
| DISPLAY GROUP | Displays information about Model 204 groups |
| LOGWHO | Identifies the users who are currently logged in to the Model 204 system |
| MONITOR | Provides usage statistics for each service thread currently open in the network; also provides information about active local and remote subsystems |
| STATUS | Displays information about remotely opened Model 204 files |
| VIEW | Specifies the current setting for the named parameter |
These commands can be used system-wide. These commands also provide information that identifies users, files, groups, or settings that are particular to the PQO network, as described in the sections that follow.
Using the DISPLAY GROUP command
The DISPLAY GROUP command can display the name and member files of any or all locally created scattered groups. It does not display definitions for groups that were created on other nodes.
The names of remote files displayed are their file synonyms or remote file specifications (filename AT location).
In addition, the display might include:
- OPTIONAL (in parentheses) following each optional member. MANDATORY is not displayed if the member is mandatory. For more information about optional and mandatory group members, see Creating ad hoc scattered groups.
- MAXFAIL parameter (CREATE GROUP command) value, if it has a value other than asterisk (*).
- UPDTFILE parameter value, including the update file's location if its location was used in the CREATE GROUP definition.
Using the LOGWHO command
The LOGWHO command lists the users who are currently logged in to Model 204. For PQO, the LOGWHO command operates differently depending on whether it displays information for a client or a server system.
For each PQO user, LOGWHO shows the remote files currently open. Model 204 includes the following LOGWHO information for a PQO user:
| Client | Displays the user ID and the name of the open remote file using the full remote file specification (filename AT location) |
| Server | Displays the client user number and user ID, and also displays name of subsystem into which service thread is logged, if any |
For example, the LOGWHO command displays the line below for a PQO user on a client system. The user has two files open: a local file, DEMOINV, and a remote file, SALES1, at the BOSTON location:
USER 5 SYSADM L3270621 DEMOINV SALES1 AT BOSTON
The values in this example come from the following sources:
| Value | Source |
|---|---|
| USER 5 | User thread number displayed in Model 204 journal/audit trail user statistics; see Tracking system activity (CCAJRNL, CCAAUDIT, CCAJLOG) |
| SYSADM | User's Model 204 login user ID |
| L3270621 | User's SNA Communications Server Communications Server (formerly VTAM) terminal ID or z/VM machine name |
| DEMOINV | Name of a local file open on the client |
| SALES1 | File's name as specified in a Model 204 CREATE FILE command on the server |
| BOSTON | Node on which the remote file resides; a symbolic destination name specified in a client DEFINE PROCESS command for CCAD2C |
In the following example, a LOGWHO command is issued for a PQO service thread. The display includes the following line for a client user. The line includes the service thread's originating client node, the user number of the client thread, and the name of the subsystem into which the client user is logged.
USER 34 MGRXYZ XXXXXXXX SALES1 CLNT: 00005 ON CHICAGO APSY: DEMOSALES
The values in this example come from the following sources:
| Value | Source |
|---|---|
| USER 34 | User thread number of service thread as displayed in Model 204 journal/audit trail user statistics |
| MGRXYZ | Client user's Model 204 login user ID |
| XXXXXXXX | Value of local DEFINE PROCESSGROUP command REMOTEID parameter |
| SALES1 | Name of a local file open on the server |
| CLNT: 00005 | User number at the client thread that is currently using the service thread MGRXYZ (only if user is a client) |
| ON CHICAGO | Value of User 0 LOCATION parameter in the client's Model 204 CCAIN |
| APSY: DEMOSALES | Name of APSY subsystem into which client thread is logged (only if USER 34 is a service thread) |
The LOGWHO command requires system administrator privileges.
Using the MONITOR command
The MONITOR command can provide statistics on the current usage of a network entity: link, processgroup, or process. MONITOR can also provide information about active PQO subsystems. This section describes details specific to the PQO output lines.
The MONITOR commands of particular interest for PQO are summarized in the following table.
| Command | Displays... |
|---|---|
| MONITOR LINK | Single summary line, and a detail line for each bound session |
| MONITOR PROCESSGROUP | Single summary line, and a detail line for each active conversation |
| MONITOR PROCESS | Detail line for each active conversation |
| MONITOR SUBSYSTEM | List of active subsystems and information about those subsystems |
The MONITOR command for network entities operates the same for PQO as it does for the Horizon network. It requires User 0, system manager, or system administrator privileges.
MONITOR SUBSYSTEM output reports whether subsystem members are optional or mandatory, and it has an option (FROM location) that allows PQO users to specify exactly the service subsystem monitored. Ordinary user privileges are required.
MONITOR LINK statistics
Monitoring link activity in the PQO network produces the following difference in the output lines compared to the Horizon statistics: The PROCESS term in the detail line for PQO specifies CCAD2S for the server process or CCAD2C for the client process.
The PROTO term in the summary line specifies LU 6.2 as the type of communications protocol for PQO, the same as is used for Horizon.
MONITOR PROCESSGROUP statistics
Monitoring processgroup activity in the PQO network produces differences in the detail output line compared to the Horizon statistics. The PROCESS term in the detail line for PQO specifies:
- CCAD2S for an inbound conversation
- CCAD2C for an outbound conversation
MONITOR PROCESS statistics
Monitoring process activity in the PQO network produces differences in the detail output line compared to the Horizon statistics. The CID (conversation ID) term for a PQO conversation ID specifies:
- CCAD2S (for a server), with the FLGS term set for I (inbound)
- Concatenation of the processgroup REMOTEID and LINK values (for a client), with the FLGS term set for O (outbound)
MONITOR SUBSYSTEM command
To display information about a PQO service subsystem, a server node user specifies the client subsystem name and LOCATION name with the MONITOR SUBSYSTEM command. The format is as follows:
Syntax
MONITOR SUBSYSTEM (optionlist) subsysname FROM location
where:
- optionlist and subsysname are the standard Model 204 MONITOR SUBSYSTEM variable arguments.
- location is the value of the client CCAIN LOCATION parameter, which is also the value of the CLNT field in the LOGWHO command output, or is the symbolic name specified by the process definition.
You can also use pattern matching:
MONITOR SUBSYSTEM (optionlist) LIKE 'pattern' FROM 'loc-pattern'
loc-pattern is used to match a client LOCATION parameter. An asterisk (*), meaning all nonlocal locations, is a valid value for loc-pattern. If you use pattern matching, you must specify a pattern for both the subsystem name and location, and you can only match remote location names.
The MONITOR SUBSYSTEM display includes subsystem member locations (if remote) and whether members are optional or mandatory. A client subsystem display also includes items that are not relevant for the server, such as the storage used for resident requests and whether client subsystem files and groups are automatically or manually opened.
For example, this command produces the output that follows:
MONITOR SUBSYSTEM (ALL) SALES FROM BOSTON SUBSYSTEM NAME: SALES FROM BOSTON SUBSYSTEM STATUS: ACTIVE NUMBER OF USERS: 1 NUMBER OF PRECOMPILABLE PROCEDURES (SAVED): 1 FILE: BUYERS STATUS=OPEN,NUSERS=1,DFRD UPDATE=N,MANDATORY FILE: REG1 STATUS=OPEN,NUSERS=1,DFRD UPDATE=N,OPTIONAL FILE: REG2 STATUS=CLOSED,NUSERS=1,DFRD UPDATE=N,OPTIONAL FILE: REG3 STATUS=CLOSED,NUSERS=1,DFRD UPDATE=N,OPTIONAL FILE: TOTLS
Using the STATUS command
For PQO, the STATUS command displays recovery information about remote Model 204 files that were opened during a client Online run.
A STATUS command issued by a client user displays a line with the following format for a remotely opened file:
filename:(REMOTE FILE), LOCATION: name1 ONLINE: name2
where:
- filename is the actual (nonsynonym) name of the remote file.
- name1 is the symbolic name of the file's remote location as specified in the DESTINATION parameter of a local DEFINE PROCESS command.
- name2 is the value of the CCAIN parameter LOCATION in the server Online.
For more information about location references, see Client process DESTINATION parameter and Setting the LOCATION parameter. See STATUS command: Listing file recovery information for details.
Using the VIEW command
Use the VIEW command to display the current settings of Model 204 parameters. In PQO remote file contexts, the VIEW command is not reliable for all file parameters.
In remote file context, reliable VIEW command results are guaranteed only for the following parameters:
ASTRPPG ATRPG CURFILE CURLOC FICREATE FILEORG FITRANS HASHKEY LOCATION OPENCTL RECSCTY SORTKEY
Similarly, for VIEW FPARMS or VIEW TABLES in remote file context, correct information is guaranteed only for the file parameters listed above.
The following examples are of remote file context VIEW command displays for individual file parameters:
- VIEW LOCATION displays the value of the CCAIN LOCATION parameter of the Model 204 copy that the file you are in belongs to.
For example, VIEW LOCATION in remote file context displays a line with the following format:
LOCATION name D204 LOCATION
name is the value specified in the LOCATION parameter in the remote Online's User 0 input stream. See Setting the LOCATION parameter for a description of this parameter.
- VIEW CURFILE displays the name of the file you are currently in.
For example, VIEW CURFILE in remote file context displays a line with the following format:
CURFILE name CURRENT FILE
name is the name given to the file when it was created. No file synonyms or remote file specifications are displayed.
-
VIEW CURLOC displays the current file's location.
For example, VIEW CURLOC in remote file context displays a line with the following format:
CURLOC name CURFILE LOCATION IF REMOTE
name is the symbolic name of the file's remote location as specified in the DESTINATION parameter of a local DEFINE PROCESS command.
If the current file is local, VIEW CURLOC displays a line with the following format:
CURLOC name (LOCAL)
Using the Model 204 audit trail
Technical Support recommends that PQO clients and servers run with a Model 204 audit trail activated. The audit trail can be printed directly by a Model 204 run without requiring a separate job step. It is invaluable for debugging application programs and for analyzing system performance.
For your own diagnostic purposes or when reporting debugging problems to Technical Support, set the Model 204 SYSOPT parameter on server nodes to include audit trail RK lines. The RK lines record calls to Host Language Interface functions, and PQO service threads make use of Model 204 HLI calls to access data.
When you need to conserve audit trail space, turn off the RK lines.
Interpreting communications errors
When you use or attempt to use PQO communications, Model 204 generates messages that track the network activity. Model 204 writes these messages to the system's audit trail.
If an error occurs involving PQO communications, conversation processing is not started or is stopped, and Model 204 automatically displays status codes and sometimes an error message on the client user's terminal or server operator's console. Model 204 also writes the error message to the audit trail of the client or server on which the error occurred.
PQO errors that involve the underlying communications layer are handled differently from application level errors. For a description of error handling at compilation and evaluation time, see Errors during compilation and evaluation.
Communications error display format
Each PQO error condition involving the underlying communications layer is displayed as one or two error messages. One of these messages contains the status codes. The other line, if any, contains a Model 204 message that helps to describe the condition that caused the error.
An error message that includes the status codes has the following format:
M204.nnnn: COMM[UNICATION] ERROR STATUS=nn, STATUSD=nn
The STATUS value refers to the status of the communications statement last executed. This value is a number value greater than or equal to zero. A value of two or greater indicates that a communications error occurred and identifies the error as belonging to a particular category.
STATUSD is set to the return code that details the specific error condition within a particular STATUS category.
STATUS and STATUSD refer to the SOUL $STATUS and $STATUSD function values described in Horizon conversation interface.
Using the status return codes
The STATUS and STATUSD codes that correspond to PQO communications errors are displayed for informational purposes only and cannot be manipulated by the PQO user in a SOUL procedure.
This limitation on use of the status return codes applies only to communications errors.
Using the Model 204 error message
The Rocket Model 204 messages documentation provides a description of Model 204 errors associated with PQO error conditions. Wherever possible, refer to this messages documentation for an explanation of the associated error message.
If an error message is encountered for which no description is available, contact Technical Support for assistance.