STIMER

Purpose

Use the STIMER macro to set a timer to a given time period. When time is up, your task will be notified.

At times, a task reaches a point where it needs to have something done for it. The task allocates a certain time period during which it waits for some event to occur. When told that time is up, the task resumes execution.

At other times, a task may be able to continue with other work while waiting for some event to take place. Having allocated a certain time period for this event, the task needs to be told when time is up.

To keep track of these time periods, a task sets a timer, specifying the amount of time it will allow for a certain event to take place.

Parameters

REAL

Indicates that the task will continue with other work while waiting for the specified time to elapse.

exit_routine_address

Specifies the address of an exit routine that will get control at the end of the interval.

This exit routine must be resident in virtual storage and can be specified only with the REAL parameter.

The exit will always be in the AMODE of the caller.

You can write this as an RX-type address, as register (0), or as register (2) through (12).

WAIT

Indicates that the task is to be placed in the WAIT state during the specified time period. At the end of the time period, the task will resume execution.

BINTVL

Specifies the address containing the duration of time allocated for the event.

You must store the amount of time as an unsigned 32 bit binary number in a fullword on a fullword boundary. The low-order bit is equivalent to 0.01 seconds.

You can write this parameter as an RX-type address or as register (1) through (12).

For example, to define a BINTVL you would code:

         DS    0F                Fullword Boundary
BINTIME  DC    B'00000000000000000000001111111111'

DINTVL

Specifies the address containing the duration of time allocated for the event.

You must store the amount of time as EBCDIC characters in the range 0-9 on a doubleword boundary in the following format:

   HHMMSS00

• HH stands for the number of hours.
• MM for the number of minutes.
• SS for the number of seconds.

The maximum amount of time you can specify is 24 hours.

You can write this parameter as an RX-type address or as register (1) through (12).

For example, to define a DINTVL you would code:

         DS    0D                Doubleword Boundary
DECTIME  DC    CL8'00000500'     Wait 5 Seconds

TOD

Specifies the address containing the time of day that marks the end of the time period.

You must store this time of day as EBCDIC characters in the range 0-9 on a doubleword boundary in following format:

   HHMMSS

 

• HH stands for the number of hours.
• MM for the number of minutes.
• SS for the number of seconds.

The maximum amount of time you can specify is 24 hours.

For example, to define a TOD (Time-of-day) time value you would code:

         DS    0D                Doubleword Boundary
TODTIME  DC    CL6'084805'       Wait until 08:48:05 AM

Usage

1. It is the responsibility of the task issuing the STIMER macro to provide storage. The task must see to it that the appropriate time value is stored there before issuing the STIMER macro.
2. If you choose the REAL parameter and you do not specify the address of an exit routine, your task will never know the time has expired. In such a case, the supervisor does not notify your task that time is up.
3. The exit routine is responsible for saving and restoring your task's registers. It also executes in the same state and key as did your task when the latter issued the STIMER macro. After your exit routine completes execution, it returns control to the supervisor.

   Input to the exit routine is:

   Register	Contents
   0 - 12	Unpredictable.
   13	The address of a supervisor-provided save area.
   14	The address to which control will transfer after the exit routine completes processing.
   15	The address of the exit routine.

4. No task can have more than one timer set at the same time. If you enter an STIMER macro before the time period associated with a previous STIMER macro expires, then the second STIMER macro cancels and replaces the first.
5. All time is measured continuously in real time.
6. The SPLEVEL macro need not be issued unless you want a STIMER macro used by GCS that has an expanded parameter list, which is designed for use in the 31-bit addressing mode. A 31-bit parameter list is incompatible if you are running under the 370 Accommodation Facility. However the SPLEVEL macro lets you select either the 24-bit version or the 31-bit version
7. This macro supports both 24 and 31-bit address expansions of the parameter list. The macro expansion is controlled by the internal macro SPLEVEL. The default value is 31.

Return Codes and ABEND Codes

The STIMER macro generates no return codes.