IEANTRT — Retrieve the token from a name/token pair

Description

Call the IEANTRT service to retrieve the token from a name/token pair. For example, you can use IEANTRT to obtain the name of the logrec recording medium, which is either the name of the logrec data set or the name of the logrec log stream.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state and 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:	The caller can hold a local, CML, or CMS lock; however, no locks are required.
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 macro IEANTASM 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
*
* 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

To obtain the name of the logrec data set or the name of the logrec log stream, you can include the IFBNTASM macro, as well as the IEANTASM macro, in your program. See Example 2 for the list of definitions IFBNTASM provides.

Restrictions

Do not call the IEANTRT callable service with the user_name and user_token parameters in the same storage location.

Input register information

Before issuing the IEANTRT 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 IEANTRT	,(level ,user_name ,user_token ,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 IEANTRT:

  1.   LOAD EP=IEANTRT
       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'08'(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 from which you want to retrieve the token:

1 - Task
2 - Home address space
3 - Primary address space
4 - System.

,user_name

Specifies the 16-byte area containing the name of the requested name/token pair.

,user_token

Specifies the 16-byte area to contain the token of the requested name/token pair.

,return_code)

Specifies a fullword to contain the return code from the IEANTRT service.

ABEND codes

None.

Return and reason codes

When IEANTRT 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 request is rejected because the system could not find the requested name/token pair. Action: Check the `user_name` you specified.
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.
1C	28	Meaning: The caller specified an incorrect `level`. Action: Respecify the correct `level`. Valid values are 1, 2, 3, or 4.
40	64	Meaning: A system error occurred while handling the request. Action: Retry the request.

Example 1

For a complete example of creating, retrieving, and deleting a task-level name/token pair, see the IEANTCR callable service.

Example 2

Following is an example of using Name/Token services to obtain the name of the logrec data set or logrec log stream. (Note that because the routine is not reentrant, module IEANTRT is first loaded and then called.) IEANTRT returns a token that contains a pointer to the name of the logrec data set or logrec log stream.

Before you use name/token services, you can optionally include macro IFBNTASM which provides the following definitions for use in your program:

* IFBNTASM Parameters

IFBNT_DSNLOGREC       DC     CL16'DSNLOGREC       '   System level
*                                      DSNLOGREC name
IFBNT_VERSION1        EQU    X'01'     First version of IFBNT_TOKEN
IFBNT_VERSION2        EQU    X'02'     Second version of IFBNT_TOKEN
IFBNT_LATEST_VERSION  EQU    X'02'     Latest version of IFBNT_TOKEN
*
IFBNT_TOKEN           DSECT  ,         Token area
IFBNT_LOGREC_NAME_PTR DS     A         Address of the LOGREC data
*                                      set name area
IFBNT_VERSION         DS     X         Version of IFBNT_LOGREC
IFBNT_RESV1           DS     X         Reserved for IBM
IFBNT_LENGTH          DS     XL2       Length of IFBNT_LOGREC area
IFBNT_RESV2           DS     CL8       Reserved for IBM
*
IFBNT_LOGREC          DSECT  ,         Pointed to by
*                                      IFBNT_LOGREC_NAME_PTR
IFBNT_LOGREC_NAME     DS     CL44      LOGREC data set name or
*                                      no data set name string (see
*                                      comments at end of mapping)
IFBNT_LOGREC_CURRENT  DS     XL1       Current Logrec recording
*                                      medium
IFBNT_LOGREC_PREVIOUS DS     XL1       Previous Logrec recording
*                                      medium
IFBNT_LOGREC_LOGSTREAM DS     CL26     Logrec log stream name,
*                                      only filled in when
*                                      IFBNT_USE_LOGSTREAM is
*                                      the current medium
IFBNT_LOGREC_LEN      EQU    *-IFBNT_LOGREC  Length of IFBNT_LOGREC
*
********************************************************************
* The following values are used in the following fields:
*   IFBNT_LOGREC_CURRENT
*   IFBNT_LOGREC_PREVIOUS
********************************************************************
IFBNT_USE_DATASET      EQU    X'01'     Logrec data set being used
IFBNT_USE_LOGSTREAM    EQU    X'02'     Logrec log stream being used
IFBNT_IGNORE_RECORDS   EQU    X'03'     Logrec recording is ignored
*
********************************************************************
* If a Logrec data set was not defined during the IPL of the system
* then the following string will appear in field
* IFBNT_LOGREC_NAME = '...NO.LOGREC.DATA.SET.DEFINED...            '
********************************************************************

IFBNT_TOKEN provides a DSECT to map the returned token area.

IFBNT_LOGREC_NAME_PTR contains the address of the logrec data set name.

IFBNT_LOGREC provides a DSECT to map the logrec recording medium.

IFBNT_LOGREC_NAME contains the name of the installation-defined logrec data set or no data set name, if the recording medium is other than a data set.

         TITLE 'DSNLOGREC Name/Token Retrieve Example Routine'
IFBNTXMP AMODE 31
IFBNTXMP RMODE ANY
IFBNTXMP CSECT
         BAKR  R14,0                   Save calling program's
*                                      registers and return location
         LR    R12,R15                 Establish base ref
         USING IFBNTXMP,R12            Set addressability
         MODID BRANCH=YES
*********************************************************************
*  Initialize the NAME field
*********************************************************************
         MVC   NAME,IFBNT_DSNLOGREC    Request DSNLOGREC name
*********************************************************************
*  System level DSNLOGREC Retrieve example
*********************************************************************
         LOAD  EP=IEANTRT              Get address of IEANTRT routine
         LR    R15,R0                  Set address for Call
         CALL  (15),(LEVEL,NAME,TOKEN,RETCODE)
*
         LA    R15,IEANT_OK            Get successful return code value
         C     R15,RETCODE             Was TOKEN Returned?
         BNE   ABEND                   No, Go ABEND
         EJECT
*********************************************************************
*  Get the installation specified LOGREC data set name
*********************************************************************
         LA    R2,TOKEN                Set pointer to TOKEN area
         USING IFBNT_TOKEN,R2          Set addressability
*                                      DSNLOGREC TOKEN area
         L     R2,IFBNT_LOGREC_NAME_PTR  Get pointer to data set name
         DROP  R2                      Free up register 2
         USING IFBNT_LOGREC,R2         Set addressability to
*                                      LOGREC data set name area
*********************************************************************
* If you are interested in obtaining the log stream name, reference
* IFBNT_LOGREC_LOGSTREAM instead of IFBNT_LOGREC_NAME here,
* using the MVC command to move the log stream name to your
* own program's area.
*********************************************************************
         MVC   LOGRNAME,IFBNT_LOGREC_NAME  Move LOGREC data set name
*                                      to own area
         DROP  R2                      Free up register 2
EXIT     DS    0H                      Return point
         SLR   R15,R15                 Set return code of zero
         PR                            Return to caller
         EJECT
ABEND    ABEND X'BAD'                  ABEND if non-zero return code
         EJECT

*********************************************************************
* Local working storage declares
*********************************************************************
NAME     DS    CL16                    Name for Name/Token pair
TOKEN    DS    XL16                    Token for Name/Token Pair
RETCODE  DS    F                       Return code from IEANTRT
LOGRNAME DS    CL44                    Area for LOGREC data set name
*
*********************************************************************
* Constant and Equates
*********************************************************************
LEVEL    DC    A(IEANT_SYSTEM_LEVEL)   SYSTEM LEVEL
R0       EQU   0
R1       EQU   1
R2       EQU   2
R11      EQU   11
R12      EQU   12
R13      EQU   13
R14      EQU   14
R15      EQU   15
         EJECT
*********************************************************************
* NAME/TOKEN SYSTEM LEVEL DSNLOGREC VARIABLE DECLARES
*********************************************************************
         IFBNTASM
         EJECT
*********************************************************************
* NAME/TOKEN VARIABLE DECLARES
*********************************************************************
         IEANTASM
         END   IFBNTXMP