The Roll-for-Event (ROLEVT) function provides a facility that allows the application program to rollout of the thread until an event controlled by a companion JOB (or task) occurs. This facility allows a Com-plete application program to interact with another JOB running in the same machine and provides a synchronization mechanism between the Com-plete program and the companion JOB.
Synchronization of the two tasks is controlled through an Event Control Block (ECB), which is waited on by the ROLEVT function, and which must be posted by the companion task to signal a synchronization. ROLEVT uses a standard operating system WAIT macro to await the event occurrence, and relies on the companion task to issue the operating system POST macro to signal the event occurrence.
The ROLEVT function can be used by any online Com-plete application program, privileged or non-privileged. However, a distinction is made by the ROLEVT function between privileged and non-privileged programs when validating the ECB argument.
For non-privileged programs, the area pointed to by the ECB argument must be located within storage acquired via the Com-plete COMSTOR function. This area is located within the Com-plete partition/address space, but outside of the Com-plete threads. For privileged programs, no address validation is performed.
If the ROLEVT request is rejected, the program is not rolled out and remains in the thread. However, once rolled out as a result of the ROLEVT function, the application remains rolled out until the companion task POST's caller's ECB occurs. The only exception to this is if the application program is cancelled by the computer operator with the operator command CANCEL. When this happens, the application program is rolled back into the thread and terminated abnormally.
- Format
The format for using the ROLEVT function is:
ROLEVT (retcode,CB)The argument is:
retcode Required.
A fullword where Com-plete places the return code upon completion of the operation.CB Specifies the address of a control block to be used to pass information back and forth between the application program and Com-plete. The first word of the control block contains the address of an ECB. The ECB pointed to is used by Com-plete to wait for the event occurrence to be signalled by a POST from a companion task. This area is also used by Com-plete to pass back the status of the ROLEVT function.The area pointed to by this argument is validated by the ROLEVT function, according to the rules established earlier in this section. - Return Codes
The return code parameter or the first word of the control block must be checked for the following conditional values:
0 ROLEVT request accepted. The ROLOUT and subsequent ROLIN has been completed. 4 Invalid control block address specified. 8 COMSTOR does not exist (non-privileged programs). 12 ECB address is not within an area acquired with the Com-plete COMSTOR function (non-privileged program). 16 The specified ECB has already been waited on. - Abends
The only abnormal termination associated with the ROLEVT functions is one indicating that the parameter list is invalid.