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 NTCR - Name/Token pair creation
  • 1.0 Description
  • 1.1 Environment
  • 1.2 Programming Requirements
  • 1.3 Restrictions
  • 1.4 Input Register Information
  • 1.5 Output Register Information
  • 1.6 Performance Implications
  • 1.7 Syntax
  • 1.8 Parameters
  • 1.9 Abend Codes
  • 1.10 Return and Reason Codes
  • 1.11 Examples
• 2 NTCR - list form
  • 2.1 Syntax
  • 2.2 Parameters
  • 2.3 Example
• 3 NTCR - generate form
  • 3.1 Syntax
  • 3.2 Parameters
  • 3.3 Example
• 4 NTCR - execute form
  • 4.1 Syntax
  • 4.2 Parameters
  • 4.3 Example
• 5 Miscellaneous
  • 5.1 Wish List
  • 5.2 Maintenance status
  • 5.3 Source Code

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

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:

When control returns to the caller, the access registers (ARs) contain:

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:

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.

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:

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:

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:

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

• Add type-checking for operands
• Check effects of 64-bit addressing

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

© Copyright B.V. Bixoft 1997-2007. All rights reserved.
Bixoft ® is a trademark of B.V. Bixoft
e-mail Bixoft.