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.
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.
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. |
No enabled, unlocked task (EUT) FRRs may be established.
TEST and CANCEL requests have no restrictions.
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.
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.
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 |
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 |
Default: WAIT=NO |
,RELATED=value | |
The parameters are explained as follows:
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.
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.
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:
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.
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.
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.
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.
See z/OS MVS System Codes for explanations and programmer responses for these 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.
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. |
STIMERM SET,ID=ADDRESS,BINTVL=INTERVAL,EXIT=TIME,ERRET=ERROR
ADDRESS DS F ID RETURNED
INTERVAL DC X'00000020' TIME INTERVAL
STIMERM SET,ID=ADDRESS,GMT=INTERVAL,WAIT=YES,ERRET=EXITX
ADDRESS DS F ID RETURNED
INTERVAL DC X'F1F4F0F6F0F0F0F0' EXPIRATION TIME OF DAY
STIMERM SET,ID=(7),DINTVL=(8),PARM=USERDATA,ERRET=(9),EXIT=(10)
USERDATA DC CL4'ABCD' PARAMETER PASSED TO EXIT ROUTINE
STIMERM TEST,ID=(4),TU=INTERVAL,ERRET=XYZ
INTERVAL DS XL4 REMAINING TIME
STIMERM TEST,ID=ADDR,MIC=INTERVAL,ERRET=ERRORADD
ADDR DS F ID TO BE TESTED
INTERVAL DS XL8 REMAINING TIME
STIMERM CANCEL,ID=ADDRESS,TU=INTERVAL,ERRET=ERROR
ADDRESS DS F ID TO BE CANCELLED
INTERVAL DS XL4 REMAINING TIME
STIMERM CANCEL,ID=PLACE,MIC=INTERVAL,ERRET=EXITA
PLACE DS F ID TO BE CANCELLED
INTERVAL DS XL8 REMAINING TIME
STIMERM CANCEL,ID=ALL