This section describes event-driven processing using certain macros. For a more detailed explanation of “eventing”, see the “Executive Macros” manual [2].
Eventing is used by UPAM to report the completion of an I/O request to a job. The job can
be continued in parallel with the UPAM I/O operation and, when the expected event occurs (in this case, termination of the requested I/O operation), proceed with a contingency process (asynchronous processing).
wait for termination of the requested I/O operation and then proceed (synchronous processing; this is, of course, equally feasible without eventing).
Upon completion of an I/O operation, UPAM sends a message to the associated event item (using the POSSIG macro). Sooner or later this message encounters the request issued by the user (by means of the SOLSIG macro).
When both request and message are present (for the same event item), a contingency process is started or the basic task resumed.
Figure 5: Coordination of user job and UPAM processing
Basic task
The system must be informed of the event items and contingency definitions that are to be used (ENAEI, ENACO macros).
For each I/O operation, the system must be supplied with the address of a file event control block (FECB). I/O operations running in parallel must refer to different FECBs. The maximum number of parallel I/O operations is defined via the FCB operand PAMREQS; for tape files, only PAMREQS=1 may be specified.
The number of contingency definitions depends on whether different procedures are required after execution of I/O operations. If, for instance, the same procedure is to be used in all cases, the contingency definition needs to be coded once only.
A 14-byte FECB (File Event Control Block) must be set up for each event item.
The FCB macro for each file must specify a valid PAMREQS operand; PAMREQS defines the maximum number of concurrent I/O operations which may be requested for that file.
Until the first I/O operation with an FECB is terminated, the FECB must not be used for other I/O operations.
The address of the associated FECB must be specified for each UPAM I/O request (FECB operand in the PAM macro). No wait operations may be requested either explicitly or implicitly by the PAM macro. The instruction sequence read (RD) -> write (WRT) -> wait (WT) for the same block would thus yield an undefined result. The user must wait for the event (I/O termination) before issuing the WRITE call.
After each UPAM I/O request, precisely one request must be issued to the associated event item (SOLSIG macro). The request may also be used to specify whether the basic task is to continue in parallel with the I/O operation or is to wait for it to terminate.
At the start of a contingency process, it is passed the following information via registers 2 and 3:
For PARMOD=31: the I/O operation is initiated using the 31-bit operand list; the required information is transferred in registers 2, 3 and 4:
Register | Information |
2 | contains the event information code. |
3 | the two rightmost bytes contain a post code supplied by the user at the start of the I/O operation, the leftmost byte contains an identifier indicating a UPAM event (X'10'). |
4 | contains the address of the operand list for the operation which has just been completed. |
For PARMOD=24: the I/O operation is initiated using the 24-bit operand list; the required information is held in registers 2 and 3 (as in earlier versions of BS2000):
Register | Information |
2 | contains the event information code. |
3 | the three rightmost bytes contain the address of the operand list for the operation just terminated, the leftmost byte contains the value X'10'. |
If a SOLSIG macro generated with PARMOD=24 or a 24-bit contingency definition is addressed via an operand list created with PARMOD=31, the secondary return code (leftmost byte in register 15) indicates that the sending and receiving lengths are not consistent.
Format of the file event control block (FECB)
The FECB must be aligned on a word boundary. It can be given a symbolic name by means of the IDECB macro.
Executive flag byte
Meaning of field | Field length | Field name |
Internal ID of event item | 4 | CBEVID |
Address of FCB | 4 | CBP1LNK |
Standard device byte | 1 | CBSDB |
Sense bytes | 3x1 | CBSB1, CBSB2, CBSB3 |
Executive flag byte | 1 | CBEFB |
Number of PAM pages transferred | 1 | CBNPA |
A UPAM I/O operation can be terminated in a number of different ways (EFB = Executive flag byte; see FECB):
Normal I/O termination | EFB=X'80' |
I/O operation led to exception condition | EFB=X'C0' |
Unrecoverable error (e.g. hardware fault) | EFB=X'A0' |
In a contingency process, the user can program appropriate responses to the various ways in which an I/O operation can terminate.