Most CICSPlex® SM API commands normally function in a synchronous manner, where your program issues a request and then waits until command processing is complete. However, some of the API commands also support asynchronous processing. This allows you to request data or perform actions without waiting for the request to complete. This support also enables you to receive notification when events of interest occur in the CICSplex.
The API commands you can use to request asynchronous processing are:
The LISTEN command is, by its very nature, an asynchronous request because you are asking to be notified whenever a certain event occurs. The CANCEL command simply cancels an outstanding LISTEN request. The other commands can be used in either a synchronous or asynchronous manner. If you specify the NOWAIT option on any of these commands, the request is processed asynchronously.
The API commands you can use to monitor and receive the results of asynchronous processing are:
Figure 12 illustrates the relationship of these commands to the API environment.
Many of the resources that are managed by CICSPlex SM can notify the system when events occur that are considered significant to the CICSplex. Such events are not scheduled and cannot be anticipated, so a program designed to process these notifications must do so asynchronously. You can identify the event notifications you are interested in by using the LISTEN command.
The events that can be listened for are represented by resource tables with a type of CPSM Notification. For example, an EMASSICK notification is produced by a MAS when a condition occurs that adversely affects the health of the CICS® system. For a list of the CPSM Notification resource tables, and complete descriptions of other resource table's, see CICSPlex System Manager Resource Tables Reference.
When you issue a LISTEN command, the resulting notifications are added to an outstanding data queue for the API processing thread. The number of completed asynchronous requests, including event notifications and requests issued with the NOWAIT option, is reported by the SENTINEL option of the ADDRESS command. You can retrieve the event notifications by issuing a RECEIVE command.
If you specify the NOWAIT option on a GET, PERFORM OBJECT, PERFORM SET, REFRESH, or SET command, the request does not complete processing immediately. Instead, the request is scheduled for processing, the command returns a RESPONSE value of SCHEDULED, and control returns to your program.
While the asynchronous request is executing, your program can perform other processing, even issuing another CICSPlex SM API command. However, as long as a command is active, the result set it has been given to process is unavailable. A RESPONSE value of INUSE is returned if you try to access a result set that is still being processed by an asynchronous request.
An ASYNCREQ resource table record is produced when the asynchronous request completes. The number of completed asynchronous requests, including ASYNCREQ records that represent requests issued with the NOWAIT option, is reported by the SENTINEL option of the ADDRESS command. You can retrieve ASYNCREQ records by issuing a RECEIVE command.
The ASYNCREQ resource table includes much of the information that is normally returned by the command itself. Because control returns to your program before the command completes processing, that information is not available to the command. The information returned in the ASYNCREQ resource table includes:
To keep track of the asynchronous requests your program issues, you can assign each request a unique identifying token. This allows your program to correlate LISTEN requests and requests made with the NOWAIT option with the results of a subsequent RECEIVE command. The CICSPlex SM API makes no use of any tokens you define. User token values are simply held until the associated requests are complete and then returned to your program by the RECEIVE command. You can use any 1- to 4-character value as an identifying token. For example, you might specify:
When you issue a CONNECT command and an API processing thread is established, two control fields are created in the MVS™ address space or CICS system where the program is running. By requesting the addresses of these thread control fields, you can determine if asynchronous output is available without the need for polling or suspending processing.
You can use the ADDRESS ECB() SENTINEL() command to request the addresses of these fields:
The sentinel value increases each time an asynchronous request completes. Examples of completed asynchronous requests include:
The sentinel value decreases when a RECEIVE command is issued.
You can use the RECEIVE command to determine if any of the asynchronous requests you issued have completed. RECEIVE returns the output from those requests. The output returned can be:
As an example, your program might issue a LISTEN command and a GET command with the NOWAIT operand on the same API thread. Then, in response to a RECEIVE command, you would receive either an ASYNCREQ resource table record for the GET command or a resource table record associated with the event you were listening for.
Alternatively, you can use multiple API threads to separate the output returned by subsequent RECEIVE commands. For example, you might create one thread and use it only for receiving event notifications from the LISTEN command. You might also create another thread for use by other API functions. In this way, you can control what output is returned by the RECEIVE commands issued against each thread.
Another reason you might want to create multiple API threads is because each thread can have only 256 asynchronous requests outstanding at one time. If your program issues a large number of asynchronous requests on a single API thread, you should issue the RECEIVE command at regular intervals. If a processing thread reaches its maximum of 256, asynchronous requests are discarded and are not processed.
By default, the RECEIVE command waits until asynchronous output is available before returning control to your program. This means processing is suspended until an asynchronous request completes. As an alternative to waiting indefinitely, you can specify one of these options on the RECEIVE command: