Put job on hold waiting for event
Component: | BS2000 |
Functional area: | Job variables |
Domain: | JOB-VARIABLES |
Privileges: | STD-PROCESSING |
Function
With the WAIT-EVENT command, the user can make the time at which a job runs dependent on user switch settings and time specifications (in procedures or batch jobs only) or on the status of a job variable (JV).
User switches
The user switch settings for the user’s own ID or for another user ID can be interrogated. If the desired switch settings are obtained before the specified time limit (TIME-LIMIT operand) is exceeded, the waiting job is continued with the following command. If the time has elapsed, spin-off is initiated. In a non-S procedure, processing branches to one of the following commands: SET-JOB-STEP, EXIT-JOB, CANCEL-PROCEDURE, END-PROCEDURE or EXIT-PROCEDURE.
In an S procedure, processing branches to the next error handling block (see IF-BLOCK-ERROR command, description of SDF-P error handling).
If no user switches are specified (ON or OFF), any time specification (TIME-LIMIT) is ignored and processing is resumed immediately with the next command.
Time specifications
Time specifications can be entered in the form of a time period or a specific time. After the specified time has elapsed, the waiting job is continued with the next command. This is still the case if the time specification for the waiting is “zero”. If the specified time is in the past, however, the command will be rejected.
Job variables (JV)
The user defines a condition (CONDITION) and sets a time limit (TIME-LIMIT). In addition, the user can specify that the condition is checked if one of the job variables affected by it is modified during the wait time (CHECK-CURRENT-VALUE operand). If the condition is satisfied before the time limit is reached, the waiting job is continued with the next command. If the time has elapsed, processing is continued at the branch destination specified by TIMEOUT-LABEL (if any) or spin-off is initiated.
Format
WAIT-EVENT | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
UNTIL =
Type of event.
UNTIL = *USER-SWITCHES(...)
The job is to wait dependent on user switch settings. If user switches are not specified in the ON and OFF operands, any time specification in the TIME-LIMIT operand is ignored and processing resumes immediately with the following command.
USER-IDENTIFICATION = *OWN / <name 1..8>
User ID whose user switches are to be interrogated. The default value is *OWN, i.e. the user switches of the user ID under which the current job is running are interrogated.
ON = *NONE / list-poss(32): <integer 0..31>
User switches. The job is continued as soon as the specified switches are set to ON and the switches specified in the OFF operand are set to OFF.
The default value is *NONE, i.e. the user switches are not checked to see whether they are set to ON.
OFF = *NONE / list-poss(32): <integer 0..31>
User switches. The job is continued as soon as the specified switches are set to OFF and the switches specified in the ON operand are set to ON.
The default value is *NONE, i.e. the user switches are not checked to see whether they are set to OFF.
TIME-LIMIT = *SHUTDOWN / <integer 0..9999999 minutes>
Time limit in minutes. Maximum time the job is to wait for the event to occur.
UNTIL = *PERIOD(...)
The job is to wait a specific time.
SECONDS = 0 / <integer 0..9999999 seconds>
Time specified in seconds. If the time specification for waiting is “zero”, the command will be rejected.
UNTIL = *DATE(...)
The job is to wait until a specific time. If the time specified is in the past, the command is rejected.
DATE = *TODAY / *TOMORROW / <date>
Date specification.
TIME = <time>
Time specification.
UNTIL = *JV(...)
The length of time that the job waits is to be dependent on the state of a JV.
CONDITION = *NONE / <text 0..1800 with-low cond-expr>
Conditional expression (enclosed in parentheses). The job is continued as soon as the condition is satisfied.
The permitted specifications are described in section "Conditional expressions (job variables)". Special job variables are not allowed.
TIME-LIMIT = 600 / <integer 1..65535 seconds>
Time limit in seconds. Maximum time the job is to wait for the event “condition satisfied” to occur, the time of the check being determined by the CHECK-CURRENT-VALUE operand. Time values greater than 65280 seconds are interpreted as unlimited waiting times.
TIMEOUT-LABEL = *NONE / <name 1..8>
Branch destination. Name of the non-S mark specifying the command with which processing is to continue if the specified time elapses and the event has not yet occurred.
If no branch destination is defined, spin-off is initiated when the time has elapsed. In dialog, specification of a branch destination is ignored and a warning issued.
If WAIT-EVENT was issued within a procedure, the branch destination must also be contained within this procedure, otherwise the procedure is aborted. If the branch destination appears within a CJC command sequence (see the ADD-CJC-ACTION command), it will not be recognized.
CHECK-CURRENT-VALUE = *YES / *NO
Specifies whether the condition should be checked immediately.
The default *YES specifies an immediate check of the condition. If *NO is specified, the condition is checked only if write access takes place to a job variable affected by the condition.
Return codes
(SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
0 | CMD0001 | Command executed | |
1 | 0 | CJC0022 | UNTIL=*JV: |
1 | 0 | CMD0001 | UNTIL=*USER-SWITCHES: |
2 | 0 | CMD0002 | UNTIL=*USER-SWITCHES: |
1 | CMD0202 | Syntax error, error in the condition, branch label not found, or branch label of the WAIT-EVENT command | |
32 | CMD0221 | Internal error | |
32 | EXC0041 | System error | |
64 | CMD0025 | JV catalog exported | |
64 | EXC0868 | User ID not found | |
64 | EXC0878 | Branch destination not found | |
130 | CJC0002 | JV cannot be accessed | |
130 | CJC0003 | Memory saturation | |
130 | CMD2282 | SHUTDOWN or CANCEL-JOB active, user ID locked or file open | |
140 | CMD2382 | SHUTDOWN or CANCEL-JOB active, program loaded, user ID locked or file open |
Notes
The wait state for a job pended by a WAIT-EVENT command (with UNTIL=*JV(...)) can be temporarily suspended to allow execution of CJC command sequences. Thereafter, the job returns to the wait state.
When the command is processed (with UNTIL=*USER-SWITCHES, *PERIOD or *DATE set), all the job’s system resources that were previously requested either implicitly or with a SECURE-RESOURCE-ALLOCATION command are released, i.e. the device requests must be repeated.
The period preceding the branch destination must not be inserted by expression replacement, because then the branch destination as such will no longer be found.