Description

RESMGR allows an authorized program to add (ADD parameter) or delete (DELETE parameter) a resource manager routine.

Upon completion of RESMGR ADD, the resource manager is established for a task or address space. On the TYPE parameter, you choose whether the resource manager routine receives control when a task (TYPE=TASK) or an address space (TYPE=ADDRSPC) terminates. On the ROUTINE parameter, you designate the routine and choose the kind of linkage the routine has with RTM:

For information about the uses of resource managers, see z/OS MVS Programming: Authorized Assembler Services Guide.

Parent topic: RESMGR — Add or delete a resource manager

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Supervisor state or PKM allowing key 0 - 7
Dispatchable unit mode: Task or SRB. However, you cannot issue TCB=CURRENT in SRB mode.
Cross memory mode: Any PASN, any HASN, any SASN
AMODE: 24- or 31-bit
ASC mode: Primary or access register (AR)
Interrupt status: Enabled for I/O and external interrupts
Locks: The caller can hold the local lock, depending on whether the caller is in noncross memory mode or cross memory mode:
  • In noncross memory mode, the caller can hold the local lock for the home (that is, primary) address space.
  • In cross memory mode, the caller can hold the local lock for the primary address space but not for the home address space.

If the caller holds a local lock, it can also hold the CMS lock.
Control parameters: Must be in the primary address space

Programming requirements

None.

Restrictions

None.

Input register information

Before issuing the RESMGR 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 (GPRs) 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 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

The LINK option on the ROUTINE parameter might degrade the performance of the system during task and address space termination.

If you specify TCB=ALL and ASID=ALL, the system invokes the resource manager program for every task termination initiated by the system. You can improve system performance by specifying a particular task or ASID.

Syntax

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

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede RESMGR.
   
RESMGR  
   
␢ One or more blanks must follow RESMGR.
   
ADD  
DELETE  
   
,TOKEN=tokaddr tokaddr: A-type address or register (2) - (12).
   
   ,TYPE=ADDRSPC  
   ,TYPE=TASK  
   
   ,ASID=CURRENT asid: A constant or register (2) - (12).
   ,ASID=ALL  
   ,ASID=asid  
   
   ,TCB=CURRENT  
   ,TCB=ALL  
   ,TCB=tcbaddr tcbaddr: A-type address or register (2) - (12).
   ,TTOKEN=ttoken ttoken: A-type address or register (2) - (12).
   
   ,ROUTINE=(LINK, pgname) pgname: C-type constant, A-type address, or register (2) - (12).
   ,ROUTINE=(BRANCH, pgaddr) pgaddr: A-type address or register (2) - (12).
   ,ROUTINE=(PC, pcnum) pcnum: A constant or register (2) - (12).
   ,ROUTINE=(RLXPC,    
seqnumpcnum)		 seqnumpcnum: A-type address or register (2) - (12).
   
   ,ECB=ecbaddr ecbaddr: A-type address or register (2) - (12).
   
   ,PARAM=paddr paddr: A-type address or register (2) - (12).
   
   ,RELATED=value value: Any valid macro keyword specification.
   

Parameters

The parameters are explained as follows:

ADD
DELETE
Specifies whether a resource manager is to be added or deleted. You must specify the same values for TYPE, TCB, TTOKEN, and ASID on DELETE as you specified on those parameters for ADD. On DELETE, you must specify the token that ADD returned so the system can identify the resource manager that you want to delete.

Note that you can use RESMGR to delete a resource manager from the resource manager routine itself.

,TOKEN=tokaddr
Specifies the address of the fullword where you want the system to store the token that it returns after an ADD. The token represents the resource manager that the system added. On DELETE, however, you store the token in this fullword before invoking the delete function. TOKEN is required for both ADD and DELETE.
,TYPE=ADDRSPC
,TYPE=TASK
Specifies whether the resource manager is an address space resource manager (ADDRSPC) or a task resource manager (TASK). The default is address space. If you specify TYPE=ADDRSPC, you cannot specify TTOKEN=ttoken.
,ASID=CURRENT
,ASID=ALL
,ASID=asid
Specifies the ID of the address space or spaces to be monitored for termination (TYPE=ADDRSPCE) or the home address space or the primary address space (TYPE=TASK). If you want to monitor:
  • The home address space, specify ASID=CURRENT
  • All address spaces, specify ASID=ALL
  • A specific address space, specify ASID=asid.

If TYPE=TASK, asid must be the home or primary address space.

,TCB=CURRENT
,TCB=ALL
,TCB=tcbaddr
,TTOKEN=ttoken
Specifies the task that the system is to monitor for termination. If you want to monitor:
  • The current task, specify TCB=CURRENT. Note that a program in SRB mode or in cross memory mode cannot issue TCB=CURRENT.

    If your program is in cross memory mode and you want to monitor a task in the primary address space, do not specify TCB=CURRENT. In this case, specify the primary address space through ASID=asid and the task through TCB=tcbaddr or TTOKEN=ttoken.

  • All tasks in the specified address space, specify TCB=ALL. If you specify TCB=ALL with ASID=ALL, the system monitors all tasks in all address spaces.
  • A task in the primary or home address space, specify TCB=tcbaddr or TTOKEN=ttoken. Note that TTOKEN is not valid on TYPE=ADDRSPC.

    If your program is in cross memory mode and it holds the local lock for the primary address space, it cannot request monitoring of a task in the home address space.

,ROUTINE=(LINK, pgname)
,ROUTINE=(BRANCH, pgaddr)
,ROUTINE=(PC, pcnum)
,ROUTINE=(RLXPC, seqnumpcnum)
Specifies:
  • the type of linkage to be used by the system when giving control to the resource manager
  • the resource manager to receive control when the task or address space terminates.

The section on resource managers in z/OS MVS Programming: Authorized Assembler Services Guide describes the registers on entry, the resource manager parameter list (RMPL), and some of the responsibilities of the resource manager.

If you specify LINK, the system uses the LINK service. The resource manager routine must reside within the Link Pack Area (LPA) or an APF-authorized library in the LNKLST set that is active when the LINK is issued. The resource manager receives control in the addressing mode defined for that routine. pgname is one of the following:
  • A character constant of up to 8 characters.
  • The address of an eight-byte field. If the name is less than eight characters, left-justify the name and pad with blanks on the right to make up the eight characters.

If you specify PC, the resource manager receives control through a PC instruction. pcnum is the PC number of the PC instruction that gives control to the resource manager. The address space from which the resource manager is called must have the authority to issue the PC.

If you specify RLXPC, the resource manager receives control through a reusable LX PC instruction. pcnumseqnum is the 8-byte area that identifies the PC instruction that gives control to the resource manager. This 8-byte area consists of the following:
  • The 4-byte sequence number of the LX with which the PC number is associated (returned within the output area of the LXRES macro when REUSABLE=YES and EXLIST were specified) followed by
  • The 4-byte PC number
The address space from which the resource manager is called must have the authority to issue the PC.

To code: Specify the 8-byte area, or its address in register (2) - (12).

If you specify BRANCH, the resource manager receives control in 31-bit addressing mode and in primary ASC mode through a branch instruction, and the resource manager (whether address space termination resource manager or task termination resource manager) must reside in storage addressable from all address spaces in which it can get control. Note that for address space termination, resource managers run in master's address space (ASID 1). pgaddr is the address of the resource manager.

ROUTINE is required on the ADD request.

,ECB=ecbaddr
The processing to delete a resource manager might not be complete when RESMGR returns. If you require notification after DELETE has completed, code ECB. The ECB will be posted when DELETE is completed. Note, however, that DELETE may already be complete upon return, in which case the system does not post any completion ECB. Check the return code from RESMGR before you wait on the ECB.
The system associates the completion ECB with the home address space of the DELETE requestor. ECB is valid only for DELETE. You must specify either of the following when you specify ECB:
  • TYPE=ADDRSPC and ASID=ALL
  • TYPE=TASK and ASID=ALL and TCB=ALL.
,PARAM=paddr
Specifies the address of an 8-byte field containing parameter data to be used by the resource manager when it receives control. The parameter data must reside in the caller's primary address space. PARAM is valid only with ADD. A copy of the 8-byte field is passed to the resource manager as the second parameter.
,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 information specified are at the discretion of the user, and may be any valid coding values.

ABEND codes

None.

Return codes from the ADD function

Return codes from the ADD function follow. A return code greater than 4 indicates that RESMGR did not establish a resource manager.

Table 1. Return Codes from the ADD Function
Decimal Return Code Meaning and Action
0 Meaning: The resource manager was successfully established. The word provided by the TOKEN parameter contains the token required to delete the resource manager.

Action: None.
12 Meaning: Program error. The caller did not provide the address of a word to contain the token of the new resource manager.

Action: Issue the macro again with the TOKEN parameter.
16 Meaning: Program error. The caller did not provide the resource manager description through the ROUTINE parameter.

Action: Issue the macro again with the ROUTINE parameter.
20 Meaning: Program error. The TCB address provided did not represent a valid TCB.

Action: Issue the macro again and ensure that the TCB address represents a valid TCB.
24 Meaning: Program error. The ASID provided did not represent a valid ASCB.

Action: Issue the macro again and ensure that the ASCB address represents a valid ASCB.
28 Meaning: Program error. The request type was not ADD or DELETE.

Action: Ensure that the parameter list created by the RESMGR macro is not inadvertently overlaid or the contents lost due to an assembler coding error.
32 Meaning: Environmental error. RESMGR was unable to obtain storage for a work area it needed to process the request.

Action: Rerun your program one or more times. If the problem persists, check with the operator to see if another user in the installation is causing the problem, or if the entire installation is experiencing storage constraint problems.
36 Meaning: Program error. The caller held an incorrect lock.

Action: Ensure only the allowable locks are held before the macro is issued.
40 Meaning: Program error. It is not valid to establish a task resource manager for a specific task that is not in the home or primary address space of the requestor.

Action: Issue the RESMGR macro for a task within the home or primary address space.
44 Meaning: System error. An unrecoverable error occurred while processing the request.

Action: Rerun your program one or more times. If the problem persists, record the return code and supply it to the appropriate IBM® support personnel.
48 Meaning: Environmental error. RESMGR was unable to obtain storage to maintain information about RESMGR.

Action: Rerun your program one or more times. If the problem persists, check with the operator to see if another user in the installation is causing the problem, or if the entire installation is experiencing storage constraint problems.
52 Meaning: Program error. The caller is not authorized to use RESMGR.

Action: Ensure that your program has the proper authorization.
56 Meaning: Environmental error. The TCB was already terminating and no more dynamic resource managers can be established for it.

Action: Attempt to establish the resource manager before the task starts to terminate.
60 Meaning: Environmental error. The ASCB was already in termination and no more dynamic resource managers can be established for it.

Action: Attempt to establish the resource manager before the address space starts to terminate.
64 Meaning: Program error. The TTOKEN parameter specified a task in an address space other than the home address space.

Action: Issue the RESMGR macro from within the address space of the task represented by the specified TTOKEN.

Return codes from the DELETE function

Return codes from the DELETE function follow. A return code greater than 8 indicates that RESMGR did not delete a resource manager.

Table 2. Return Codes from the DELETE Function
Decimal Return Code Meaning and Action
0 Meaning: The resource manager was successfully deleted. An ECB is never posted for this return code.

Action: None.
4 Meaning: The resource manager is currently in use. It has been queued for deletion. The ECB, if provided, will be posted when the delete process has completed.

Action: None.
8 Meaning: The resource manager was queued for deletion by a previous request. It is still active and will be deleted as soon as it is no longer in use.

Action None.
12 Meaning: Program error. The caller did not provide a token to RESMGR.

Action: Specify the TOKEN parameter and value that represents the resource manager to be deleted.
16 Meaning: Program error. The token provided did not represent a currently established resource manager.

Action: Ensure that the token was properly saved after the resource manager was established. Also ensure that the resource manager had not previously been deleted either directly through RESMGR or indirectly through task or address space termination.
20 Meaning: Program error. The TCB address provided did not represent a valid TCB.

Action: Ensure that the TCB represents a valid TCB within the home address space.
24 Meaning: Program error. The ASID provided did not represent a valid ASCB.

Action: Ensure that the ASCB address represents a valid ASCB.
28 Meaning: Program error. The request type was not ADD or DELETE.

Action: Ensure that the parameter list created by the RESMGR macro was not inadvertently overlaid or its contents lost due to an assembler coding error.
32 Meaning: Environmental error. RESMGR was unable to obtain storage for a work area it needed to process the request.

Action: Rerun your program one or more times. If the problem persists, check with the operator to see if another user in the installation is causing the problem, or if the entire installation is experiencing storage constraint problems.
36 Meaning: Program error. The caller held an incorrect lock.

Action: Ensure only the allowable system locks are held prior before the macro is issued.
40 Meaning: Program error. It is not valid to delete a task resource manager for a specific task that is not in the home or primary address space of the requestor.

Action: Issue the RESMGR macro again for a task within the home or primary address space.
44 Meaning: System error. An unrecoverable error occurred while processing the request.

Action: Rerun your program one or more times. If the problem persists, record the return code and supply it to the appropriate IBM support personnel.
48 Meaning: Program error. The ECB parameter was specified but is not supported for the particular type of delete request.

Action: Refer to the ECB parameter description to ensure proper usage of this parameter.
52 Meaning: The caller is not authorized to use RESMGR.

Action: Ensure that your program has the proper authorization.
64 Meaning: Program error. The TTOKEN parameter specified a task in an address space other than the home address space.

Action: Issue the RESMGR macro from within the address space of the task represented by the specified TTOKEN.

Example 1

Establish a resource manager that receives control for every address space termination and every task termination. This resource manager is equivalent to having included the name IAMARESM in the IEAVTRML table. 
RESMGR ADD,TOKEN=MYTOKEN,TYPE=ADDRSPC,ASID=ALL,
         ROUTINE=(LINK,'IAMARESM')

RESMGR ADD,TOKEN=MYTOKEN,TYPE=TASK,ASID=ALL,TCB=ALL,
         ROUTINE=(LINK,'IAMARESM')

Example 2

Establish a resource manager for the current task, using a branch interface and specifying the routine using register notation: 
      L     R2,RMADDR    Obtain address of resource manager routine
      RESMGR ADD,TOKEN=MYTOKEN,TYPE=TASK,ASID=ALL,
               TCB=ALL,ROUTINE=(BRANCH,(R2))

      EXTRN RMROUTIN
RMADDR DC   A(RMROUTIN)  Address of resource manager routine