IEAMSCHD — Schedule an SRB

The requirements for the caller are:

• If the caller specifies RMTRADDR, the resource manager termination routine must reside in MVS™ common storage.
• If the caller specifies PRIORITY=ENCLAVE, the enclave token must have been previously obtained through the IWMECREA macro.

• Address space resource managers cannot use the STOKEN parameter.
• If you issue IEAMSCHD from a set DIE routine, you cannot specify PRIORITY=CURRENT, you cannot specify SYNCH=YES, and the DIE routine must be running in supervisor state, with PSW key 0.
• If your program specifies SYNCH=YES and the scheduled SRB issues the SRBSTAT SAVE macro or invokes any services that issue SRBSTAT SAVE, control returns to your program immediately.

Before issuing the IEAMSCHD 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.

None.

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

Syntax	Description
name	name: symbol. Begin name in column 1.
␢	One or more blanks must precede IEAMSCHD macro.
IEAMSCHD
␢	One or more blanks must follow IEAMSCHD macro.
EPADDR=epaddr	epaddr: RS-type address or register (2) - (12).
,ENV=HOME	Default: HOME
,ENV=PRIMARY
,ENV=FULLXM
,ENV=STOKEN
,TARGETSTOKEN=targetstoken	targetstoken: RS-type address or register (2) - (12).
,FEATURE=NONE	Default: NONE
,FEATURE=CRYPTO
,FEATURE=CPMASK
,PRIORITY=LOCAL	Default: LOCAL
,PRIORITY=GLOBAL
,PRIORITY=CURRENT
,PRIORITY=PREEMPT
,PRIORITY=CLIENT
,PRIORITY=ENCLAVE
,MINORPRIORITY=ZERO	Default: ZERO
,MINORPRIORITY=minorpriority	minorpriority: RS-type address or register (2) - (12).
,SRBIDTOKEN=token	token: 16-byte output area.
,CLIENTSTOKEN=clientstoken	clientstoken: RS-type address or register (2) - (12).
,ENCLAVETOKEN=enclavetoken	enclavetoken: RS-type address or register (2) - (12).
,PARM=ZERO	Default: ZERO
,PARM=parm	parm: RS-type address or register (2) - (12).
,FRRADDR=NOFRR	Default: NOFRR
,FRRADDR=frraddr	frraddr: RS-type address or register (2) - (12).
,SDWALOC31=NO	Default: NO
,SDWALOC31=YES
,KEYVALUE=INVOKERKEY	Default: INVOKERKEY
,KEYVALUE=keyvalue	keyvalue: RS-type address or register (2) - (12).
,LLOCK=NO	Default: NO
,LLOCK=YES
,RMTRADDR=NORMTR	Default: NORMTR
,RMTRADDR=rmtraddr	rmtraddr: RS-type address or register (2) - (12).
,PURGESTOKEN=NOPSTOKEN	Default: NOPSTOKEN
,PURGESTOKEN=purgestoken	purgestoken: RS-type address or register (2) - (12).
,PTCBADDR=NOPTCB	Default: NOPTCB
,PTCBADDR=ptcbaddr	ptcbaddr: RS-type address or register (2) - (12).
,FLAGS=NO_FLAGS	Default: NO_FLAGS
,FLAGS=flags	flags: RS-type address or register (2) - (12).
,SYNCH=NO	Default: NO
,SYNCH=YES
,SYNCHCOMPADDR=NOVALUE	Default: NOVALUE
,SYNCHCOMPADDR=compaddr	compaddr: RS-type address or register (2) - (12).
,SYNCHCODEADDR=codeaddr	codeaddr: RS-type address or register (2) - (12).
,SYNCHRSNADDR=rsnaddr	rsnaddr: RS-type address or register (2) - (12).
,RETCODE=retcode	retcode: RS-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION	Default: PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
,PLISTVER=1
,MF=S	Default: MF=S
,MF=(L,list addr)	list addr: RS-type address or register (1) - (12).
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)

The parameters are explained as follows:

EPADDR=epaddr

Specifies the address of the SRB routine to be scheduled for asynchronous execution.

Note: The SRB routine receives control in 31–bit addressing mode.

To code: Specify the name (RS-type), or address in register (2)-(12), of a required 4-byte input parameter.

,ENV=HOME

,ENV=PRIMARY

,ENV=FULLXM

,ENV=STOKEN

Optional input parameter that specifies the addressing and cross memory environment in which the SRB routine is to receive control.

HOME

Specifies that the SRB routine is to receive control in the current home address space.

Default: HOME

PRIMARY

Specifies that the SRB routine is to receive control in the current primary address space.

FULLXM

Specifies that the SRB routine is to receive:

• Control in the scheduling program's current cross memory environment
• A copy of the scheduling program's dispatchable unit-access list (DU-AL). For details about how the system copies a DU-AL, see the topic on access lists in z/OS MVS Extended Addressability Guide.

This provides the SRB routine with addressability to the same address spaces and data spaces as the scheduling program.

STOKEN

Specifies that the SRB routine is to receive control in the address space specified by TARGETSTOKEN=targetstoken. If the target stoken passed is no longer valid, then the caller receives AC7 abend code with reason code X'00080001'.

,TARGETSTOKEN=targetstoken

Specifies the space token (STOKEN) of the address space in which the SRB routine is to receive control.

To code: Specify the name (RS-type), or address in register (2)-(12), of a required 64-bit input parameter.

,PRIORITY=LOCAL

,PRIORITY=GLOBAL

,PRIORITY=CURRENT

,PRIORITY=PREEMPT

,PRIORITY=CLIENT

,PRIORITY=ENCLAVE

Optional input parameter that specifies the priority at which the SRB routine is dispatched, and whether the SRB is to be preempted.

LOCAL

Schedules an SRB at a priority equal to that of the address space into which it was scheduled. With a LOCAL priority, an SRB has a higher priority than any task or preemptable SRB in that address space.

Default: LOCAL

GLOBAL

Schedules an SRB at a priority equal to the highest priority work in the system, regardless of the address space into which it was scheduled. An SRB scheduled with PRIORITY=GLOBAL is not preemptable.

CURRENT

Schedule an SRB at a priority equal to that of the scheduling work unit.

Task Mode Callers: For task mode callers, the SRB is always preemptable. If the task has joined an enclave, the SRB routine inherits the enclave's major priority and the task's minor priority. Otherwise, the SRB routine inherits the major priority of the task's home address space and the minor priority of the task. If the scheduling task and the scheduled SRB have different home address spaces, then the scheduled SRB is also converted to a client SRB.

Nonpreemptable SRB Mode Callers: For SRB mode callers that are not preemptable, the scheduled SRB inherits the PRIORITY option used to schedule the scheduling SRB routine:

• If PRIORITY=GLOBAL was used, the scheduled SRB will have a priority as high as the highest priority in the system.
• If PRIORITY=LOCAL was used, the scheduled SRB will have a priority that is higher than any task or preemptable SRB in the scheduled SRB's home address space.

Preemptable SRB Mode Callers: For preemptable SRB mode callers, the scheduled SRB is always preemptable. If the scheduling SRB was scheduled into an enclave, the scheduled SRB inherits the enclave's major priority and the scheduling SRB's minor priority. Otherwise, the scheduled SRB inherits the major priority of the scheduling SRB's home address space and the minor priority of the scheduling SRB. If the scheduling SRB and the scheduled SRB have different home address spaces, then the scheduled SRB is also converted to a client SRB.

PREEMPT

Schedules a preemptable SRB routine that inherits the major priority of the target home address space (the home address space as specified on the ENV parameter).

CLIENT

Schedules a preemptable SRB that inherits the major priority of the address space named by the STOKEN specified on the CLIENTSTOKEN parameter. The processor time used by this SRB is accumulated in the address space specified by the clientstoken.

ENCLAVE

Schedules a preemptable RB into an enclave. The SRB inherits the major priority of the enclave specified on the ENCLAVETOKEN keyword. The processor time used by this SRB is accumulated in the enclave specified by the enclavetoken.

,MINORPRIORITY=ZERO

,MINORPRIORITY=minorpriority

Specifies the minor priority to assign to the SRB routine. SRB routines with higher minor priority are dispatched before preemptable-class SRB routines and before tasks with lower minor priority in the same address space. A minor priority of X'00' is the lowest and X'FF' is the highest.

The minor priority parameter assigns the SRB routine a priority that is comparable to a task's dispatching priority in the address space. The caller can specify priorities for SRB routines so that they are dispatched before, with, or after tasks in the address space.

Default: ZERO

To code: Specify the name (RS-type), or address in register (2)-(12), of an 8-bit input parameter. MINORPRIORITY is optional for PRIORITY=PREEMPT, PRIORITY=CLIENT, and PRIORITY=ENCLAVE.

,SRBIDTOKEN=token

Specifies the name of an optional 16-byte output area where a token is placed to be used to fully identify the SRB to the system. The token is used to request termination of a preemptable SRB via CALLRTM TYPE=SRBTERM. The SRBIDTOKEN keyword may be used even if the program runs on a release for which the support is not provided or on a release on which the support is not installed. If the program is running on a release that supports SRBIDTOKEN, the returned SRBIDTOKEN will have a non-zero value in the first eight bytes.

SRBIDTOKEN is optional for PRIORITY=PREEMPT, PRIORITY=CLIENT, and PRIORITY=ENCLAVE.

,CLIENTSTOKEN=clientstoken

Specifies the space token (STOKEN) of the address space where the processor time used by the SRB is to be accumulated. The SRB also inherits the major priority of this address space. This parameter is a required input parameter for PRIORITY=CLIENT.

To code: Specify the name (RS-type), or address in register (2)-(12), of a required 64-bit parameter.

,ENCLAVETOKEN=enclavetoken

Specifies the enclave token representing the group of SRB routines. The enclave token must be obtained prior to scheduling the SRB.

To code: Specify the name (RS-type), or address in register (2)-(12), of an 8-character input parameter. ENCLAVETOKEN=enclavetoken is required for PRIORITY=ENCLAVE.

,FEATURE=NONE

,FEATURE=CRYPTO

,FEATURE=CPMASK

Optional parameter that specifies affinity to specific processors.

NONE

Specifies that there is no affinity to specific processors.

Default: NONE

CRYPTO

Specifies that the SRB routine must run on a processor that has an Integrated Cryptographic Feature (ICRF) associated with it. When you specify this parameter, the system assigns the correct processor affinity for the SRB routine. Use FEATURE=CRYPTO only for SRB routines whose exclusive purpose is to encrypt or decrypt data.

LLOCK=NO

LLOCK=YES

Specifies whether the SRB is to receive control with the LOCAL lock held. The LOCAL lock is the lock of the home address space.

Default: NO

,FRRADDR=NOFRR

,FRRADDR=frraddr

Specifies the name (RS-type), or address in register (2)-(12), of an optional 4 byte input that contains the address of the Functional Recovery Routine (FRR) that is to be established prior to the SRB routine receiving control. The low bit of this address should not be set on. If it is set on, that bit will not be treated as part of the FRR address, but will be treated as indicating SDWALOC31=YES and will override the specification, or default, of SDWALOC31=NO.

The FRR receives control in supervisor state, PSW key 0, primary ASC mode, 31-bit addressing mode, holding the same locks the SRB routine held at the time of error. The FRR receives control with the same PASID, SASID, and HASID as the SRB routine had on entry.

If you specify LLOCK=YES, then the FRR should release the LOCAL lock prior to the completion of its processing.

Default: NOFRR. The SRB routine will receive control without its own FRR.

To code: Specify the name (RS-type), or address in register (2)-(12), of an optional 4-byte input parameter.

SDWALOC31=NO

SDWALOC31=YES

Specifies whether the FRR specified by FRRADDR can tolerate an SDWA in 31-bit addressable storage. Considering that 31-bit storage is less likely to be constrained than 24-bit storage and RTM skips FRRs for which it can not obtain an SDWA, use SDWALOC31=YES whenever possible. SDWALOC31 is valid only for FRRADDR.

Default: NO

,KEYVALUE=INVOKERKEY

,KEYVALUE=keyvalue

Specifies the name or address of an optional 8-bit input. Bits 0-3 contain the PSW key in which the SRB is to receive control. Bits 4-7 are ignored. For example, the byte required to specify PSW key 7 contains the value X'70', and the byte required to specify PSW key 11 contains the value X'BO'.

Default: INVOKERKEY

If INVOKERKEY is not specified the SRB routine receives control with the PSW key of the invoker of the IEAMSCHD macro.

To code: Specify the name (RS-type), or address in register (2)-(12), of an optional 8-bit input parameter.

RMTRADDR=NORMTR

RMTRADDR=rmtraddr

Specifies the address of an SRB resource manager termination routine (RMTR). RMTRs are responsible for cleaning up resources on behalf of an SRB routine that has been purged by the PURGEDQ service before the SRB is first dispatched.

The RMTR must reside in the MVS common area because the address space where the RMTR will get control is unpredictable at the time of the invocation of the IEAMSCHD macro. It is called from the PURGEDQ service and will receive control in task mode, supervisor state, PSW key 0, primary ASC mode, and 31-bit AMODE. If bit 31 of the RMTRADDR is one, control is received with the local lock held and control can return to the PURGEDQ service with or without the local lock held, but must not hold any other locks upon return. If bit 31 of the RMTRADDR is zero, control is received with no locks held and control must be returned to the PURGEDQ service with no locks held. Bit 31 of RMTRADDR is treated as zero when determining the RMTR address.

Default: NORMTR

To code: Specify the name (RS-type), or address in register (2)-(12), of an optional 4-byte input parameter.

,PARM=ZERO

,PARM=parm

Specifies input to be loaded into register 1 when the SRB routine receives control.

Default: ZERO

To code: Specify the name (RS-type), or address in register (2)-(12), of a fullword input parameter.

,PURGESTOKEN=NOPSTOKEN

,PURGESTOKEN=purgestoken

Specifies the space token of an address space to be associated with this SRB routine. During memory termination, all SRB routines that are scheduled into the address space and have not received control are purged and control will be given to each SRB routine's RMTR.

The address space represented by the purgestoken does not have to be the same as the address space where the SRB routine will be dispatched.

Default: NOPSTOKEN

To code: Specify the name (RS-type), or address in register (2)-(12), of an optional 64-bit input parameter.

,PTCBADDR=NOPTCB

,PTCBADDR=ptcbaddr

Specifies the address of the TCB to be related to the SRB routine. When a SYNCH=NO SRB routine scheduled with a related task terminates abnormally and the FRR for the SRB routine does not exist or percolates, the error is percolated to the recovery routine of the related task. This is known as SRB-to-task percolation.

If you specify PTCBADDR, then you must specify PURGESTOKEN.

Default: NOPTCB

To code: Specify the name (RS-type), or address in register (2)-(12), of an optional 4-byte input parameter.

,FLAGS=NO_FLAGS

,FLAGS=flags

Specifies an optional 1-byte input/output field that provides information about the scheduling of the SRB. The caller must zero this byte before invoking IEAMSCHD.

• When bit 7 (the x'01' bit) is on, the SRB has been successfully scheduled.
• When bit 7 is off, but bit 6 (the x'02' bit) is on, the system had just begun the final part of the scheduling of the SRB, but that did not complete successfully; it is not known whether the SRB will or will not get control.
• When both bits 6 and 7 are off, the SRB was not successfully scheduled. This will be an extremely rare circumstance.

These bit definitions are true whether control returns normally to the caller or whether control passes to the caller's recovery. The byte must be in disabled-reference or page-fixed storage.

Default: NO_FLAGS

To code: Specify the name (RS-type), or address in register (2)-(12), of an optional 1-byte input output parameter.

,SYNCH=NO

,SYNCH=YES

Specifies whether or not the caller's work unit is to be suspended until the scheduled SRB completes, is purged, or ends abnormally:

SYNCH=NO

The SRB is to be scheduled but not synchronized with the caller's work unit.

SYNCH=YES

The SRB is to be scheduled and synchronized with the caller's work unit; the caller's work unit is suspended until the SRB completes, is purged, or ends abnormally. SRB to task percolation does not occur when the SRB is scheduled with the SYNCH=YES option.

Default: NO

,SYNCHCOMPADDR=NOVALUE

,SYNCHCOMPADDR=compaddr

When you specify SYNCH=YES, you can specify this optional parameter, which contains one of the following completion codes when the caller's work unit resumes:

Code

Meaning

0

SRB completed successfully.

8

SRB ended abnormally; there is an associated reason code.

12

SRB ended abnormally; there is no associated reason code.

16

PURGEDQ processing purged the SRB.

20

SRB state is undetermined. It was dispatched but did not complete. A probable cause is address space termination or an error in the dynamic address translation (DAT) process.

24

SRB was not scheduled; SYNCHCODEADDR contains the return code from the SUSPEND service.

28

SRB was not scheduled; SYNCHCODEADDR contains the abend code from the SUSPEND service.

Default: NOVALUE

To code: Specify the name (RS-type) of an optional 4-byte input area that contains the address of the fullword that is to hold the data to be returned. When you specify this parameter, you must also specify SYNCHCODEADDR and SYNCHRSNADDR, which can provide additional information about the completion code.

,SYNCHCODEADDR=codeaddr

When the caller's work unit resumes, contains information associated with the completion code returned through SYNCHCOMPADDR. The completion codes and the associated information are:

Code

SYNCHCODEADDR Contents

0

Contents of GPR 15 when the SRB completed.

8

Abend code in the same format as field SDWAABCC in the SDWA.

12

Abend code in the same format as field SDWAABCC in the SDWA.

16

X'FFFFFFFF' (-1), indicating that there is no meaningful value to return.

20

X'FFFFFFFF' (-1), indicating that there is no meaningful value to return.

24

Return code from the SUSPEND service. The SRB was not scheduled because this work unit could not be successfully suspended.

28

Abend code from the SUSPEND service. The SRB was not scheduled because this work unit could not be successfully suspended.

For example, if SYNCHCOMPADDR contains a completion code of 8, then SYNCHCODEADDR contains an abend code. (If the scheduled SRB exits with the TCTL macro, SYNCHCODEADDR does not contain meaningful data; its contents are unpredictable.)

To code: Specify the name (RS-type) of an optional 4-byte input area that contains the address of the fullword that is to hold the data to be returned.

,SYNCHRSNADDR=rsnaddr

When the caller's work unit resumes, contains additional information associated with the completion code returned through SYNCHCOMPADDR and the information returned through SYNCHCODEADDR. The completion codes and the associated information are:

Code

SYNCHRSNADDR Contents

0

Contents of GPR 0 when the SRB completed.

8

Reason code associated with an abend code.

12

X'FFFFFFFF' (-1), indicating that there is no meaningful value to return.

16

X'FFFFFFFF' (-1), indicating that there is no meaningful value to return.

20

X'FFFFFFFF' (-1), indicating that there is no meaningful value to return.

24

X'FFFFFFFF' (-1), indicating that there is no meaningful value to return.

28

Reason code associated with the abend code issued during an unsuccessful attempt to suspend the current work unit.

For example, if SYNCHCOMPADDR contains a completion code of 8, then SYNCHCODEADDR contains an abend code, and SYNCHRSNADDR contains the reason code associated with the abend code. (If the scheduled SRB exits with the TCTL macro, SYNCHCODEADDR and SYNCHRSNADDR do not contain meaningful data; the contents of both are unpredictable.)

To code: Specify the name (RS-type) of an optional 4-byte input area that contains the address of the fullword that is to hold the data to be returned.

,RETCODE=retcode

An optional output parameter into which the return code is to be copied from GPR 15.

To code: Specify the RS-type address of a fullword field, or register (2)-(12).

To code: Specify the RS-type address of a fullword field, or register (2)-(12).

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=0

,PLISTVER=1

An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:

• IMPLIED_VERSION, which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
• MAX, if you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage that your program needs.

  If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.

• 0, if you use only the following parameters:
  • CLIENTSTOKEN
  • ENCLAVETOKEN
  • ENV
  • EPADDR
  • FEATURE
  • FRRADDR
  • KEYVALUE
  • LLOCK
  • MINORPRIORITY
  • PARM
  • PLISTVER
  • PRIORITY
  • PTCBADDR
  • PURGESTOKEN
  • RMTRADDR
  • TARGETSTOKEN
• 1, if you use any of the following parameters, and parameters from version 0, or both:
  • SYNCH
  • SYNCHCODEADDR
  • SYNCHCOMPADDR
  • SYNCHRSNADDR

To code: Specify one of the following:

• IMPLIED_VERSION
• MAX
• A decimal value of 0 or 1

,MF=S

,MF=(L,list addr)

,MF=(L,list addr,attr)

,MF=(L,list addr,0D)

,MF=(E,list addr)

,MF=(E,list addr,COMPLETE)

An optional input parameter that specifies the macro form.

Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.

Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.

Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.

,list addr

The name of a storage area to contain the parameters. For MF=S and MF=E, this can be an RS-type address or an address in register (1)-(12).

,attr

An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.

,COMPLETE

Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.

IEAMSCHD might abnormally end with system completion code AC7. See z/OS MVS System Codes for an explanation and programmer responses for this code.

When the IEAMSCHD macro returns control to your program, GPR 15 contains a return code.

*
SCHED_SRB_RTN  EQU *
               IEAMSCHD  EPADDR=EP_ADDR,ENV=STOKEN,          X
               TARGETSTOKEN=THEIR_STOKEN,                    X
               PRIORITY=LOCAL
*
    .
    .
    .
THEIR_STOKEN   DS    D               Space Token
EP_ADDR        DC    A(SRB_ROUTINE)  SRB Entry Point Address

Note that in this example, the SRB routine is running in a different address space from the scheduling code. To run an SRB routine in a different address space from the scheduling code, the SRB must be either in a different program that is accessible from the target address space, or in the common storage together with the scheduling code.

*
SCHED_SRB_RTN  EQU *
               IEAMSCHD  EPADDR=EP_ADDR,ENV=STOKEN,          X
               TARGETSTOKEN=THEIR_STOKEN,PRIORITY=LOCAL,     X
               SYNCH=YES,SYNCHCOMPADDR=COMPCODE,             X
               SYNCHCODEADDR=ABENDCODE,SYNCHRSNADDR=REASONCODE
*
    .
    .
    .
THEIR_STOKEN   DS    D               Space Token
EP_ADDR        DC    A(SRB_ROUTINE)  SRB Entry Point Address
COMPCODE       DS    F
ABENDCODE      DS    F
REASONCODE     DS    F

Note that in this example, the SRB routine is running in a different address space from the scheduling code. To run an SRB routine in a different address space from the scheduling code, the SRB routine must be either in a different program that is accessible from the target address space, or in the common storage together with the scheduling code.