Description
The ETCON macro connects one or more previously created entry tables to the specified linkage table indexes in the current home address space. If an entry table is connected to a system linkage index (an index reserved with the SYSTEM=YES option of the LXRES macro), the entry table is connected to the linkage table of every address space, both present and future.
- The ETDIS macro removes the connection.
- The entry table owner terminates.
- The address space to which the table is connected terminates unless the connection was to a system linkage index.
- The system is re-IPLed.
Related macros
ETDEF, ETCRE, ETDES, and ETDIS
Environment
The requirements for callers of ETCON are:
| Environmental factor | Requirement |
|---|---|
| Minimum authorization: | Supervisor state or PKM 0-7 |
| Dispatchable unit mode: | Task or SRB |
| Cross memory mode: | 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: | The parameter list passed to the ETCON macro must be addressable in primary mode at the time the macro is issued. |
Programming requirements
None.
Restrictions
- If an entry table contains entries that cause address space switches, the entry table owner must have PT and SSAR authorization to issue PT and SSAR instructions to the home address space.
- An entry table can be connected only once to a single linkage table.
- The linkage index and the entry table being connected must be owned by the same task (the cross memory resource owning task of the home address space).
Any violation of these restrictions causes the system to abnormally end the calling program.
Input register information
- 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 ETCON 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 system might use some registers as work registers or might change the contents of some registers. When the system 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 using the standard form of ETCON, do not use register 2 as your program's base register. The macro modifies register 2 and then uses a branch instruction. Register 2 is restored by the time control returns to your program.
- 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
Performance implications
None.
Syntax
The ETCON macro is written as follows:
| Syntax | Description |
|---|---|
| name | name: Symbol. Begin name in column 1. |
| ␢ | One or more blanks must precede ETCON. |
| ETCON | |
| ␢ | One or more blanks must follow ETCON. |
| TKLIST=addr | addr: RX-type address or register (0) - (12). |
| ,LXLIST=lx list addr | lx list addr: RX-type address or register (2) - (12). |
| ,ELXLIST=elx list addr | elx list addr: RX-type address or register (2) - (12). |
| ,RELATED=value | value: Any valid macro keyword specification. |
Parameters
The parameters are explained as follows:
- TKLIST=addr
- Specifies the address of a list of fullword tokens representing the entry tables to be connected to the linkage table. The first entry in the list must be the number of tokens that follow (from 1 to 32). The tokens are the values returned in register 0 when the ETCRE macro is issued.
- ,LXLIST=addr
- ,ELXLIST=addr
- lx list addr specifies the address of
a list of linkage index (LX) values to which the specified entry tables
are to be connected. The list contains fullword entries, the first
of which must be the number of linkage index values that follow (from
1 to 32). The number of linkage index values must be the same as the
number of tokens. The first entry table is connected to the first
linkage index; the second entry table is connected to the second linkage
index, and so on.
elx list addr specifies the address of an area that contains extended linkage index (LX) values to which the specified entry tables are to be connected. The first word in the area must be the number of extended LX values that follow (from 1 to 32). Each subsequent eight bytes contains an extended LX value which consists of a 4-byte sequence number followed by an LX value. The number of extended linkage index values must be the same as the number of tokens. The first entry table is connected to the first linkage index; the second entry table is connected to the second linkage index, and so on. If the sequence number in the entry is incorrect, the system issues abend X'052' with reason code X'051B'.
- ,RELATED=value
- Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user and can be any valid coding values.
ABEND codes
053
See z/OS MVS System Codes for an explanation and programmer responses for these codes.
Return codes
When ETCON macro returns control to your program, GPR 15 contains a return code.
| Hexadecimal Return Code | Meaning |
|---|---|
| 00 | Meaning: The specified connections were
successfully made. Action: None required. |
Examples
For examples of the use of this and other cross memory macros, refer to the chapter on cross memory communication in z/OS MVS Programming: Extended Addressability Guide.