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
Dispatchable unit mode:	Task
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

Before you use name/token services, you can optionally include the IEANTASM macro to invoke name/token services equate (EQU) statements. IEANTASM provides the following constants for use in your program:

* 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

None.

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

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 access registers (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

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)

Link edit your program with a linkage-assist routine (also called a stub) in SYS1.CSSLIB unless you use one of the following techniques as an alternative to CALL IEANTCR:

  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.

,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 Checkpoint/Restart can be issued if the program has this task-level name/token pair.

0 - checkpoint is not permitted
2 - checkpoint is permitted.

Note: 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 should take:

Hexadecimal Return Code	Decimal Return Code	Meaning and Action
00	0	Meaning: The operation was successful. Action: None.
04	4	Meaning: The `user_name` specified already exists. Action: Choose a different `user_name`.
08	8	Meaning: The request is rejected because the caller is in 24-bit addressing mode. Action: Change your program to 31-bit addressing mode.
10	16	Meaning: An unauthorized caller attempted to create a system-level name/token pair. Action: Check which level of name/token pair you are creating.
18	24	Meaning: The caller held locks. Action: Release all locks before issuing IEANTCR.
1C	28	Meaning: The caller specified an incorrect `level`. Action: Respecify the correct `level`. Valid values are 1, 2, or 3.
20	32	Meaning: The caller specified an incorrect `user_name`. Action: Respecify the correct `user_name`.
24	36	Meaning: The caller specified an incorrect `persist_option`. Action: For task-level name/token pairs, you must specify zero or two for the `persist_option`. For home or primary address space level name/token pairs, you must specify zero for the `persist_option`.
28	40	Meaning: The caller was in AR ASC mode and AR1 was not zero. Action: Change your program to primary mode or make sure the parameter list is in the primary address space.
40	64	Meaning: A system error occurred while handling the request. Action: Retry the request.

Example

Initialize the name/token fields, and create, retrieve, and delete a task-level name/token pair.

         TITLE 'NAME/TOKEN EXAMPLE PROGRAM'
NTIDSAMP CSECT
NTIDSAMP AMODE 31
NTIDSAMP RMODE ANY
         BAKR  R14,0                   SAVE CALLING PROGRAM'S
*                                      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