Establishing a timer disabled interrupt exit

The system provides a function called set DIE that allows a user-written program to establish a disabled interrupt exit (DIE) routine. The DIE routine gains control asynchronously after a specified real time interval has elapsed.

The set DIE function is available only to programs executing in supervisor state with PSW key zero. The set DIE function allows users to initiate a real time interval by branching to the set DIE system service. When the time interval expires, the user's DIE routine gains control as an extension of the timer second level interrupt handler. It is also possible for a user to set a new time interval from the DIE routine.

Although a program can have an unlimited number of outstanding time intervals at one time, storage and system performance considerations may impose practical and reasonable limits.

Note: The time during which a DIE routine is executing is not charged to the job step time of the interrupted address space.

The caller of the set DIE service routine can be executing in either task control block (TCB) or service request block (SRB) mode, but must be in PSW key zero and supervisor state. The entry point to the set DIE service routine is in field TPCSDIE in the timer supervision work area mapped by macro IEAVVTPC. The address of this work area is in CVT field CVTTPC.

DIE routines execute in an MVS-recognized disabled state, and therefore do not need to obtain the CPU lock. They must, however, comply with the special characteristics and restrictions that apply only to DIE routines, as described in this information.

Note that except where explicitly documented, register descriptions apply to 32-bit GPRs. The exception is for AMODE 64 cases, either invoking a service in AMODE 64 or where an exit routine gets control in AMODE 64.

The caller of the set DIE service routine must provide the following input environment.

Register 1 must contain the address of a user-supplied timer queue element (TQE) whose fields are available from the IHATQE mapping macro. This user TQE must:
- Be a contiguous block of 128 bytes aligned on a double word boundary.
- Reside in SQA.
- Include the following field initialization:
  TQEAID -- zero or a valid ASID, important in case of an address space failure (see Obtaining and freeing the TQE).
  
  TQEVAL -- the desired real time interval (a 64 bit unsigned binary number with bit 51=1 microsecond).
  
  TQEAMODE bit -- set to 1 if you wish +o indicate that the address of the user's DIE in TQEEXIT is pointer defined.
  
  TQEEXIT -- address of the user's DIE. If the TQEAMODE bit is set to 1, the high-order bit of this field, TQEXMODE, must indicate the addressing mode of the user's DIE. If the user's DIE is to execute in 24-bit addressing mode, TQEXMODE=0; if the user's DIE is to execute in 31-bit addressing mode, TQEXMODE=1.
- Have all the other fields cleared to zero.
Registers 2 - 12 must be parameter registers whose input values will be restored in the same registers on entry to the DIE routine.
Register 14 must contain the caller's return address.

Loss of the contents of register 1 and 11-13 occurs upon return from the set DIE service routine. Register 15 contains a return code as follows:

Code: Meaning
0: The TQE was successfully enqueued onto the system's real time queue.
4: Failure - needed clocks are unavailable.

The set DIE service routine does not establish its own recovery routine. Any program calling the set DIE service routine should have its own FRR or ESTAE routine. A program check occurs in the set DIE service routine if the caller is not both in PSW key zero and in supervisor state.

The DIE routine gains control under the system's FRR on the current stack. The DIE itself can optionally establish its own FRR, which should terminate by percolation to let the timer supervision FRR gain control. For additional information on the environmental factors on entry to an FRR, see Environment on entry to an FRR.