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
The UNBIND macro is used during the program run to release memory occupied by objects that are no longer needed. The object can be a context, a load unit, an LLM or an object module (OM). The symbols in the unloaded objects are then no longer available. The occupied memory space is released pagewise only (in units of 4Kb). The space is returned to memory management only if it is not required by any other modules on the same page. Otherwise DBL notes the free areas and uses them at the next opportunity.
Control sections (CSECTs) and entry points (ENTRYs) in the object can optionally be unlinked, i.e. external references to these symbols are treated as unresolved external references by DBL. An object can be loaded only within a context and then only if LDINFO=REF (BIND macro) or LOAD-INFORMATION=*REFERENCES (LOAD-PROGRAM command) was specified when the object was loaded.
Macro format and description of operands
UNBIND |
[ {CONTEXT=name / CONTXT@={addr / (r)} ] [,{UNIT=name / UNIT@={addr / (r)}}] [,{MODULE=name / MODULE@={addr / (r)}}] [,{PGMVERS={*STD / version} / PGMVER@={addr / (r)}}] ,UNLINK=NO / YES ,MSG=*DBLOPT / INFORMATION / WARNING / ERROR / NONE ,MF=S / C / D / E / L / M [,PARAM=addr / (r)] ,PREFIX=P / p [,LABEL=name] |
CONTEXT=name
Specifies the name of the context to be unloaded or in which objects are to be unloaded. Objects can be:
a load unit specified by UNIT or
a module specified by MODULE.
“name” can be up to 32 characters long and must not begin with “$” or “#”.
If the operand is not used the name “LOCAL#DEFAULT” is assumed by default.
CONTXT@=
May be specified only if MF=M.
Specifies the address of a field which contains the name of the context to be unloaded.
addr
Address of an field which contains the name.
(r)
Register containing the address value “addr”.
UNIT=name
Specifies the name of the load unit to be unloaded or in which a module specified by MODULE is to be unloaded. “name” is the name of the load unit which was specified in the BIND macro at the time of loading. This can be:
the name defined with the UNIT@ or UNIT operand or
the name defined with the SYMBOL@ or SYMBOL operand if UNIT@ or UNIT was not specified.
“name” can be up to 32 characters long.
UNIT@=
May be specified only if MF=M.
Specifies the address of a field which contains the name of the load unit to be unloaded.
addr
Address of a field which contains the name.
(r)
Register containing the address value “addr”.
MODULE=name
Specifies the name of the module to be unloaded. The module can be an LLM or an OM. If an LLM, its internal name must be specified. “name” can be up to 32 characters long.
MODULE@=
May be specified only if MF=M.
Specifies the address of a field containing the name of the module which is to be unloaded.
addr
Address of a field which contains the name.
(r)
Register containing the address value “addr”.
UNLINK=
Specifies whether or not control sections (CSECTs) and entry points (ENTRYs) are to be unlinked in the unloaded object. External references to unlinked symbols are then treated as unresolved external references by DBL. Unlinking is only possible if the LDINFO=REF operand was specified in the BIND macro at the time of loading.
Symbols in a context which refer to another context cannot be unlinked. Unlinking is only possible within the same context.
NO
Default setting: symbols will not be unlinked.
YES
Symbols will be unlinked.
PGMVERS=
Specifies the program version to be unloaded.
*STD
Default setting: signifies that no version specification is to be taken into account during unloading.
version
The version specification may be up to 24 characters long.
If the DBL does not find this program version, the program specified is not unloaded.
PGMVER@=
May be specified only if MF=M.
Specifies the address of a field containing the program version.
addr
Address of a field which contains the name.
(r)
Register containing the address value “addr”.
MSG=
Specifies the lowest message class; messages at and above this level will be output.
*DBLOPT
Default setting: the parameter value is taken from the last call of the MODIFY-DBL-PARAMETERS command. If a value for the parameter has not yet been set using the MODIFY-DBL-PARAMETERS command, MSG=INFORMATION applies.
INFORMATION
All classes of message will be output.
WARNING
Only messages of the WARNING and ERROR classes will be output. Messages of the INFORMATION message class will not be output.
ERROR
Only messages of the ERROR class will be output.
NONE
No messages will be output.
MF=
For a general description of the MF operand, its operand values and any of the specified operands PARAM and PREFIX, 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.
A PREFIX can be specified in the C form, D form or M form of the macro
(see section “S-type macros”).
LABEL=name
May be specified only if MF=M
Name of the structure, i.e. the DSECT which describes the operand list of the UNBIND macro. The operand is mandatory if there is no valid USING statement for the definition of the base address register for the DSECT of the parameter list. The LABEL operand must be specified in conjunction with the PARAM operand. Both operands are used to produce a valid USING statement.
The following may be specified for “name”:
The name specified in the name field of a preceding macro
name UNBIND MF=DThe name “xPBUNDS” if no “name” has already been specified, where “x” is the value of the PREFIX operand of a preceding macro
PBUNBIND MF=D, PREFIX=xThe default value for “x” is “P”.The name of the longer DSECT containing the parameter list of the UNBIND macro if the macro
UNBIND MF=Cwas specified earlier.
Notes on the macro call
The CONTEXT, UNIT and MODULE operands can be specified together in the same macro in order to expedite the search by DBL or to resolve name conflicts in cases where load units or modules have the same name. By default, DBL always chooses the first name it finds.
The delayed resolution of external references (DELAY) and the unlinking (UNLINK) are restricted to one context. References which have been resolved by symbols in more than one context cannot be unlinked.
UNBIND can be used to unload only objects which were loaded with the BIND macro or with the LOAD- or START-EXECUTABLE-PROGRAM (or LOAD- and START-PROGRAM) command. Shared code which was loaded into a common memory pool with the ASHARE macro cannot be unloaded with UNBIND; the DSHARE macro must be used for this.
A module belonging to a list name unit cannot be unloaded independently of the list name unit.
Return information and error flags
Standard header:
+---------------+ | | | | | |c|c|b|b|a|a|a|a| +---------------+
A return code relating to the execution of the UNBIND 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'0C' | X'01' | X'0018' | A reserved field in the parameter list is not preset with zeros. |
X'0C' | X'01' | X'0100' | Illegal parameter combination in the parameter list. Blanks must be |
X'0C' | X'01' | X'015C' | The specified context is not present. |
X'0C' | X'01' | X'0170' | The specified load unit is not present. |
X'0C' | X'01' | X'0174' | The specified module is not present. |
X'0C' | X'01' | X'0178' | A module belonging to a list name unit cannot be unloaded |
X'0C' | X'01' | X'0198' | Illegal context name. The first character is not a letter. |
X'0C' | X'01' | X'0204' | Inconsistencies in the DBL memory management tables (system error). |
X'0C' | X'01' | X'0208' | Inconsistencies in the DBL tables (system error) |
X'0C' | X'01' | X'0300' | Error during RETMEM processing (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
During the UNBIND1 program run, a BIND macro is issued to load a second control section, BIND3, as an overlay. BIND3 is stored as an object module in library MACEXMP.LIB. Both control sections are to execute in 31-bit addressing mode. UNBIND1 is to be loaded below, and BIND3 above, the 16-MB boundary. After the BIND macro is called BIND3 is to execute first. Following the execution of BIND3 a return branch is to be made to UNBIND1 and module BIND3 is to be unloaded by means of the UNBIND macro.
UNBIND1 START
UNBIND1 AMODE 31 ————————————————————————————————————————————————————— (1)
UNBIND1 RMODE 24
BALR 3,0
USING *,3
USING BINDDS,6 ——————————————————————————————————————————————— (2)
USING UNBDS,7 ———————————————————————————————————————————————— (3)
ST 3,AREA11
UNPK AREAH,AREA1
MVC AREAA(8),AREAH
WROUT1 WROUT OUT,ERROR,PARMOD=31 ———————————————————————————————————— (4)
BACK LA 12,UNBIND
BIND BIND MF=E,PARAM=BINDPAR ————————————————————————————————————— (5)
LA 6,BINDPAR
CLC XBINRET,=X'00000000' ——————————————————————————————————— (6)
BE UNBIND
MVC OUT+5(28),='BIND ERROR! '
WROUT OUT,ERROR,PARMOD=31 ———————————————————————————————————— (7)
B ERROR
UNBIND UNBIND MF=E,PARAM=UNBPAR ————————————————————————————————————— (8)
LA 7,UNBPAR
CLC YUNBRET,=X'00000000' ——————————————————————————————————— (9)
BE MVC
MVC OUT+5(28),='UNBIND ERROR! '
WROUT OUT,ERROR,PARMOD=31 ———————————————————————————————————— (10)
B ERROR
MVC MVC OUT+5(28),='UNBIND PROCESSED '
WROUT OUT,ERROR,PARMOD=31 ———————————————————————————————————— (11)
MVC OUT+5(28),='RETURN TO UNBIND1 '
WROUT OUT,ERROR,PARMOD=31
ERROR TERM
*****************
OUT DC Y(OUTE-OUT)
DS CL3
DC C'UNBIND1: BASE REG.= '
AREAA DS CL8
OUTE EQU *
AREA DS 0F
AREA1 DS 0CL5
AREA11 DS CL4
AREA12 DC C'0'
DS 0F
AREAH DS CL9
BINDPAR BIND MF=L,SYMBOL=BIND3,SYMBLAD=BIND3@,BRANCH=YES,PROGMOD=ANY,* --(5)
LIBLINK=PLAMLIB
UNBPAR UNBIND MF=L,MODULE=BIND3 –––––––––––––––––––––––––––––––––––––– (8)
BIND3@ DS A
BINDDS BIND MF=D,PREFIX=X —————————————————————————————————————————— (12)
UNBDS UNBIND MF=D,PREFIX=Y ————————————————————————————————————————— (13)
END
BIND3 CSECT ———————————————————————————————————————————————————————— (14)
PRINT NOGEN
BIND3 AMODE ANY ———————————————————————————————————————————————————— (15)
BIND3 RMODE ANY
BALR 4,0
USING *,4
ST 4,AREA11
UNPK AREAH,AREA1
MVC AREAA(8),AREAH
WROUT OUT,ERROR,PARMOD=31 ———————————————————————————————————— (16)
BR 12
ERROR TERM
*****************
OUT DC Y(OUTE-OUT)
DS CL3
DC C'BIND3: BASE REG.= '
AREAA DS CL8
OUTE EQU *
AREA DS 0F
AREA1 DS 0CL5
AREA11 DS CL4
AREA12 DC C'0'
AREAH DS CL9
END
(1) | The attribute AMODE=31 is defined for control section UNBIND1. The attribute RMODE=24 means that UNBIND1 will always be loaded below the 16-MB boundary. |
(2) | Register 6 is assigned to the assembler as the base address register for addressing the DSECT for the operand list of the BIND macro, which is generated at the symbolic address BINDDS as a result of a BIND macro specifying MF=D. |
(3) | Register 7 is assigned to the assembler as the base address register for addressing the DSECT for the operand list of the UNBIND macro, which is generated at the symbolic address UNBDS as a result of an UNBIND macro specifying MF=D. |
(4) | The contents of the base register for UNBIND1 are output to indicate the addressing mode and the load address. |
(5) | The BIND macro is called in its E form at the symbolic address BIND. At this point in the program, therefore, only the instruction code is generated. The associated operand list is created at the symbolic address BINDPAR by means of a BIND macro specifying MF=L. As a result of the operand values specified in the list, the BIND macro causes the following to happen at program runtime:
|
(6) | Following execution of the BIND macro, a check is made to verify that the XBINRET field of the standard header contains the return code X’00000000’, which indicates error-free execution of the macro. The name XBINRET originates from the DSECT that was generated under the symbolic address BINDDS as a result of a BIND macro specifying MF=D and PREFIX=X (see point 12 below). This DSECT describes the layout of the operand list of the BIND macro. The symbolic names of the DSECT can be used for addressing within the operand list once the assigned base address register (in this case, register 6) has been loaded with the start address of the operand list (in this case, BINDPAR). |
(7) | If the BIND macro does not execute without error, an error message is written to SYSOUT and the UNBIND1 program run is terminated. |
(8) | The UNBIND macro is called in its E form at the symbolic address UNBIND. At this point in the program, therefore, only the instruction code is generated. The associated operand list is created at the symbolic address UNBPAR by means of an UNBIND macro specifying MF=L. As a result of the operand MODULE=BIND3 specified in the list, the UNBIND macro causes the BIND3 module to be unloaded. |
(9) | Following execution of the UNBIND macro, a check is made to verify that the YUNBRET field of the standard header contains the return code X’00000000’, which indicates error-free execution of the macro. The name YUNBRET originates from the DSECT that was generated under the symbolic address UNBDS as a result of an UNBIND macro specifying MF=D and PREFIX=Y (see point 13 below). This DSECT describes the layout of the operand list of the UNBIND macro. The symbolic names of the DSECT can be used for addressing within the operand list once the assigned base address register (in this case, register 7) has been loaded with the start address of the operand list (in this case, UNBPAR). |
(10) | If the UNBIND macro does not execute without error, an error message is written to SYSOUT and the UNBIND1 program run is terminated. |
(11) | Messages written to SYSOUT indicate that program execution has continued in UNBIND1 and module BIND3 has been unloaded. |
(12) | The BIND macro specifying MF=D generates a DSECT which describes the layout of the operand list of the BIND macro. The operand PREFIX=X causes the letter X to be prefixed to all symbolic names in this DSECT (field names and equates). |
(13) | The UNBIND macro specifying MF=D generates a DSECT which describes the layout of the operand list of the UNBIND macro. The operand PREFIX=Y causes the letter Y to be prefixed to all symbolic names in this DSECT (field names and equates). |
(14) | The CSECT statement defines the control section BIND3. |
(15) | AMODE=ANY indicates to the operating system that BIND3 can execute in 24-bit or 31-bit addressing mode. |
(16) | The contents of the base register for BIND3 are output to indicate the addressing mode and the load address. |
Runtime listing
|
|
(17) | The file link name used in the BIND call (5) is assigned. |
(18) | DBL is invoked to link, load and start the program. |
(19) | The contents of the base register for UNBIND1 are output. 31-bit addressing is set (bit 231 = 1); the load address is below the 16-MB boundary. |
(20) | DBL has loaded the CSECT BIND3. The contents of the base register for BIND3 are output. 31-bit addressing is set (bit 231 = 1); the load address is above the 16-MB boundary. |
(21) | Following the return from BIND3, the program run is continued in UNBIND1 and module BIND3 is unloaded. |