IEANTCR — Create a name/token pair
Description
Call the IEANTCR service to create a name/token pair.
Environment
The requirements for the caller are:
Environmental factor | Requirement |
---|---|
Minimum authorization: | Problem state, with any PSW key. Note: Problem-state
programs with PSW key 8 - 15 cannot create system-level pairs.
|
Dispatchable unit mode: | Task or SRB Note: SRB-mode callers cannot
create a task-level pair.
|
Cross memory mode: | Any PASN, any HASN, any SASN |
AMODE: | 31-bit |
ASC mode: | Primary or access register (AR) |
Interrupt status: | Enabled for I/O and external interrupts |
Locks: | No locks held |
Control parameters: | The parameter list and all parameters must reside in the caller's primary address space. |
Programming requirements
* Name/Token Level Constants
*
IEANT_TASK_LEVEL EQU 1
IEANT_HOME_LEVEL EQU 2
IEANT_PRIMARY_LEVEL EQU 3
IEANT_SYSTEM_LEVEL EQU 4
IEANT_TASKAUTH_LEVEL EQU 11
IEANT_HOMEAUTH_LEVEL EQU 12
IEANT_PRIMARYAUTH_LEVEL EQU 13
*
* Name/Token Persistence Constants
*
IEANT_NOPERSIST EQU 0
IEANT_PERSIST EQU 1
IEANT_NOCHECKPOINT EQU 0
IEANT_CHECKPOINTOK EQU 2
*
* Name/Token Return Code Constants
*
IEANT_OK EQU 0
IEANT_DUP_NAME EQU 4
IEANT_NOT_FOUND EQU 4
IEANT_24BITMODE EQU 8
IEANT_NOT_AUTH EQU 16
IEANT_SRB_MODE EQU 20
IEANT_LOCK_HELD EQU 24
IEANT_LEVEL_INVALID EQU 28
IEANT_NAME_INVALID EQU 32
IEANT_PERSIST_INVALID EQU 36
IEANT_AR_INVALID EQU 40
IEANT_UNEXPECTED_ERR EQU 64
Restrictions
- The name/token pair is a system-level persistent name/token pair.
- The resource manager is running for a daughter task of the task that owns the name/token pair.
- The resource manager is running for the task that owns the name/token pair and that resource manager was established for a specific address space and a specific task.
Input register information
Before issuing the IEANTCR callable service, 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
- 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
- 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
Write the call as shown on the syntax diagram. You must code all parameters on the CALL statement in the order shown.
Syntax | Description |
---|---|
CALL IEANTCR
|
,(level ,user_name ,user_token ,persist_option ,return_code) |
1. LOAD EP=IEANTCR
Save the entry point address
(...)
Put the saved entry point address into R15
CALL (15),(...)
2. L 15,X'10'
L 15,X'220'(15,0)
L 15,X'14'(15,0)
L 15,X'04'(15,0)
CALL (15),(...)
This second technique requires AMODE=31, and, before the CALL is issued, verification that the IEANTCR service is supported by the system (in the CVT, both the CVTOSEXT and the CVTOS390 bits are set on).
Parameters
The parameters are explained as follows:
- level
- Specifies a fullword that contains an integer indicating the
level of the name/token pair:
- 1
- Task
- 2
- Home address space
- 3
- Primary address space
- 4
- System.
- ,user_name
- Specifies the 16-byte area containing the name of the name/token
pair that the user creates. The bytes of the name may have any value.
The name may contain blanks, integers, or addresses. Names must be unique within a level. Here are some examples.
- Two task-level name/token pairs owned by the same task cannot have the same name. However, two task-level name/token pairs owned by different tasks can have the same name.
- Two home-address-space-level name/token pairs in the same address space cannot have the same name. However, two home-address-space-level name/token pairs in different address spaces can have the same name.
Because of these unique requirements you must avoid using the same names that IBM® uses for name/token pairs. Do not use the following names:- Names that begin with A through I
- Names that begin with X'00'.
- ,user_token
- Specifies the 16-byte area containing the token of the name/token pair that the user creates.
- ,persist_option
- Specifies a fullword that contains an integer indicating if
a system-level name/token pair should persist after the creating address
space's job step task terminates or if Checkpoint/Restart can
be issued if the program has this task-level name/token pair. If a
program has non-task-level name/token pairs or has task-level name/token
pairs that did not specify IEANT_CHECKPOINTOK, the program cannot
take a checkpoint.
- 0 - system-level pair will not persist and checkpoint is not permitted.
- 1 - system-level pair will persist.
- 2 - checkpoint is permitted.
Note: Only system-level name/token pairs can persist after the creating task terminates. Only task-level name/token pairs can permit checkpoint.You must specify 0 for all other levels. - ,return_code
- Specifies a fullword to contain the return code from the IEANTCR service.
ABEND codes
The caller might encounter abend X'AC7' with a reason code of either X'00030000' or X'00030001'. See z/OS MVS System Codes for an explanation and responses for these codes.
Return and reason codes
When IEANTCR returns control to your program, GPR 15 and return_code contain a return code. The following table identifies return codes in hexadecimal and decimal, tells what each means, and recommends an action that you need to take:
Hexadecimal Return Code | Meaning and Action |
---|---|
00 | Meaning: The operation was
successful. Action: None. |
04 | Meaning: The user_name specified
already exists. Action: Choose a different user_name. |
08 | Meaning: The request is
rejected because the caller is in 24-bit addressing mode. Action: Change your program to 31-bit addressing mode. |
10 | Meaning: An unauthorized
caller attempted to create a system-level name/token pair. Action: Check which level of name/token pair you are creating. |
14 | Meaning: An SRB-mode caller
attempted to create a task-level name/token pair. Action: Change your program to task mode or use a different level. |
18 | Meaning: The caller held
locks. Action: Release all locks before issuing IEANTCR. |
1C | Meaning: The caller specified
an incorrect level. Action: Respecify the correct level. Valid options are 1, 2, 3, or 4. |
20 | Meaning: The caller specified
an incorrect user_name. Action: Respecify the correct user_name. |
24 | Meaning: The caller specified
an incorrect persist_option. Action:
|
28 | Meaning: The caller was
in AR ASC mode and AR1 was not zero. Action: Change your program to primary mode or set AR1 to zero. |
40 | Meaning: A system error
occurred while handling the request. Action: Retry the request. |
Example
TITLE 'NAME/TOKEN EXAMPLE PROGRAM'
NTIDSAMP CSECT
NTIDSAMP AMODE 31
NTIDSAMP RMODE ANY
BAKR R14,0 Save calling programs
* registers and return location
LR R12,R15 ESTABLISH BASE REG
USING NTIDSAMP,R12
***********************************************************************
* INITIALIZE THE NAME AND TOKEN FIELDS *
***********************************************************************
MVC NAME,=CL16'NTIDSAMP NAME ' INITIALIZE NAME FIELD
MVC TOKEN,NAME FOR EXAMPLE, MAKE TOKEN THE
* SAME AS THE NAME
***********************************************************************
* TASK LEVEL CREATE EXAMPLE *
***********************************************************************
CALL IEANTCR,(LEVEL,NAME,TOKEN,PERSOPT,RETCODE)
***********************************************************************
CLC RETCODE,=F'0' IS RETURN CODE 0?
BNE ABEND NO, GO ABEND
EJECT
***********************************************************************
* TASK LEVEL RETRIEVE EXAMPLE *
***********************************************************************
CALL IEANTRT,(LEVEL,NAME,TOKEN,RETCODE)
***********************************************************************
CLC RETCODE,=F'0' IS RETURN CODE 0?
BNE ABEND NO, GO ABEND
EJECT
***********************************************************************
* TASK LEVEL DELETE EXAMPLE *
***********************************************************************
CALL IEANTDL,(LEVEL,NAME,RETCODE)
***********************************************************************
CLC RETCODE,=F'0' IS RETURN CODE 0?
BNE ABEND NO, GO ABEND
EJECT
SLR R15,R15 SET RETURN CODE OF ZERO
EXIT PR RETURN TO CALLER
EJECT
ABEND ABEND X'BAD' ABEND IF NONZERO RETURN CODE
EJECT
***********************************************************************
* NAME/TOKEN VARIABLE DECLARES
***********************************************************************
IEANTASM
EJECT
***********************************************************************
* Constants and data areas *
***********************************************************************
LEVEL DC A(IEANT_TASK_LEVEL) Task level
NAME DS CL16 Name for name/token pair
TOKEN DS XL16 Token for name/token pair
PERSOPT DC A(IEANT_NOPERSIST) Persist option
RETCODE DS F Return code
***********************************************************************
* EQUATES
***********************************************************************
R1 EQU 1
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
END NTIDSAMP