General
Application area: | Linking and loading; see "Linking and loading" |
Macro type: | Type S, MF format 2: standard/C/D/L/E/M form; see "S-type macros" |
See also the “BLSSERV” manual [4 (Related publications)] for information on the dynamic binder loader DBL.
Macro description
With the ETABLE macro, the user program transfers a symbol table to the DBL; the table is integrated into the symbol table of the specified context. The transferred table notifies the DBL of the names and attributes of CSECTs, ENTRYs, and COMMON areas of the user program.
This macro is not compatible with the previous TABLE macro.
Macro format and description of operands
ETABLE |
MF=S / D / C / E / L / M ,ACTION=*CREATE / *UPDATE / *DELETE ,CONTEXT_NAME= ,CONTEXT_STATE=*DBL-OPTIONS / *ANY / *NEW / *OLD ,TABLE_ADDRESS=NULL-1 / <var: pointer> ,TABLE_LENGTH=0 / <integer 0..2147483647> ,PARAM=<var: pointer> / (reg: pointer>) ,PREFIX=P / p ,MACID=BEI / macid |
The operands are described in alphabetical order below.
ACTION=
Action which is to be executed for the individual symbols in the transferred table.
*CREATE
The symbols are entered into the symbol table of the context. They must not already be present in it.
*UPDATE
The symbols are entered with their new attributes into the symbol table of the context. They must already be present in it. The visibility of symbols which were not entered with an earlier call of the ETABLE macro is also changed here.
*DELETE
The symbols are to be deleted from the symbol table of the context.
CONTEXT_NAME=' ' / <char 1..32>
Name of the context to which the symbols are assigned. The first character must be a letter.
CONTEXT_STATE=
Status of the context specified with CONTEXT_NAME
*DBL-OPTIONS
The operand value is taken from the last call of the MODIFY-DBL-DEFAULTS command. If a value for the operand has not yet been set using the MODIFY-DBL-DEFAULTS command, the value that follows *DBL-OPTIONS in the syntax definition applies.
*ANY
If the context already exists it is used, otherwise a new context is created.
*NEW
The context is created. It must not already exist.
*OLD
The context already exists.
MF=
For a general description of the MF operand, its operand values and any of the specified operands PARAM, PREFIX and MACID, see section “S-type macros”. The valid MF values are given at the start of the macro description under “Macro type” and are included in the macro format.
It is possible to specify a PREFIX in the C form, D form, or M form of the macro, and additionally a MACID in the C form or M form (see section “S-type macros”).
TABLE_ADDRESS=NULL-1 / <var: pointer>
Address of a table of symbols to be transferred to DBL.
TABLE_LENGTH=0 / <integer 0..2147483647>
Actual length of the table (in bytes)
Notes on the macro call
The type and name of a symbol cannot be changed with ETABLE.
The address in the LOAD_ADDR field must be a valid class 6 memory address.
A symbol that was entered in the symbol table of the context with ETABLE cannot be deleted from the symbol table using the UNBIND macro. However, symbols that were introduced with the LOAD-/START-EXECUTABLE-PROGRAM (or LOAD-/START-PROGRAM) command or with the BIND and TABLE macros cannot be deleted with ETABLE ACTION=*DELETE.
If ACTION=*DELETE is set, the CONTEXT_STATE operand is ignored. Only the symbol names are taken into account.
The user is responsible for symbols entered in the symbol table with ETABLE; these symbols are not visible for the current task.
If a COMMON area is introduced with ETABLE, DBL assumes that the COMMON area is already loaded and refers the LOAD_ADDR field to an allocated memory area.
If ACTION=UPDATE is applied to a symbol which was not generated by ETABLE, only the symbol name, symbol type and the INVISIBLE attribute are taken into account during processing.
Only the visibility can be updated for a symbol which was not generated by ETABLE.
As the visibility can also be updated for symbols which were not generated by ETABLE, the visibility of the first symbol found is always updated.
Symbol table format
The address specified with TABLE_ADDRESS points to a symbol table, which may contain a number of entries. An individual entry has the following format:
Byte | Length | Field name | Meaning and/or value |
0 | 8 | HDR | Standard header |
8 | 1 | TYPE | / CSECT (X'F0') or |
9 | 7 | ATTRIBUTE | Same attributes as for CSECTs (1 byte per attribut with the
|
16 | 4 | LOAD_ADDR | Load address of the symbol |
20 | 2 | LEN | Length of the CSECT / of the COMMON area |
22 | 32 | SYMBOL_NAME | Name of the symbol |
54 | 1 | HSI_CODE | 390 (X'01') or |
55 | 1 | MMODE | TU_4K_DEPENDENT (X'02') or |
The DSECT for such a symbol entry is generated with ETABIT MF=D.
Handling of name conflicts
The following table shows how name conflicts between symbols introduced by the ETABLE, TABLE and BIND macros are handled:
Existing symbol was introduced by | |||
ACTION | ETABLE | TABLE | BIND |
*CREATE | (1) | (2) | (2) |
*UPDATE | (3) | (4) | (4) |
*DELETE | (5) | (6) | (6) |
(1) | An existing ETABLE symbol has the same name.The following return code is transferred: ETABLE_SYMB_DUPLICATE |
(2) | A name conflict occurs. The following return code is transferred: ETABLE_NAME_COLLISION |
(3) | The symbol is changed (no name conflict). |
(4) | Only the visibility of the symbol is updated. |
(5) | The symbol is deleted (no name conflict). |
(6) | Invalid action. |
Return information and error flags
If an error occurs during processing of the table entries, a corresponding return code is entered in the HDR field of the table entry containing the error. The return code FUNCTION_PARTIALLY_PROCESSED is entered in the standard header of the parameter list and processing of the table entries is continued.
The PROCESSED_ITEMS field of the parameter list contains the number of correctly processed entries.
Standard header:
+---------------+ | | | | | |c|c|b|b|a|a|a|a| +---------------+
A return code relating to the execution of the ETABLE macro is transferred in the standard header (cc=Subcode2, bb=Subcode1, aaaa=Maincode):
X'cc' | X'bb' | X'aaaa' | Meaning |
X'00' | X'00' | X'0000' | The macro was executed normally. |
X'01' | X'00' | X'0000' | The function was already executed. |
X'02' | X'00' | X'0001' | The function was partially executed. |
X'60' | X'01' | X'0001' | Invalid TABLE_LENGTH operand. |
X'60' | X'01' | X'0002' | Invalid specification for TABLE_ADDRESS or TABLE_LENGTH. |
X'60' | X'01' | X'0008' | Invalid ACTION operand |
X'60' | X'01' | X'000A' | Internal ETABLE error. |
X'60' | X'01' | X'0019' | A reserved field does not contain any binary zeros. |
X'60' | X'01' | X'0040' | The context is not yet present and CONTEXT_STATE=*OLD was |
X'60' | X'01' | X'0048' | The context is already present and CONTEXT_STATE=*NEW was |
X'60' | X'01' | X'0134' | Invalid CONTEXT_STATE parameter |
X'60' | X'01' | X'0148' | Invalid context name |
X'60' | X'40' | X'0158' | Maximum number of user contexts has been reached. |
X'60' | X'20' | X'0200' | Internal DBL error |
X'60' | X'20' | X'0300' | System error |
X'00' | X'01' | X'FFFF' | The function is no longer or not yet supported. |
X'00' | X'03' | X'FFFF' | The interface version is not supported. |
Other return codes which, in accordance with conventions, apply to all macros are given in the table “Standard return codes” (Standard header).
Example
This example is designed to illustrate the application of the ETABLE/ETABIT interfaces:
* DSECT of ETABLE item
*
ETABIT MF=D
...
* Initialization of the ETABLE parameter list
*
MVC ETAPL(PBEI#),ETAPLI
LA 1,ETATAB
LA 2,ETATABL
ETABLE MF=M,TABLE_ADDRESS=(1),TABLE_LENGTH=(2)
*
* Initialization of the entries
*
USING PBETDS,1 reg 1 = Address of the first entry
* PBETDS = DSECT for the entry
*
* First entry
*
MVC 0(PBET#,1),ETAITEMI Initializing entry
ETABIT MF=M,SYMBOL_NAME=CS1NAM,LEN=CS1L,
LOAD_ADDR=CS1@,SYMBOL_TYPE=*COMMON
*
* Second entry
*
LA 1,PBET#(1) reg 1 = Address of the second entry
L 2,CS2@
MVC 0(PBET#,1),ETAITEMI Initializing entry
ETABIT MF=M,SYMBOL_NAME='CS2',LEN=200,
LOAD_ADDR=(2),SYMBOL_TYPE=*CSECT
*
* Call ETABLE
*
ETABLE MF=E,PARAM=ETAPL
*
* Return code evaluation
*
...
*
* ETABLE table
*
ETATAB DS XL(2*PBET#) Table for two entries
ETATABL EQU *-ETATAB Table length
DS 0F
CS1@ DS F Address of the first symbol entered
CS1NAM DS CL32 Name of the first symbol entered
CS1L DS Y Length of the first symbol entered
CS2@ DS F Address of the second symbol entered
*
ETAPL ETABLE MF=C Parameter list
*
* Structure for initializing the ETABLE parameter list
*
ETAPLI ETABLE MF=L,ACTION=*CREATE,CONTEXT_STATE=*NEW,
CONTEXT_NAME='ETACTX'
*
* Structure for initializing an ETABLE entry
*
ETAITEMI ETABIT MF=L