Asynchronous processing

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.

Figure 12. API commands for asynchronous processing
 This figure illustrates the use of the asynchronous processing commands LISTEN, CANCEL, , ADDRESS and RECEIVE, and the NOWAIT option.

Using the LISTEN command

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.

Using the NOWAIT option

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:

Note:
To access the ASYNCREQ data from a REXX program, you can use either the CICSPlex SM TPARSE command with the ASIS option or the REXX SUBSTR function.

Using tokens to identify a request

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:

Using the ADDRESS command

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:

ECB
The ECB is posted by the API each time an asynchronous request completes and is added to the thread's outstanding data queue. With the ECB address, you can: The ECB field is cleared whenever the counter value in the SENTINEL field reaches 0.
SENTINEL
The sentinel is a 4-byte counter of completed asynchronous requests associated with the thread.

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.

Notes:
  1. You should use the ADDRESS command before issuing the RECEIVE command. If the sentinel value is 0, it means there are no completed asynchronous requests to be received.
  2. Because of the nature of asynchronous processing, the sentinel value may understate the actual number of outstanding requests at any point in time. When processing multiple asynchronous requests, you should issue the RECEIVE IMMEDIATE command until a response of NODATA is returned to ensure that all output has been received.

Using the RECEIVE command

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:

Note:
Before you issue the RECEIVE command, you should issue the ADDRESS command and check the SENTINEL value to determine if there are any outstanding asynchronous requests to be received. If the sentinel value is 0, there are no outstanding asynchronous requests to be received.

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:

DELAY(data-value)
Checks for asynchronous output, waits the specified number of seconds for output to become available, and then returns control to the processing thread, with or without output.
IMMEDIATE
Checks for asynchronous output and then immediately returns control to the processing thread, whether or not any output is available.
[[ Contents Previous Page | Next Page Index ]]