SET TIMER (COBOL)
The SET TIMER statement defines an event that occurs after a specified time interval or that cancels the effect of a previous SET TIMER request. Using the SET TIMER function, a program can perform the following tasks:
idmscu
The SET TIMER statement defines an event that occurs after a specified time interval or that cancels the effect of a previous SET TIMER request. Using the SET TIMER function, a program can perform the following tasks:
- Delay task processing for a specified timeframe.
- Post an ECB at the end of a specified timeframe.
- Initiate a task at the end of a specified timeframe.
Syntax
►►─── SET TIMER ─┬─ WAIT────┬─────────────────────────────────────────────────► ├─ POST ───┤ ├─ START ──┤ └─ CANCEL ─┘ ►─┬──────────────────────────────────┬───────────────────────────────────────► └─ INTERVALtime-interval seconds─┘ ►─┬──────────────────┬───────────────────────────────────────────────────────► └─ EVENTpost-ecb─┘ ►─┬───────────────────────────────────────────────┬──────────────────────────► └─ TASK CODEtask-code─┬─────────────────────┬─┘ └─ PRIORITYpriority─┘ ►─┬────────────────────────┬─────────────────────────────────────────────────► └─ TIMER IDice-address─┘ ►─┬────────────────────────────────────────────────────────────────┬─ . ─────►◄ └─ DATA FROMtask-data-location─┬─ TOend-task-data-location─┬─┘ └─ LENGTHtask-data-length───┘
Parameters
- WAITPlaces the issuing task in a wait state and redispatches the issuing task after the specified time interval elapses. Because WAIT relinquishes control until the time interval has elapsed, a subsequent SET TIMER request cannot be used to cancel this WAIT request.
- POSTPosts a user-specified ECB after the specified time interval elapses. The issuing task continues to run. If POST is specified, the EVENT parameter must also be specified.
- STARTInitiates a user-specified task after the specified time interval elapses. If START is specified, the TASK CODE parameter must also be specified.
- CANCELCancels the effect of a previous SET TIMER request.
- INTERVALtime-intervalsecondsSpecifies the time, in seconds, from the issuance of a SET TIMER request at which the requested event occurs. Specify the symbolic name of a user-defined field that contains the time interval, or the interval itself expressed as a numeric constant. This option applies only to WAIT, POST, and START requests.
- EVENTpost-ecbSpecifies the ECB to post. Specify the symbolic name of a user-defined area that contains three PIC S9(8) COMP SYNC (fullword) fields. This option applies only to POST requests.The POST instruction only posts an ECB that is within storage owned by the TASK initiating the POST instruction. If the same task does not own the storage, it is not executed.
- TASK CODEtask-codeSpecifies the task to initiate. Specify the symbolic name of the user-defined field that contains the task code, or the task code itself enclosed in quotation marks. The task code must have been defined during system generation or at runtime with a DCMT VARY DYNAMIC TASK command.This option applies only to START requests.
- PRIORITYprioritySpecifies a dispatching priority for the task. Specify the symbolic name of a user-defined field that contains the priority, or the priority itself expressed as a numeric constant in the range 0 through 240. The priority for the new task defaults to the priority that is defined for that task code.
- TIMER IDice-addressSpecifies the address of the interval control element (ICE) that is associated with the timed event. Specify the symbolic name of a user-defined PIC S9(8) COMP SYNC (fullword) field. If POST or START has been specified,ice-addressreferences a field to which the ICE address is returned. If CANCEL has been specified,ice-addressreferences the field containing the ICE address that was returned following a SET TIMER POST or SET TIMER START request. This option applies only to POST, START, and CANCEL requests.If the program is to issue subsequent SET TIMER CANCEL requests, specify TIMER ID with SET TIMER POST and SET TIMER START requests.
- DATA FROMtask-data-locationSpecifies the user data to pass to the new task. Specify the symbolic name of a user-defined field that identifies the beginning of an area containing the data items to pass. This option applies only to START requests.
- TOend-task-data-locationSpecifies the end of the data area being passed to the new task. Specify the symbolic name of a user-defined dummy byte field or a field containing a data item that is not associated with the data area being passed.
- LENGTHtask-data-lengthSpecifies the length of the data area in bytes. Specify the symbolic name of a user-defined WORKING-STORAGE SECTION or LINKAGE SECTION field that contains the length of the data area, or the length itself expressed as a numeric constant.The data that is passed to the new task consists of two bytes containing the length of the original data followed by the original data itself. This data can be accessed by a LINKAGE SECTION entry corresponding to the data and a USING clause in the PROCEDURE DIVISION header.
Examples
The following examples illustrate the use of the SET TIMER statement.
- Example 1The following statement places the issuing task in a wait state and redispatches it after 9 seconds have elapsed:SET TIMER WAIT INTERVAL 9 SECONDS.
- Example 2The following statement posts the event PODB after 5 seconds have elapsed:SET TIMER POST INTERVAL 5 SECONDS EVENT PODB TIMER ID TMR-ID.
- Example 3The following statement starts the SPSG task after 5 seconds have elapsed and passes the specified data to that task:SET TIMER START INTERVAL 5 SECONDS TASK CODE 'SPSG' TIMER ID TMR-ID DATA FROM PASSGR LENGTH REC-LENGTH.
- Example 4The following statement cancels the timed event that TMR-ID references:SET TIMER CANCEL TIMER ID TMR-ID.
Status Codes
After completion of the SET TIMER function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome:
Status code
| Meaning
|
0000 | The request has been serviced successfully. |
3512 | The specified task code is not known to the DC/UCF system. |
3516 | The interval control element (ICE) that was specified for a SET TIMER CANCEL request cannot be found. |
3531 | The parameter list is invalid. |
3532 | The derived length of the data area is negative. |