ETCRE — Create entry table

Description

The ETCRE macro builds a program-call entry table based upon descriptions of each entry. A token representing the created entry table is returned to the requestor. You must use this token in all subsequent references to the entry table.

Related macros

ETDEF, ETDES, ETCON, and ETDIS

Environment

These are the requirements for the caller:

Environmental factor	Requirement
Minimum authorization:	Supervisor state or PKM 0-7
Dispatchable unit mode:	Task or SRB
Cross memory mode:	PASN=HASN=SASN or PASN¬=HASN¬=SASN
AMODE:	24- or 31-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	Must be in primary address space

Programming requirements

Before issuing ETCRE, the caller must create the ETD parameter list that ETCRE uses as input. The parameter list defines the names and characteristics of the program call (PC) routines that the entry table will define. To create the parameter list, the caller can issue the ETDEF macro or can code the data constants needed to define the list. If data constants are coded, the caller can use mapping macro IHAETD to map them.

The created entry table is owned by the cross memory resource ownership task in the current home address space. When the cross memory resource ownership task terminates, entry tables are disconnected and freed.

Note: Programs written before SP/Version 3, which use data constants to define the parameter list (the resulting ETD was called a format 0 ETD) and which use IHAETD to map the data area, will still work. For information about the format 0 ETD, see z/OS MVS Data Areas in the z/OS Internet library.

Restrictions

None.

Input register information

The ETCRE macro is sensitive to the SYSSTATE macro with the OSREL=ZOSV1R6 parameter

If the caller has issued the SYSSTATE macro with the OSREL=ZOSV1R6 parameter (Version 1 Release 6 of z/OS® or later) before issuing the ETCRE macro, the caller does not have to place any information into any general purpose register (GPR) unless using it in register notation for a particular parameter, or using it as a base register.
Otherwise, the caller must ensure that the following general purpose register contains the specified information:
Register

Contents

13

The address of an 18-word save area

Output register information

After the caller issues the macro, the macro might use some registers as work registers or might change the contents of some registers. When the macro returns control to the caller, the contents of these registers are not the same as they were before the macro was issued. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.

When control returns to the caller, the general purpose registers (GPRs) contain:

Register: Contents
0: The 32-bit token associated with the new entry table
1: Used as a work register by the macro
2-13: Unchanged
14: Used as a work register by the macro
15: Return code

Performance implications

None.

Syntax

The ETCRE macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede ETCRE.

ETCRE

␢	One or more blanks must follow ETCRE.

ENTRIES=`addr`	`addr`: RX-type address or register (0) - (12).

,RELATED=`value`	`value`: Any valid macro keyword specification.

Parameters

The parameters are explained as follows:

ENTRIES=addr: Specifies the address of the parameter list that defines the PC routines.
An entry index value that does not have a description results in an invalid entry in the entry table. If the program name field in an ETD entry contains zeros, an invalid entry is created for that entry index. A program call to an invalid entry causes the caller to be abnormally terminated. The ETCRE caller is abnormally terminated if any of the reserved fields are nonzero or if the system cannot locate the specified program name.
,RELATED=value: Specifies information used to self-document macros by relating functions or services to corresponding services performed elsewhere. The format and contents of the information specified can be any valid coding values.

ABEND codes

052
053

See z/OS MVS System Codes for an explanation and programmer responses for this code.

Return codes

When ETCRE macro returns control to your program, GPR 15 contains a return code.

Table 1. Return Code for the ETCRE Macro
Hexadecimal Return Code	Meaning
00	Meaning: The entry table is successfully created. Action: None required.

Example

Show the relationship between the ETCRE and the ETDEF macros. ETDEF builds an entry table descriptor (ETD) that contains two ETD entries. The first entry, associated with PROGRAM1, is for a PC routine that runs in supervisor state. The second entry, associated with PROGRAM2, is for a PC routine that runs in problem state.

*
* CREATE THE ENTRY TABLE
*
         .
         .
         LA    2,ETSTART
         ETCRE ENTRIES=(2)
         .
         .
*
* DEFINE START OF ETD
*
ETSTART  ETDEF TYPE=INITIAL              START ETD
*
* DEFINE ENTRIES
*
ETEX2    ETDEF TYPE=ENTRY,PROGRAM='PROGRAM1',AKM=(0:15)
         ETDEF TYPE=ENTRY,PROGRAM='PROGRAM2',AKM=(0:7)
*
* DEFINE END OF ETD
*
        ETDEF TYPE=FINAL