SET TIMER (DC/UCF)

Data Manipulation Language Statements › SET TIMER (DC/UCF)

SET TIMER (DC/UCF)

The SET TIMER statement defines an event that is to occur after a specified time interval or cancels the effect of a previously issued SET TIMER request. Using the SET TIMER function, a program can:

Delay task processing for a specified period of time
Post an ECB at the end of a specified period of time
Initiate a task at the end of a specified period of time

Syntax

►►─── SET TIMER ─┬─ WAIT ───┬─────────────────────────────────────────────────►
                 ├─ POST ───┤
                 ├─ START ──┤
                 └─ CANCEL ─┘

 ►─┬───────────────────────────────────────────────┬──────────────────────────►
   └─ INTERVAL (time-before-action-taken) SECONDS ─┘

─►─┬────────────────────┬─┬───────────────────────────────────────────────────►─
   └─ EVENT (post-ecb) ─┘ └─ TASK CODE (start-task-code) ─────────────────────

─►────────────────────────────┬───────────────────────────────────────────────►
  ─┬───────────────────────┬──┘
   └─ PRIORITY (priority) ─┘

 ►─┬──────────────────────────┬───────────────────────────────────────────────►
   └─ TIMER ID (ice-address) ─┘

 ►─┬──────────────────────────────────────────────────────────────────────────►─
   └─ DATA FROM (start-task-data-location) ───────────────────────────────────

─►─────────────────────────────────────────┬─ ; ──────────────────────────────►◄
  ─┬─ TO (end-start-task-data-location) ─┬─┘
   └─ LENGTH (start-task-data-location) ─┘

Parameters

WAIT/POST/START/CANCEL

Establishes a time-related event or cancels a previously requested time-dependent action.

WAIT: Places the issuing task in a wait state and instructs the system to redispatch 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 (described below) must also be specified.
START: Initiates a user-specified task after the specified time interval elapses. If START is specified, the TASK CODE parameter (described below) must also be specified.
CANCEL: Cancels the effect of a previously issued SET TIMER request.

INTERVAL (time-before-action-taken) SECONDS

Specifies (for WAIT, POST, START requests only) the time in seconds from the issuance of a SET TIMER request at which the requested event will occur. Time-before-action-taken is either the symbolic name of a user-defined field that contains the time interval or the interval itself expressed as a numeric constant.

Note: For efficiency reasons, the time when the event is to occur is calculated by adding the time-before-action-taken value to the time at which the last TICKER interval expired. Therefore, the actual interval before the event occurs may vary plus or minus from time-before-action-taken by an amount up to the TICKER interval.

For more information about the TICKER interval, see the CA IDMS System Generation Guide.

EVENT (post-ecb)

Specifies (for POST requests only) the ECB to be posted. Post-ecb is the symbolic name of a user-defined area composed of three binary fullword fields that contain the ECB.

TASK CODE (start-task-code)

Specifies (for START requests only) the 1- to 8-character code of the task to be initiated. Start-task-code is either the symbolic name of the user-defined field that contains the task code or the task code itself enclosed in quotation marks. The specified task code must have been defined to the system during system generation or at run time with a DCMT VARY DYNAMIC TASK command.

PRIORITY (priority)

Specifies a dispatching priority for the task. Priority is either 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 new task's priority defaults to the priority defined for that task code.

TIMER ID (ice-address)

Specifies (for POST, START, CANCEL requests only) the address of the interval control element (ICE) associated with the timed event. Ice-address is the symbolic name of a user-defined FIXED BINARY(31) field. If either POST or START has been specified, ice-address references a field to which the system will return the ICE address. If CANCEL has been specified, ice-address references the field that contains the ICE address returned by the system following a SET TIMER POST or SET TIMER START request.

Note: The TIMER ID parameter must be specified with SET TIMER POST and SET TIMER START requests if the program is to issue subsequent SET TIMER CANCEL requests.

DATA FROM (start-task-data-location)

Specifies (for START requests only) the user data to be passed to the new task. Start-task-data-location is the symbolic name of a user-defined field that contains the data to be passed. The length of the data area is determined by one of the following specifications:

TO (end-start-task-data-location): Indicates the end of the data area being passed to the new task and is specified following the last data-item entry in start-task-data-location. End-start-task-data-location is the symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the data area being passed.
LENGTH (start-task-data-location): Specifies the length, in bytes, of the data area. Start-task-data-location is either the symbolic name of a user-defined program variable storage field that contains the length of the data area or the length itself expressed as a numeric constant.

Note: When the new task is started, the first program which receives control in the new task can access this data by observing the following conventions:

The receiving program must access the data as though it had been passed by an Assembler program.
The data will be preceded by a half-word field containing the length of the original data.

Examples

The following statement places the issuing task in a wait state and redispatches it after nine seconds have elapsed:

SET TIMER WAIT
  INTERVAL (9) SECONDS;

The following statement posts the event PODB after five seconds have elapsed:

SET TIMER POST
  INTERVAL (5) SECONDS
  EVENT ('PODB')
  TIMER ID (TMR_ID);

The following code declares a data field, starts the SPSG task after five seconds have elapsed, and passes the specified data to the task:

DECLARE 1 PASSED_DATA,
     2 PASSED_FIXED FIXED,
     2 PASSED_CHAR CHAR(20),
     2 PASSED_END CHAR(1);
SET TIMER START
  INTERVAL (5) SECONDS
  TASK CODE ('SPSG')
  DATA FROM (PASSED_DATA) TO (PASSED_END);

The following code in the program invoked by task SPSG establishes access to the data passed by the above SET TIMER START command:

   SPSGPRG: PROC (PARMIN_DUMMY)
    OPTIONS(MAIN,REENTRANT) REORDER;
   DECLARE 1 PARMIN_DUMMY FIXED;
   DECLARE 1 PARMIN BASED (ADDR(PARMIN_DUMMY)),
        2 PASSED_DATA_LENGTH FIXED BIN(15),
        2 PASSED_DATA,
         3 PASSED_FIXED FIXED,
         3 PASSED_CHAR CHAR(20);

The following statement cancels the timed event referenced by TMR-ID:

SET TIMER CANCEL
  TIMER ID (TMR_ID);

Status Codes

Upon completion of the SET TIMER function, the ERROR_STATUS field in the IDMS DC communications block indicates the outcome of the operation:

0000: The request has been serviced successfully.
3516: The interval control element (ICE) specified for a SET TIMER CANCEL request cannot be found.
3532: The derived length of the data area is negative.