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 ─┘  ►─┬──────────────────────────────────┬───────────────────────────────────────►    └─ INTERVAL 
time-interval seconds
 ─┘  ►─┬──────────────────┬───────────────────────────────────────────────────────►    └─ EVENT 
post-ecb
 ─┘  ►─┬───────────────────────────────────────────────┬──────────────────────────►    └─ TASK CODE 
task-code
 ─┬─────────────────────┬─┘                            └─ PRIORITY 
priority 
─┘  ►─┬────────────────────────┬─────────────────────────────────────────────────►    └─ TIMER ID 
ice-address
 ─┘  ►─┬────────────────────────────────────────────────────────────────┬─ . ─────►◄    └─ DATA FROM 
task-data-location
 ─┬─ TO 
end-task-data-location
 ─┬─┘                                     └─ LENGTH 
task-data-length
 ───┘
Parameters
  • WAIT
    Places 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.
  • POST
    Posts 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.
  • START
    Initiates a user-specified task after the specified time interval elapses. If START is specified, the TASK CODE parameter must also be specified.
  • CANCEL
    Cancels the effect of a previous SET TIMER request.
  • INTERVAL
    time-interval
     
    seconds
    Specifies 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.
  • EVENT 
    post-ecb
    Specifies 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 CODE 
    task-code
    Specifies 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.
  • PRIORITY 
    priority
    Specifies 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 ID 
    ice-address
    Specifies 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-address
     references a field to which the ICE address is returned. If CANCEL has been specified, 
    ice-address
     references 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 FROM 
    task-data-location
    Specifies 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.
  • TO 
    end-task-data-location
    Specifies 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.
  • LENGTH 
    task-data-length
    Specifies 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 1
    The 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 2
    The following statement posts the event PODB after 5 seconds have elapsed:
    SET TIMER POST   INTERVAL 5 SECONDS   EVENT PODB   TIMER ID TMR-ID.
  • Example 3
    The 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 4
    The 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.