Horizon error processing
Overview
Most Horizon errors do not cause the SOUL program to be cancelled. Usually, however, the appropriate programmatic action when an error is detected is to display diagnostic information, terminate the program, and debug the problem.
Debugging program-to-program errors is more difficult than debugging a single program, because there are more places where problems may occur. There are two or more programs, running asynchronously at different nodes, and there are numerous network components connecting them.
This topic discusses the detection and troubleshooting of typical types of Horizon error conditions and provides a table containing the Horizon error codes and messages.
The Rocket Model 204 Messages Manual contains descriptive and debugging information for many of the Horizon error conditions that are accompanied by a Model 204 error message number.
Detecting Horizon errors
Unlike most other SOUL statements, when a Horizon statement is executed, certain status information is set to indicate whether the statement completed normally. In cases of error, this status information may not only indicate the type of error but also may contain directions about how to correct the error.
It is the responsibility of the application program to check this status information and to detect and handle errors.
Conversation status information
Information about the current condition of a Horizon conversation is communicated to the SOUL program through the following means:
- The $Status and $StatusD functions.
- The RESULT variable (on RECEIVE statements).
- The REQSEND variable (on the SEND, CONFIRM, and SEND ERROR statements).
- The QUERY PROCESS statement, for additional information, such as conversation state.
For more about the RESULT, REQSEND, and conversation state information pertaining to individual Horizon conversation interface statements, see the descriptions of each statement in Horizon conversation interface.
The execution of a Horizon SOUL statement always sets $Status to some integer. Since each $Status code provides general information about the current condition of the conversation, the application program should include some logic to test $Status after each Horizon statement. When $Status indicates an error has occurred ($Status=2 or greater), a Model 204 message is generated.
The individual $Status (and $StatusD) codes and messages are listed in tabular format in $Status/$StatusD codes and accompanying error messages.
Note: Model 204 (as opposed to Horizon) error messages generated during Horizon program execution are not written to the user's terminal. They can be retrieved programmatically, however, using the $Errmsg function.
Client versus server error detection and debugging
Client processes usually run on a thread that has a terminal. The exceptional situation is when a server process initiates a conversation (becomes a client process) with a third partner. The presence of the terminal permits interactive debugging: the developer can insert PRINT statements into trace processing routines to display status information about the conversation and to create break points, for example.
A server process, on the other hand, does not have access to a terminal. Messages are only written to the audit trail or the operator's console. Debugging a server process usually involves embedding AUDIT (rather than PRINT) statements and browsing the audit trail for messages originating from the thread on which the server process ran.
Troubleshooting Horizon errors
In this section, the general categories of Horizon errors are listed, followed by discussions of typical debugging approaches for OPEN PROCESS errors and errors producing unanticipated conversation terminations.
Types of errors
There are several types of Horizon errors, corresponding to different values of $Status. The list below describes briefly the types of errors. All the $Status (and $StatusD) codes and messages are listed in tabular format in $Status/$StatusD codes and accompanying error messages.
- State check ($Status=3).
The program has issued a Horizon SOUL statement that is invalid for the current state of the conversation. State checks are described further in Horizon conversation data flow.
-
Partner closed the conversation ($Status=4).
This occurs if a partner has terminated or issued a CLOSE PROCESS statement.
-
Parameter check ($Status=5).
One or more parameters of a Horizon statement or Horizon entity definition is incorrect.
-
System failures ($Status=10 or greater).
A Horizon system component has failed or is unavailable. Unlike the other types of errors, this is generally not an application program bug. There are four kinds of system failures:
- Local allocation: a conversation could not be established because of a lack of resources at the node where the program is running.
- Remote allocation: a conversation could not be established because of a lack of resources at the node to which the connection was being attempted.
- Session: failure of the LU 6.2 session on which the conversation was running.
- Link: a SNA Communications Server (formerly VTAM) error occurred.
-
Partner issued SEND ERROR statement ($Status=2).
Unlike the other types of errors, this is an application-level error. It allows a program to create an error condition that is communicated to its partner. See SEND ERROR statement for details.
OPEN PROCESS errors
While many of the types of errors described in the previous section can occur throughout the life of a conversation, one error situation is likely to be the most frequent: a system failure encountered during a client program's OPEN PROCESS statement and the subsequent attempt at the server node to start the requested partner process.
As described in OPEN PROCESS statement, such an error is not always received immediately following the OPEN PROCESS statement. Most Horizon statements simply cause LU 6.2 requests to be buffered until physical transmission becomes necessary, which may be several Horizon statements later. Consequently, a client program may not receive an indication of a remote allocation failure until some later statement.
For more information about the physical sending of requests, see Buffering and shipping conversation information.
OPEN PROCESS errors received immediately
The types of errors typically seen at OPEN PROCESS time on the client side are the following:
- State Check
- Parameter Check
- Retryable and Non-Retryable Local Allocation errors
Generally the remedy is simple. For example, suppose that following an OPEN PROCESS statement, $Status=5 and $StatusD=4. This is a parameter check error: entity not defined. After making sure that the process name is correctly spelled, check with the system manager to make sure a process definition exists.
When an error from the server side is returned on a subsequent Horizon statement, tracking it down is not so simple.
OPEN PROCESS errors traced to the server
When a client program receives an error that can be traced to the server side, it is almost always necessary to look in the server system's audit trail for an indication of what happened. Because Horizon is based on the LU 6.2 protocol, only limited information can be transmitted along with an error: The return of detailed information about why the conversation failed is considered a breach of security.
For example, a server program may fail due to a shortage of any one of a number of Model 204 or network resources. A Model 204 error message pinpointing the reason for the failure is generated at that server node; however, the error notification received by the client program only indicates that a resource shortage occurred at the server. The audit trail at the server node must be looked at to find out what resource is not available.
For security violations, Horizon sends only an indication that there has been a security violation. To determine if the USERID or PASSWORD value is incorrect, for example, it is necessary to look in the audit trail at the server node.
Troubleshooting conversation initiation layers for server errors
To determine where the fault is on the server side, consider the layers that a conversation request must pass through for the conversation to start:
To determine from the client side where the server problem is, the developer should examine each layer in turn. Examples follow of kinds of errors at each layer:
- If there are no sessions available or the remote LU is not active, the conversation fails.
- If the Horizon network definitions are not correct, the remote LU might not be known at the local node.
- If the security requirements at the remote node are not met, the conversation fails.
- If the server program is not defined, the conversation fails.
- If the partner application subsystem is not started, the conversation fails.
Because each layer can generate a variety of errors, a systematic examination of the conversation initiation layers is the most productive debugging approach.
Unanticipated conversation termination
Another error, which can occur at any time, is an abnormal termination of conversation by the partner ($Status=4, $StatusD=1). A variety of events at the partner node can result in abnormal conversation termination, including:
- Bumping of the partner thread.
- Termination of the partner process due to program errors.
- Issuing of CLOSE LINK FORCE by the partner's LU.
The only way to determine what went wrong is to examine the audit trail at the partner node for messages associated with the conversation that ended.
$Status/$StatusD codes and accompanying error messages
The following table lists the possible combinations of return values of the $Status and $StatusD functions and a brief description of each combination.
In addition to the $Status and $StatusD information, you can use the $Errmsg function to retrieve the Model 204 error message numbers generated along with $Status and $StatusD. The message text associated with the message number (along with debugging hints when appropriate) is found in the Rocket Model 204 Messages Manual.
| $Status | $StatusD | Description | Error message number |
|---|---|---|---|
| 0 | 0 | Normal completion; no unusual conditions. | none |
| 1 | 0 | Normal completion; check RESULT variable. | none |
| 1 | 1 | Specified event(s) not pending (WAIT or TEST). | none |
| 1 | 2 | Specified event(s0 still pending (TEST). | none |
| 1 | 3 | WAIT completed due to timeout. | none |
| 2 | 2 | SEND ERROR statement issued by partner (Horizon only) | none |
| 3 | 3 | State check: verb issued in wrong conversation state. | 1254 |
| 4 | 0 | Conversation ended normally by partner process.
The partner process has finished executing, or it has ended the conversation by issuing a CLOSE PROCESS statement. |
none |
| 4 | 1 | Partner process closed conversation abnormally. | none |
| 5 | 1 | Password required.
If the USERID keyword parameter is provided on the OPEN PROCESS statement, the PASSWORD parameter must also be provided. |
1950 |
| 5 | 2 | Process is already open.
The OPEN PROCESS statement being executed specifies a process name or CID for a process that is already open. |
1499 |
| 5 | 3 | Initial (PIP) data incorrectly specified. | 2031 |
| 5 | 4 | Entity (process, processgroup, or link) not defined. | 1743 |
| 5 | 5 | Process has not been opened. | 1572 |
| 5 | 6 | Statement or option not supported. | 1811 |
| 5 | 11 | Process may only be opened within an application subsystem. | 1948 |
| 5 | 12 | Process definition requires 'OPEN' for security parameters.
The OPEN PROCES STATEMENT being executed contains an ACCOUNT or USERID parameter. This is only valid when the process definition specifies ACCTSOURCE=OPEN or UIDSOURCE=OPEN (PROFILE and PROFSOURCE may be written instead of ACCOUNT and ACCTSOURCE). |
1949 |
| 5 | 13 | Security violation. | 1951*
2027** |
| 5 | 14 | SESPARMS was specified on the processgroup definition but is not valid for Horizon links. | none |
| 5 | 15 | OPEN type conflicts with PROCESS type. | 1953*
2027** |
| 5 | 16 | Reserved names may not be used in OPEN PROCESS. | 1955 |
| 5 | 17 | Process name or CID is too long. | 2035 |
| 5 | 18 | Synchronization level not supported.
The process issued the CONFIRM verb but the process definition does not contain the CONFIRM parameter |
2036 |
| 5 | 19 | Parameter required but not specified. | 1797 |
| 5 | 20 | Invalid duration value specified for WAIT statement. | 1882 |
| 10 | 1 | Insufficient main storage available at a local node. | 1788 |
| 10 | 2 | Reserved. | |
| 10 | 3 | Local link is not open or is being closed. | 1494 |
| 10 | 4 | Local Processgroup is being stopped. | 1493 |
| 11 | 1 | Partner process temporarily cannot be started. | 2031 |
| 11 | 3 | Retryable remote allocation failure. | 1294
2290 |
| 12 | 1 | Link failure. | 1325 |
| 13 | 1 | Session failure. | none |
| 13 | 2 | Reserved. | |
| 13 | 3 | Connection failure for parallel session setup. | none |
| 50 | 1 | Local session limit has been reached. | 1496 |
| 50 | 2 | Local conversation limit has been reached. | 1495 |
| 50 | 3 | Server process subsystem could not be started because APSY is not initialized. | |
| 50 | 4 | Subsystem is not available. The requested server process subsystem is not defined in CCASYS. | |
| 50 | 5 | Input buffer too small for SUBSYSPARM. The SUBSYSPARM value specified in the process definition was larger than the size in the IODEV 27 command line. | |
| 50 | 6 | Synchronization level not supported by local process. Requesting process and local process must agree on CONFIRM or NOCONFIRM. | |
| 50 | 7 | Server security violation. | |
| 51 | 1 | Server process not available (from client's point of view only). | 2031 |
| 51 | 2 | Synchronization level not supported by server LU (from client's point of view only). The server process definition does not specify the same synchronization level as that of the local process (CONFIRM/NONCONFIRM). | 2031 |
| 52 | 1 | Link failure. | none |
| 53 | 1 | Session failure. Check the sense code in the $Errmsg function. | 1432 |
| 53 | 2 | Timeout duration exceeded waiting for response from partner. | 1968 |
| 53 | 3 | Session Bind rejected due to incorrect session parameters. | none |
| 53 | 4 | Unexpected conversation end. |
* Server message
** Client message