General
Application area: | Linking and loading; see "Linking and loading" |
Macro type: | Type S, MF format 2: standard/C/D/E/L/M form; see "S-type macros" |
See also the “BLSSERV” manual [4 (Related publications)] for information on the dynamic binder loader DBL.
Macro description
The ILEMGT macro enables the user to manage a list of ILEs (Indirect Linkage Entries). The ILEs in the list may be generated, updated or deleted.
Information on ILEs can be requested with the VSVI1 macro.
Macro format and description of operands
ILEMGT |
MF=S / D / C / E / L / M ,ACTION=*CREATE / *UPDATE / *DELETE ,CONTEXT_NAME= ,CONTEXT_STATE=*DBL-OPTIONS / *ANY / *NEW / *OLD ,ILE_LIST_ADDR=NULL-1 / <var: pointer> ,ILE_LIST_LEN=0 / <integer 0..2147483647> ,MPID_ADDR=NULL-1 / <var: pointer> ,PARAM=<var: pointer> / (reg: pointer>) ,PREFIX=P / p ,MACID=ILE / macid |
The operands are described in alphabetical order below.
ACTION=
Action to be executed for the ILEs in the list.
*CREATE
The ILEs are to be created.
*UPDATE
The ILEs are to be updated.
*DELETE
The ILEs are to be deleted.
CONTEXT_NAME=
' ' / <c-string 1..32> / <var: char 1..32>
Name of the context to which the ILEs belong.
CONTEXT_STATE=
State of the context specified in CONTEXT_NAME
*DBL-OPTIONS
The parameter value is taken from the last call of the MODIFY-DBL-DEFAULTS command. If a value for the parameter 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 being created. It must not already exist.
*OLD
The context must already exist.
ILE_LIST_ADDR=NULL-1 / <var: pointer>
Address of a list of ILEs that is to be transferred to DBL.
ILE_LIST_LEN=0 / <integer 0..2147483647>
Length of the ILE list (in bytes)
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”).
MPID_ADDR=NULL-1 / <var: pointer>
Address of a field with the identifier of the memory pool containing the specified context. This identifier is made available to the user by means of the ENAMP macro.
ILE list format
The addresses specified in ILE_LIST_ADDR point to an ILE list which may contain a number of entries. An individual ILE entry has the following format:
Byte | Length | Field name | Meaning and/or value |
0 | 8 | HDR | Standard header |
8 | 1 | STATE | ACTIVE (X'01') or |
9 | 1 | CONTROL | SYSTEM (X'01') or |
10 | 1 | HSI_CODE | 390 (X'01') or |
11 | 1 | RESERVED1 | reserved (must contain X'00') |
12 | 4 | LOAD_ADDR | Address of the IL routine |
16 | 4 | SERVER_ADDR | Address of the ILE server |
20 | 2 | REF_DISPL | Distance of the external reference to the server within the IL |
22 | 32 | NAME | Name of the ILE symbol |
54 | 2 | RESERVED2 | reserved (must contain X'0000') |
The DSECT for such an ILE list entry is generated with ILEMIT MF=D.
Notes on the macro call
If an address was specified with MPID_ADDR, the first character of the context name (mandatory parameter) determines whether or not the context is shared. If the Context name begins with „#“, DBL searches for the context in common memory pools and generates the context if necessary (ASHARE macro). In this case the MPID must identify a memory pool which is either already used with ASHARE, or which is blank (i.e. in which no memory is yet occupied).
If the context name does not begin with '#', DBL searches in the normal user contexts. A context whose name begins with a letter may not be shared. DBL recognizes this as a conflict between the memory pool usage type and the name convention, and the macro is rejected with the corresponding return code.
The number of memory pools in which the user can store shared code is limited to 16 per scope for each user ID, see "ASHARE - Load user's shared code into common memory pools".
If ACTION = *CREATE / *UPDATE is specified the STATE field of an ILE entry contains ACTIVE, and both LOAD_ADDR and SERVER_ADDR must refer to allocated memory areas.
If the CONTROL field contains SYSTEM, DBL executes the following actions:
When the ILE server is loaded
the STATE field is set to ACTIVE and the address of the ILE server is entered into the IL routine.When the ILE server is unloaded
the STATE field is set to NOT_ACTIVE and X'FFFFFFFF' is entered into the IL routine as the address of the ILE server.The CONTROL=SYSTEM field setting may not be used in combination with the ACTION=*UPDATE macro parameter.
If ACTION=*CREATE is specified the LOAD_ADDR field must refer to an allocated memory area containing the user-defined IL routine (CONTROL=USER). If this does not apply (CONTROL=SYSTEM) then the DBL generates a standard IL routine in the context. The standard IL routine is generated in the HSI code that was specified when the ILEMIT macro was called, or else in the HSI code of the server on which the program is running.
If a user-defined IL routine is present, the REF_DISPL field must contain the distance of the word in the IL routine that refers to the ILE server. This word must be writable.Specification of the HSI code is mandatory for user-defined routines.If ACTION=*DELETE is specified, the IL routine will also be deleted from the context provided the ILE to be deleted was generated with CONTROL=*BY-SYSTEM. The IL routine must have been generated by the DBL.
All non-masked CSECTs and ENTRYs in the target context may be used as ILE servers, even those introduced by means of the ETABLE macro. To avoid any problems which this might cause for ILE management, one context should be set up for ILEs and their servers, and a different context set up for ETABLE symbols.
If LLMs formed from PUBLIC and PRIVATE slices are to be used for indirect linking, these LLMs must be available in format 1 (see the “BINDER” manual [5 (Related publications)]).
The IL routines should have the attributes AMODE and RMODE=ANY and be loaded below 16 Mb, to ensure that they can be accessed by all programs.
When an ILE is updated a check is performed when its server is loaded to see whether the HSI code and AMODE of ILE and server match. If not, loading of the server is rejected.
Return information and error flags
If an error occurs during processing of the list entries, a corresponding return code is entered in the HDR field of the list entry containing the error. The return code FUNCTION_PARTIALLY_PROCESSED is transferred in the standard header of the parameter list and processing of the list 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| +---------------+
The following return code relating to the execution of the ILEMGT 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'02' | X'00' | X'0001' | The function was partially executed. |
X'61' | X'01' | X'0001' | Invalid value in ILE_LIST_LEN. |
X'61' | X'01' | X'0002' | Invalid parameter combination in the parameter list. |
X'61' | X'01' | X'0003' | The MESSAGE parameter is invalid. |
X'61' | X'01' | X'0004' | The context name is invalid. |
X'61' | X'01' | X'0008' | The ACTION parameter is invalid. |
X'61' | X'40' | X'0011' | The task is not connected to the memory pool. |
X'61' | X'01' | X'0014' | The new USER context already exists in another memory pool. |
X'61' | X'40' | X'0015' | Maximum number of contexts in the memory pool has already been |
X'61' | X'40' | X'0016' | The maximum number of memory pools with this scope has already |
X'61' | X'40' | X'0017' | System storage area for user contexts is full. |
X'61' | X'01' | X'0018' | A reserved field does not contain any binary zeros. |
X'61' | X'01' | X'0019' | The current memory pool is not shared. |
X'61' | X'20' | X'0100' | System error (e.g.: $REQM, $RELM, $CSTAT, RDTFT) |
X'61' | X'20' | X'0101' | Internal DBL error. |
X'61' | x'80' | X'0103' | Shared resources are not available. |
X'61' | X'01' | X'0114' | CONTEXT_STATE=*OLD was specified and the context does not exist. |
X'61' | X'01' | X'0118' | CONTEXT_STATE=*NEW was specified and the specified context |
X'61' | X'40' | X'0120' | MPID_ADDR is not aligned on a word boundary. |
X'61' | X'01' | X'0134' | The CONTEXT_STATE parameter is invalid. |
X'61' | X'40' | X'0148' | An attempt was made to use a context which has been corrupted by a |
X'61' | X'40' | X'0158' | Maximum number of 16 user contexts has been reached. No more new |
X'61' | X'01' | X'0184' | The specified memory pool is invalid. |
X'61' | X'20' | X'0198' | Insufficient memory availabe for the action requested. |
X'61' | X'20' | X'0204' | Inconsistencies in the DBL memory management tables (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).