NTCR - Name/Token pair CReation

Remark:
This document is intended for evaluation of the setup for documentation.
Please e-mail us any comments you may have.

This document contains the following chapters:

1.0 Description

The NTCR macro encapsulates the IEANTCR service described in the various IBM manuals. A list form, an execute form, and an additional generate form of the NTCR macro are supplied. A standard form is not supported.

1.1 Environment

The requirements for the caller are:
Minimum authorization Problem state with any PSW key
For creating system-level name/token pairs additional authorization is required.
Dispatchable unit mode Task or SRB
For creating task-level name/token pairs task mode is required.
Cross memory mode any HASN, any PASN, 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 Must reside in an addressable area in the caller's primary address space.

See the chapter on IEANTCR in the Authorized Assembler Services Reference manual for your level of OS/390 or z/OS for details.

1.2 Programming Requirements

Before using the NTCR macro you have to define all required equates by invoking the MAPIEANT macro. The preferred way to achieve this is to specify IEANT on the MAPS pararmeter of the PGM macro that starts your program.

1.3 Restrictions

The NTCR macro cannot be used in a RESMGR resourcec manager routine. See the chapter on IEANTCR in the Authorized Assembler Services Reference manual for your level of OS/390 or z/OS for details.

1.4 Input Register Information

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

1.5 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.

See the chapter on IEANTCR in the Authorized Assembler Services Reference manual for your level of OS/390 or z/OS for details.

1.6 Performance Implications

None.

1.7 Syntax

The NTCR macro takes five positional parameters, corresponding to the parameters for IEANTCR, and four keyword parameters, which are used to specify values for the input parameters of IEANTCR. The standard form of the NTCR macro, which is not supported, would be written as follows:


name name: Symbol. Begin name in column 1.
One or more blanks must precede NTCR.
NTCR
One or more blanks must follow NTCR.

tok_level RX-type address or register, specifying a fullword in storage that contains the token level. If not specified, a fullword will be appended to the parameter list to contain the level value.
,tok_name RX-type address or register, specifying a 16-byte area in storage that contains the token name. If not specified, a 16-byte area will be appended to the parameter list to contain the token name.
,tok_val RX-type address or register, specifying a 16-byte area in storage that contains the token value. If not specified, a 16-byte area will be appended to the parameter list to contain the token value.
,tok_persist RX-type address or register, specifying a fullword in storage that contains the persist option. If not specified, a fullword will be appended to the parameter list to contain the persist option.
,tok_retcd RX-type address or register, specifying a fullword in storage that is to contain the returncode from IEANTCR. If not specified, a fullword will be appended to the parameter list to receive the return code.
,LVL=level Default: none
level the desired token level
,NAME=name Default: none
name the desired name to be assigned to the token
,TOKEN=token Default: none
token the desired value to be assigned to the token
,PERSIST=option Default: none
option the desired persist option for the token

1.8 Parameters

The parameters are explained as follows:

tok_level
A fullword input field to the IEANTCR service, containing the desired token level. Can be specified as the label of a field, as a register pointing to such a field, or it can be omitted, in which case a fullword field will be appended to the parameter list. If omitted, the LVL= parameter has to specify the initialization value for the field.
,tok_name
A 16-byte input field to the IEANTCR service, containing the name to be assigned to the name/token pair. Can be specified as the label of a field, as a register pointing to such a field, or it can be omitted, in which case a 16-byte area will be appended to the parameter list. If omitted, the NAME= parameter has to specify the initialization value for the field.
,tok_val
A 16-byte input field to the IEANTCR service, containing the token value to be assigned to the name/token pair. Can be specified as the label of a field, as a register pointing to such a field, or it can be omitted, in which case a 16-byte area will be appended to the parameter list. If omitted, the TOKEN= parameter has to specify the initialization value for the field.
,tok_persist
A fullword input field to the IEANTCR service, containing the desired persist option. Can be specified as the label of a field, as a register pointing to such a field, or it can be omitted, in which case a fullword field will be appended to the parameter list. If omitted, the PERSIST= parameter has to specify the initialization value for the field.
,tok_retcd
A fullword output field from the IEANTCR service, containing the return code from IEANTCR. Can be specified as the label of a field, as a register pointing to such a field, or it can be omitted, in which case a fullword field will be appended to the parameter list. The field does not need to be initialized.
,LVL=level
If specified, the value of level is used to initialize the level field designated by the tok_level parameter.
,NAME=name
If specified, the value of name is used to initialize the name field designated by the tok_name parameter.
,TOKEN=token
If specified, the value of token is used to initialize the token field designated by the tok_val parameter.
,PERSIST=option
If specified, the value of option is used to initialize the token field designated by the tok_persist parameter.

1.9 Abend codes

X'AC7'.

See the chapter on IEANTCR in the Authorized Assembler Services Reference manual for your level of OS/390 or z/OS for details.

1.10 Return and Reason Codes

When control is returned register 15 and the field specified by the tok_retcd parameter both contain one of the following hexadecimal return codes.

Hexadecimal
Return code
Meaning and Action
00 Meaning: The operation was successful.
Action: None.
04-40 Meaning: Error.
Action: Correct the error and retry.

See the chapter on IEANTCR in the Authorized Assembler Services Reference manual for your level of OS/390 or z/OS for details.

1.11 Example

Examples are given under the list, generate and execute forms of the NTCR macro.

2 NTCR - Name/Token pair CReation - list form

The list form of the NTCR macro assigns the correct amount of storage for the NTCR parameter list and any required parameter fields.

2.1 Syntax

The list form of the NTCR macro is written as follows:


name name: Symbol. Begin name in column 1.
One or more blanks must precede NTCR.
NTCR
One or more blanks must follow NTCR.

tok_level RX-type address or register, specifying a fullword in storage that contains the token level. If not specified, a fullword will be appended to the parameter list to contain the level value.
,tok_name RX-type address or register, specifying a 16-byte area in storage that contains the token name. If not specified, a 16-byte area will be appended to the parameter list to contain the token name.
,tok_val RX-type address or register, specifying a 16-byte area in storage that contains the token value. If not specified, a 16-byte area will be appended to the parameter list to contain the token value.
,tok_persist RX-type address or register, specifying a fullword in storage that contains the persist option. If not specified, a fullword will be appended to the parameter list to contain the persist option.
,tok_retcd RX-type address or register, specifying a fullword in storage that is to contain the returncode from IEANTCR. If not specified, a fullword will be appended to the parameter list to receive the return code.
,LVL=level Default: none
level the desired token level
,NAME=name Default: none
name the desired name to be assigned to the token
,TOKEN=token Default: none
token the desired value to be assigned to the token
,PERSIST=option Default: none
option the desired persist option for the token
MF=L or
MF=(L)

2.2 Parameters

The parameters are explained under the standard form of the NTCR macro with the following exception:

MF=L or MF=(L)
Specifies the list form of NTCR

Remark:
The initialization values are optional for the list-form of the NTCR macro. Before the IEANTCR service is invoked, however, all input fields have to be properly initialized, either on the list-form of the macro, or on the execute-form of NTCR. Alternatively, the input fields that are not appended to the parameter list may be initialized in any other way.

2.3 Example

An example of the use of the list form of NTCR is:

WRK      DSECT
WRKTOKEN DS    CL16                     * Token value field
WRKRETCD DS    F                        * Returncode field
*
* Room for NTCR plist and three unnamed fields
SAMP1    NTCR  ,,0,,0,                  * Define NTCR plist+fields     
*
         MF=L
+*Generated plist and areas for NTCR: 44 bytes
SAMP1_LEN EQU  *-SAMP1                  * Define length of area
         ...
CODE     CSECT
         ...
* Prototype plist for NTCR with three unnamed fields
NTCRINIT NTCR  ,,0,,0,                  * Define plist                 
*
         LVL=IEANT_SYSTEM_LEVEL,        * and init'ed fields           
*
         NAME='BIXOFT.SAMP1',           *   for IEANTCR               
 *
         PERSIST=IEANT_NOPERSIST,                                      
*
         MF=L
+*Generated plist and areas for NTCR: 44 bytes

3 NTCR - Name/Token pair CReation - generate form

The generate form of the NTCR macro creates a remote parameter list that can be used by the execute form of NTCR.

3.1 Syntax

The egenerate form of the NTCR macro is written as follows:


name name: Symbol. Begin name in column 1.
One or more blanks must precede NTCR.
NTCR
One or more blanks must follow NTCR.

tok_level RX-type address or register, specifying a fullword in storage that contains the token level. If not specified, a fullword will be appended to the parameter list to contain the level value.
,tok_name RX-type address or register, specifying a 16-byte area in storage that contains the token name. If not specified, a 16-byte area will be appended to the parameter list to contain the token name.
,tok_val RX-type address or register, specifying a 16-byte area in storage that contains the token value. If not specified, a 16-byte area will be appended to the parameter list to contain the token value.
,tok_persist RX-type address or register, specifying a fullword in storage that contains the persist option. If not specified, a fullword will be appended to the parameter list to contain the persist option.
,tok_retcd RX-type address or register, specifying a fullword in storage that is to contain the returncode from IEANTCR. If not specified, a fullword will be appended to the parameter list to receive the return code.
,LVL=level Default: none
level the desired token level
,NAME=name Default: none
name the desired name to be assigned to the token
,TOKEN=token Default: none
token the desired value to be assigned to the token
,PERSIST=option Default: none
option the desired persist option for the token
MF=(G,list_addr) list_addr: RX-type address or register

3.2 Parameters

The parameters are explained under the standard form of the NTCR macro with the following exception:

MF=(G,list_addr)
Specifies the generate form of the NTCR macro, which uses a remote parameter list. list_addr specifies the starting address for the remote parameter list to be generated.

3.3 Example

An example of the use of the generate form of NTCR is given below. It expands on the example of the list form of NTCR given above.

CODE     RSECT ,                       * CSECT would be ok too
         ...
* Set up plist for NTCR with three unnamed fields
SAMP2    NTCR  ,,WRKTOKEN,,WRKRETCD,   * Define plist                   *
         LVL=IEANT_SYSTEM_LEVEL,       * and init fields                *
         NAME='BIXOFT.SAMP1',          *   for IEANTCR                  *
         PERSIST=IEANT_NOPERSIST,      *
         MF=(G,SAMP1)                  * Use declared area in WRK
  dsect
+*Generated plist and areas for NTCR: 44 bytes

4 NTCR - Name/Token pair CReation - execute form

The execute form of the NTCR macro uses a remote parameter list that can be generated by the list form or the generate form of NTCR.

4.1 Syntax

The execute form of the NTCR macro is written as follows:


name name: Symbol. Begin name in column 1.
One or more blanks must precede NTCR.
NTCR
One or more blanks must follow NTCR.

tok_level RX-type address or register, specifying a fullword in storage that contains the token level. If not specified, a fullword will be appended to the parameter list to contain the level value.
,tok_name RX-type address or register, specifying a 16-byte area in storage that contains the token name. If not specified, a 16-byte area will be appended to the parameter list to contain the token name.
,tok_val RX-type address or register, specifying a 16-byte area in storage that contains the token value. If not specified, a 16-byte area will be appended to the parameter list to contain the token value.
,tok_persist RX-type address or register, specifying a fullword in storage that contains the persist option. If not specified, a fullword will be appended to the parameter list to contain the persist option.
,tok_retcd RX-type address or register, specifying a fullword in storage that is to contain the returncode from IEANTCR. If not specified, a fullword will be appended to the parameter list to receive the return code.
,LVL=level Default: none
level the desired token level
,NAME=name Default: none
name the desired name to be assigned to the token
,TOKEN=token Default: none
token the desired value to be assigned to the token
,PERSIST=option Default: none
option the desired persist option for the token
MF=(E,list_addr) list_addr: RX-type address or register

4.2 Parameters

The parameters are explained under the standard form of the NTCR macro with the following exception:

MF=(E,list_addr)
Specifies the execute form of the NTCR macro, which uses a remote parameter list. list_addr specifies the address of the remote parameter list, generated by the list form or the generate form of the macro.

4.3 Example

An example of the use of the execute form of NTCR is given below. It expands on the examples of the list and generate forms of NTCR given above.

CODE     RSECT ,                       * CSECT would be ok too
         ...
* Plist for NTCR has been set up with three unnamed fields
SAMP3    NTCR  MF=(E,SAMP1)            * Create token
SAMP4    NTCR  R6,                     * Override level field
   location
 *
         NAME='BIXOFT.SAMP4',          *  and token name               
*
         MF=(E,SAMP1)                  * to create a second token

5 Miscellaneous

5.1 Wish List

5.2 Maintenance Status

Currently not in maintenance

5.3 Source Code

Source code of macro NTCR is available for reference only.
Any other use is licensed under the GPL.
For other licenses, please e-mail us.


Please e-mail us with your comments. Thanks in advance.

To our homepage.

 

This site is a member of WebRing.
You are invited to browse the list of mainframe-loving sites.
Running
    Tyrannosaurus Rex Dinos are not dead. They are alive and well and living in data centers all around you. They speak in tongues and work strange magics with computers. Beware the dino! And just in case you're waiting for the final demise of these dino's: remember that dinos ruled the world for 155-million years!
Dinos and other anachronisms
[ Join Now | Ring Hub | Random | << Prev | Next >> ]