Asynchronous Requests

Most CSL routines that interface with the Shared File System (such as DMSOPEN, DMSERASE, DMSCRLOC) can be issued either synchronously or asynchronously by an application. To process a routine asynchronously means that the server handles the request while control returns to your program so it can continue processing. Asynchronous support is designed for performance-sensitive applications such as service machines or multitasking applications that may be doing other work concurrently.

Note: If you are writing an application that issues asynchronous SFS requests on behalf of other users, you may wish to consider using multiple user ID support.

You can indicate that a request is to be processed asynchronously by specifying a binary 1 in the requestid parameter. This causes CMS to generate an integer that uniquely identifies the asynchronous request. This integer is passed back in the requestid parameter of the routine making the request. You can then specify this value on DMSCHECK to determine if the request has completed. (If a 1 is passed back, it means that no server interaction was required to complete the request.)

Note: All requests to a minidisk will be processed synchronously. If an asynchronous request was issued (requestid = binary 1), the request is still processed synchronously to the minidisk and the requestid will still have a 1 when the CSL routine has completed.

CMS passes the asynchronous request on to the server for processing. When control is returned to your program, the return and reason codes indicate whether the request was accepted or immediately rejected. If the return code is zero, indicating that the request was accepted, your program needs to invoke the DMSCHECK routine with the value returned in requestid to check if the asynchronous request has completed.

You must specify a WAIT or NOWAIT parameter on the DMSCHECK routine. The WAIT parameter means that your program waits until the request you are checking for completes. The NOWAIT parameter means that control returns to your program to continue processing.

Note that a number of server requests may be needed to satisfy a single CSL request. This is particularly true when large amounts of data are being processed. When DMSCHECK is specified with the NOWAIT option, you may need to issue DMSCHECK more than once to complete the request.

The request is not considered to be complete until the DMSCHECK has completed. Both input and output parameters of the initial CSL request may be updated by CMS at any time during this process. The application must not change the contents of these parameters until DMSCHECK completes, or unpredictable results may occur. When DMSCHECK completes, you must examine the return code and reason code parameters of the initial request (for example, DMSOPEN) to determine the outcome of that operation.

If the return code on DMSCHECK is zero, the request has completed and the variables for the request are filled in. A return code of 4 indicates that the request has not yet completed. A return code of 8 indicates that an error occurred. See the z/VM: CMS Callable Services Reference for further information on DMSCHECK.

If there are any asynchronous requests pending when CMS end-of-command processing takes place, the work units with which these requests are associated will be rolled back.

Even when you request asynchronous processing, there are several circumstances in which some synchronous SFS server processing may be performed to satisfy your request. These circumstances include:
  • You specify the COMMIT keyword and other CRR-participating resources (for example, another file pool) are active for this work unit.
  • You specify the COMMIT keyword and you have open SFS output files on the work unit.
  • Your asynchronous CSL request is the first SFS request to the file pool for the specified work unit.
Note: You cannot call any CSL routines asynchronously from a REXX program.

If a work unit has an active asynchronous request, you cannot issue any other request for the affected file pool on that work unit. The only exception to this rule is a rollback request, which could be a rollback routine, such as DMSROLLB, or a routine or macro that causes a rollback, such as the DMSPURWU (Purge Work Unit IDs) routine or the DMSABN macro.