Description

The STIMERM macro:

Sets a timer to a specified time interval (SET parameter)
Tests the remaining time interval for a timer request (TEST parameter)
Cancels a specific timer request (CANCEL parameter)

The SET request sets a timer to a specified time interval or to an interval that will expire at a specified time of day.

A program that is problem state and key 8-15 may not set an STIMERM, if there are currently 16 or more requests in effect for the issuing task.
A program that is supervisor state or key 0-7 may not set an STIMERM, if there are currently 128 requests in effect for the issuing task.

The time interval is a real-time interval, measured continuously. The task can continue (WAIT=NO) or suspend execution (WAIT=YES). If the task continues execution, it can pass control to an exit routine (EXIT parameter) when the time interval is complete. If you specify an exit routine, the task can optionally pass a parameter to the exit routine (PARM parameter). The task grants control to the optional asynchronous timer completion exit when the time interval expires. If the task did not specify either an asynchronous timer completion routine or WAIT=YES, the task receives no indication that the time interval has expired.

The TEST request tests the remaining time interval for a timer request established through the SET parameter. The ID parameter identifies the particular timer request to be tested and must be established by the current task.

The CANCEL request cancels a specific timer request or all of the current task's timer requests that were established through the SET parameter. The ID parameter identifies the timer request or requests of the current task to be cancelled. If the macro cancels a specific timer request, it may return the remaining time interval for that request to a storage area designated by the TU (Timer Units) or MIC (Microseconds) parameters.

On the TEST and CANCEL requests, the TU and MIC parameters specify the location where the system returns the remaining time:

If you specify TU, the STIMERM macro returns the amount of time remaining to the designated 4-byte storage area as an unsigned 32-bit binary number containing the number of timer units (approximately 26.04166 microseconds per unit) remaining in the interval.
If you specify MIC, the STIMERM macro returns the remaining time to the designated 8-byte storage area. Bit 51 of the area is the low-order bit of the interval value and is equivalent to approximately one microsecond.

If the specified timer request does not exist for the current task, or if the timer request exists but has expired, the system sets to zero the storage area designated by TU or MIC.

When you cancel a timer request that specified a timer exit, specify TU or MIC to determine whether the cancel operation was successful:

If STIMERM returned a value of zero to the storage area designated by TU or MIC, then any associated timer exit has run or will run because its interval expired before the cancel operation completed.
If STIMERM returned a non-zero value to the storage area designated by TU or MIC, then the timer interval was cancelled and any associated timer exit will not run.

It is your responsibility to set up your program to determine whether the timer exit has run. For information about interval timing, see z/OS MVS Programming: Assembler Services Guide.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state and any PSW key.
Dispatchable unit mode:	Task
Cross memory mode:	PASN=HASN=SASN
AMODE:	24- or 31- or 64-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O or external interrupts
Locks:	No locks held.
Control parameters:	Must be in the primary address space.

Programming requirements

All input and output addresses are treated as full 31-bit addresses.
The parameter lists may be above or below 16 megabytes.
There is no interaction between the TTIMER macro support and the STIMERM macro support or between the STIMER macro support and the STIMERM macro support.
If the STIMERM macro service cannot access the macro parameter list or any in-storage parameters, the system abnormally ends the calling program whether or not it specified an ERRET routine.

Restrictions

No enabled, unlocked task (EUT) FRRs may be established.

For SET requests:

If you specify a time of day at which the interval will expire (GMT, LT, or TOD parameters), the time of day you specify must not exceed 24:00:00.00; otherwise, you receive a X'32E' abend unless you specify ERRET.
If you specify a time interval on the MICVL parameter, the interval you specify, when added to the current TOD clock contents, must not exceed the maximum value for the clock comparator (X'FFFFFFFFFFFFFFFF'); otherwise, you receive a X'32E' abend unless you specify ERRET.
The time interval specified by a STIMERM macro has no relation to the time interval specified in an EXEC statement.
You can issue STIMERM with a timer completion exit routine and, within that routine, you can issue STIMERM and specify the same timer completion exit routine. Under these circumstances, IBM recommends that you specify a time interval rather than a time of day on the STIMERM you issue within the timer completion exit routine. If you specify a time of day, it is possible for the timer completion exit routine to receive control later than the time of day you specified, resulting in a infinite loop.
The time interval you specify on the BINTVL parameter must not exceed X'7FFFFFFF'. If the time interval exceeds X'7FFFFFFF', your program receives a X'32E' abend unless you use the ERRET parameter to specify a recovery routine.
No enabled, unlocked task (EUT) FRRs can be established.

TEST and CANCEL requests have no restrictions.

Input register information

Before issuing the STIMERM macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter or using it as a base register.

Output register information

When control returns to the caller, the general purpose registers contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code

When control returns to the caller, the access registers (ARs) contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service and restore them after the system returns control.

Performance implications

None.

Syntax

The standard form of the STIMERM macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede STIMERM.

STIMERM

␢	One or more blanks must follow STIMERM.

	Valid parameters (Required parameters are underlined)
SET	For SET: ID, BINTVL or DINTVL or GMT or MICVL or TOD
TEST	or TUINTVL or LT, ERRET, WAIT, EXIT, PARM, RELATED
CANCEL	For TEST: ID, TU or MIC, ERRET, RELATED
	For CANCEL: ID, TU or MIC, ERRET, RELATED

,ID=`stor addr`	`stor addr`: RX-type address or register (2) - (12).
,ID=ALL	Note: ID=ALL is only valid on the CANCEL request.

,TU=`stor addr`	`stor addr`: RX-type address or register (2) - (12).
,MIC=`stor addr`

,BINTVL=`stor addr` ,DINTVL=`stor addr` ,MICVL=`stor addr` ,GMT=`stor addr` ,TUINTVL=`stor addr` ,TOD=`stor addr` ,LT=`stor addr`	`stor addr`: RX-type address or register (2) - (12).

,ERRET=`err rtn addr`	`err rtn addr`: RX-type address or register (2) - (12).

,EXIT=`exit rtn addr`	`exit rtn addr`: RX-type address or register (2) - (12).
	Note: EXIT must not be specified if WAIT=YES is specified.

,PARM=`stor addr`	`stor addr`: RX-type address or register (2) - (12).
	Note: If PARM is specified, EXIT must be specified and WAIT=YES must not be specified.

,WAIT=YES ,WAIT=NO	Default: WAIT=NO

,RELATED=`value`

Parameters

The parameters are explained as follows:

SET

TEST

CANCEL

Request to establish, return, or cancel a real-time interval. You must specify one of these parameters.

SET indicates a request to establish a real-time interval.

TEST indicates a request to return the remaining time for a request made using the SET parameter.

CANCEL indicates a request to cancel and optionally return the remaining time for a timer request.

If the CANCEL parameter specifies (through ID=) a timer request that was established with the WAIT=YES parameter, the task will still remain in the wait condition.

,ID=stor addr

,ID=ALL

Specifies the address of a 4-byte area containing the identifier assigned to a particular timer request by the timer service routine. When you specify STIMERM SET, the ID is returned in the 4-byte area. Specify this ID on STIMERM TEST or STIMERM CANCEL. ID=ALL, valid only on STIMERM CANCEL, cancels all the current task's timer requests as established by STIMERM SET. If you specify ID=ALL, the system does not return a remaining time interval. Do not specify MIC or TU with ID=ALL.

,TU=stor addr

,MIC=stor addr

Specifies that the remaining time in the interval be returned to the 4-byte or 8-byte area specified in stor addr. TU or MIC is required for STIMERM TEST and is optional for STIMERM CANCEL (providing you do not also specify ID=ALL). TU and MIC are mutually exclusive.

For TU, the time is returned to the specified 4-byte area as an unsigned 32-bit binary number. The low-order bit is approximately 26.04166 microseconds (one timer unit). If the time remaining is too great to be expressed in 4 bytes, the remaining time interval is set to the maximum possible value (X'FFFFFFFF') and the return code is set to 4.

For MIC, the time is returned to the specified 8-byte area as microseconds. The 8-byte area stores the remaining interval, which is represented as an unsigned 64-bit binary number; bit 51 is equivalent to one microsecond.

,BINTVL=stor addr

,DINTVL=stor addr

,GMT=stor addr

,MICVL=stor addr

,TUINTVL=stor addr

,TOD=stor addr

,LT=stor addr

Specifies the storage address and format of the time of day, or time interval, to be set. You must specify one of these parameters.

For BINTVL, the address is a 4-byte area containing the time interval. The time interval is represented as an unsigned 32-bit binary number; however, the high-order bit of the time interval must not be set. Therefore, the time interval specified cannot exceed X'7FFFFFFF'. The low-order bit of the time interval has a value of 0.01 second.

For DINTVL, the address is an 8-byte area in virtual storage containing the time interval. The time interval is represented as zoned decimal digits of the form:

HHMMSSth, where:

HH: is hours
MM: is minutes
SS: is seconds
t: is tenths of seconds
h: is hundredths of seconds

For GMT, the address is an 8-byte area containing the Greenwich mean time at which the interval will complete. The time is represented as zoned decimal digits of the form HHMMSSth, as described previously under DINTVL.

For MICVL, the address is an 8-byte storage area containing the time interval. The time interval is represented as an unsigned 64-bit binary number; bit 51 is the low-order bit of the interval value and equivalent to one microsecond.

For TUINTVL, the address is a 4-byte area containing the time interval. The time interval is represented as an unsigned 32-bit binary number; the low-order bit has a value of one timer unit (approximately 26.04166 microseconds).

For TOD and LT, the address is an 8-byte storage area containing the local time of day at which the interval is to be completed. The time of day is represented as zoned decimal digits of the form HHMMSSth, as described previously under DINTVL.

The LT and TOD parameters perform identical functions. However, the name for the LT parameter (LT or local time) describes the function more accurately than does the name for the TOD parameter (TOD or time-of-day). Therefore, for clarity purposes, IBM recommends the use of the LT parameter instead of TOD.

Notes on setting the time interval: For the DINTVL, GMT, TOD, and LT parameters, the zoned decimal digits are not checked for validity. Thus, specifying invalid digits can cause a X'0C7' abend or an undesired time interval.

,ERRET=err rtn addr

Specifies the address of the routine to receive control when the STIMERM function cannot be performed. If you omit this parameter and your program encounters an error, the system abnormally ends your program. The specified error routine will be entered in the addressing mode and environment of the STIMERM invoker.

When the routine receives control, the register contents are:

Register: Contents
0: Address of a 24-byte STIMERM parameter list.
1: Does not contain any information for use by the routine.
2-13: The contents are the same as they were when the caller issued STIMERM.
14: Return address.
15: Return code.

If the macro parameter list or any in-storage parameters are not accessible, the system abnormally ends your program regardless of whether or not you specified ERRET. No error routine will receive control.

,EXIT=exit rtn addr

Specifies the address of an exit routine that will gain asynchronous control after the requested timer interval expires. The system's workload and the relative dispatching priority of the associated task determine exactly when, after the interval completes, the exit routine gets control. The specified exit routine will be entered in the environment of the STIMERM invoker. It will be entered in AMODE 24 if the STIMERM invoker was AMODE 24, AMODE 31 if the STIMERM invoker was AMODE 31, and AMODE 64 if the STIMERM invoker was AMODE 64. If you specify WAIT=YES, you must not specify the EXIT parameter.

Exit Routine Interface: The timer exit routine, established with the EXIT parameter in the STIMERM macro, receives control with the following register values:

R0 -: Does not contain any information for use by the routine
R1 -: Points to an 8-byte fetch-protected storage area below 16 megabytes and in the protect key of the program that issued the STIMERM SET macro
R2-R12 -: Do not contain any information for use by the routine
R13 -: Address of a 72-byte save area provided by the system
R14 -: Return address (to the system)
R15 -: Address of the exit routine

The exit routine receives control in the addressing mode of the STIMERM issuer. If multiple asynchronous exits are established, the exit routines may not receive control in the same order that the intervals expire.

,PARM=stor addr: Specifies the address of a 4-byte parameter that the exit routine receives when the requested timer interval expires. You must not specify PARM=stor addr if you specified WAIT=YES. If you specify PARM=stor addr, you must also specify EXIT=exit rtn addr.
An exit routine will be unable to distinguish between the case where PARM= was not specified and the case where the specified PARM value was zero.
,WAIT=YES
,WAIT=NO: Specifies whether the task should be suspended until the requested time interval expires. WAIT=YES specifies that the task should be suspended until the requested time interval expires. If you specify WAIT=NO without specifying EXIT, you will receive no indication when the timer expires. WAIT=NO is the default.
,RELATED=value: Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the specified information are at your discretion and may be any valid macro keyword expression.

ABEND codes

On STIMERM SET requests:

X'32E'
Abend code X'32E' might yield the following reason codes:
- X'10C'
- X'110'
- X'11C'
- X'120'
- X'128'
X'AC7'
Abend code X'AC7' might yield the following reason code:
- X'2'

On STIMERM TEST requests:

X'32E'
Abend code X'32E' might yield the following reason codes:
- X'210'
- X'220'
- X'224'

On STIMERM CANCEL requests:

X'32E'
Abend code X'32E' might yield the following reason codes:
- X'310'
- X'320'
- X'324'

See z/OS MVS System Codes for explanations and programmer responses for these codes.

Return codes

When control is returned, register 15 contains one of the following hexadecimal return codes. Note that for non-zero return codes, the ERRET routine receives control (if you specified ERRET). If you did not specify ERRET, a non-zero return code causes the STIMERM invoker to end abnormally.

Table 1. Return Codes for the STIMERM Macro
Hexadecimal Return Code	Meaning and Action
00	Meaning: The STIMERM service has completed successfully. Action: None.
04	Meaning: For TEST and CANCEL requests, the time remaining is too great to be expressed in 4 bytes. The maximum value (X'FFFFFFFF') is returned. Action: None required. However, you might take some action based upon your application.
0C	Meaning: Program error. For SET requests, the GMT, LT, or TOD at which the interval is to complete exceeds 24:00:00.00. Action: Specify a time of day value that is less than or equal to 2400 hours.
10	Meaning: Program error. Parameters passed to STIMERM are not valid. Action: Ensure that all input parameters are valid.
1C	Meaning: Program error. The request would cause the limit of concurrent STIMERM SET requests for a task to be exceeded. Action: Change your application logic so that fewer STIMERM requests are required.
24	Meaning: Program error. The specified STIMERM ID number was zero, which is not valid. Action: Ensure that the input ID is a valid value.
28	Meaning: Program error. For SET requests, either you specified a time interval on the MICVL parameter that, when added to the current TOD clock contents, exceeds the maximum value for the clock comparator (X'FFFFFFFFFFFFFFFF') or you specified a value greater than X'7FFFFFFF' for BINTVL. Action: Request a smaller time interval.

Example 1

SET a timer to a specified time interval. Specify:

The address of a 4-byte area in which the identifier assigned by the timer service to this request will be returned
That control should be given to an asynchronous timer completion exit named TIME, when the time interval expires
The address of a 4-byte area (containing the time interval of 32 hundredths of seconds) named INTERVAL. Include an error exit routine named ERROR.

          STIMERM SET,ID=ADDRESS,BINTVL=INTERVAL,EXIT=TIME,ERRET=ERROR
ADDRESS   DS F             ID RETURNED
INTERVAL  DC X'00000020'   TIME INTERVAL

Example 2

SET a timer to a time interval that specifies the address of a 4-byte area in which the identifier assigned by timer service will be returned. Specify the address of an 8-byte area named INTERVAL that contains the Greenwich mean time at which the interval is to be completed (2:06 PM). Specify that the task should be suspended until the requested time interval expires. Include an error exit routine named EXITX.

          STIMERM SET,ID=ADDRESS,GMT=INTERVAL,WAIT=YES,ERRET=EXITX
ADDRESS   DS F                      ID RETURNED
INTERVAL  DC X'F1F4F0F6F0F0F0F0'    EXPIRATION TIME OF DAY

Example 3

SET a timer to a time interval that specifies the address of a 4-byte area in which the identifier assigned by timer service will be returned. Specify the address of an 8-byte area in register 8 that contains the time interval (represented as zoned decimal digits). Specify, in register 10, the address of the exit routine that will gain control asynchronously when the requested time interval expires. Specify the address of a 4-byte parameter to be passed to the exit routine when the requested time interval expires. Include the address of an exit error routine in register 9.

          STIMERM SET,ID=(7),DINTVL=(8),PARM=USERDATA,ERRET=(9),EXIT=(10)
USERDATA  DC CL4'ABCD'     PARAMETER PASSED TO EXIT ROUTINE

Example 4

Test the remaining time interval for a timer request established with the SET parameter, specifying (in register 4) the address of a 4-byte area from which the identifier assigned by the timer service will be obtained. Specify that the time be returned as an unsigned 32-bit binary number in a 4-byte area called INTERVAL. Include the address of an exit error routine called XYZ.

          STIMERM TEST,ID=(4),TU=INTERVAL,ERRET=XYZ
INTERVAL  DS XL4    REMAINING TIME

Example 5

Test the remaining time interval for a timer request established with the SET parameter, specifying the address of a 4-byte area from which the identifier assigned by the timer service will be obtained. Specify that the time be returned in microseconds in an 8-byte area called INTERVAL. Include the address of an exit error routine called ERRORADD.

          STIMERM TEST,ID=ADDR,MIC=INTERVAL,ERRET=ERRORADD
ADDR      DS F      ID TO BE TESTED
INTERVAL  DS XL8    REMAINING TIME

Example 6

Cancel a timer request established with a SET parameter, specifying the address of a 4-byte area named ADDRESS containing the identifier assigned by the timer service. The time interval remaining should be returned as an unsigned 32-bit binary number in a 4-byte area called INTERVAL. An exit error routine named ERROR is also specified.

          STIMERM CANCEL,ID=ADDRESS,TU=INTERVAL,ERRET=ERROR
ADDRESS   DS F      ID TO BE CANCELLED
INTERVAL  DS XL4    REMAINING TIME

Example 7

Cancel a timer request established with a SET parameter, specifying the address of a 4-byte area named PLACE containing the identifier assigned by the timer service. The time interval remaining should be returned in an 8-byte area called INTERVAL. An exit error routine named EXITA is also specified.

          STIMERM CANCEL,ID=PLACE,MIC=INTERVAL,ERRET=EXITA
PLACE     DS F      ID TO BE CANCELLED
INTERVAL  DS XL8    REMAINING TIME

Example 8

Cancel all the timer requests established with STIMERM SET for the current task.

STIMERM CANCEL,ID=ALL