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 VSVI1 macro provides the user with information on entries in the DBL tables. For this purpose, DBL accesses the following contexts:
user contexts and/or system contexts
Information on system contexts is output only under TSOS.contexts of common memory pools in which shared code is stored and to which the user is connected.
The following information can be requested:
a list of context names (SELECT=CTXLIST),
the size of the code loaded in a context and the size of the associated link and load information (SELECT=CTXSIZE),
a list containing the names, load addresses, lengths, types, attributes and contexts of CSECTs, ENTRYs and COMMONs (SELECT=ALLLIST),
a list containing the names, load addresses, lengths, types, attributes and contexts of all CSECTs and COMMONs (SELECT=MODLIST),
a record containing the name, load address, length, type, attribute, context, version and HSI code of a single control section (CSECT), ENTRY or COMMON (SELECT= BYNAME),
a record containing the name, load address, length, type, attributes and context of a control section (CSECT) or COMMON specified by means of an address (SELECT= BYADDR).
A list of ILEs belonging to one or more contexts.
The individual items of information (name, load address, length, attribute, type, context and HSI code) can be selected independently of one another. It is also possible to request just the length of the desired output information.
A description of the output information follows immediately after the operand description (see "VSVI1 - Output link and load information").
Macro format and description of operands
VSVI1 |
SELECT=CTXLIST / CTXSIZE / ALLLIST / MODLIST / BYNAME / BYADDR / ILELIST ,OUTADDR=addr / (r) / label ,OUTLEN=integer ,ADDRESS=YES / NO ,CONTEXT=YES / NO ,CTXPRIV=ANY / YES / NO ,CTXSEL=ALL / LOCAL / GLOBAL / POOL ,HSI=NO / YES [,{INNAME=name / INNAME@={addr / (r)} / INADDR={addr / (r) / label}}] [,{INCTX=name / INCTX@={addr / (r)}}] ,INSTRUCT=addr ,INTVERS=BLSP2 / SRV001 / SRV002 / SRV003 ,LEN=YES / NO ,NAME=YES / NO ,RUNMOD=STD / ADV ,SCOPE=ALL / USER_GROUP / GLOBAL / GROUP ,SIZONLY=NO / YES ,SYMTYP = ANY / CSECT / ISL / NOTISL ,TYPE=YES / NO ,VERSION=NO / YES ,MF=S / C / D / E / L / M [,PARAM=addr / (r)] ,PREFIX=P / p [,LABEL=name] |
The operands are described in alphabetical order below.
ADDRESS=
Specifies whether the load addresses are to be included in the information output.
YES
The load addresses will be output.
NO
The load addresses will not be output.
CONTEXT=
Specifies whether the names of the contexts are to be included in the information output.
YES
The context names will be output.
NO
The context names will not be output.
CTXPRIV=
Specifies the access privilege for the context search (only in conjunction with RUNMOD=ADV).
For nonprivileged users (not TSOS), the entry is ignored and internally set to CTXPRIV=NO.
For privileged users (TSOS), the following applies:
If RUNMODE=ADV and the CTXPRIV parameter was not specified, DBL sets CTXPRIV=ANY.
If RUNMODE=STD, DBL ignores the input value for CTXPRIV and sets
CTXPRIV=YES.ANY
Both privileged and nonprivileged contexts are to be searched. For nonprivileged users, only nonprivileged contexts will be searched.YES
Only privileged contexts will be searched. This option is permitted for privileged users only.NO
Only nonprivileged contexts will be searched.
CTXSEL=
Specifies the scope of the context search (only in conjunction with RUNMOD=ADV).
For nonprivileged users (not TSOS), only CTXSEL=LOCAL or CTXSEL=POOL is permitted. Any other entry is handled in the same way as CTXSEL=LOCAL.
For privileged users (TSOS), the following applies:
If RUNMODE=ADV and the CTXSEL parameter was not specified, DBL sets CTXSEL=ALL.
If RUNMODE=STD, DBL ignores the input value for CTXSEL and sets CTXSEL=GLOBAL.ALL
Contexts with the SYSTEM and USER scope will be searched. Contexts with the scope POOL will not be considered.GLOBAL
Only contexts with the SYSTEM scope will be searched.LOCAL
Contexts with the USER scope will be searched.
RUNMODE=ADV will also search the pre-loaded part of the context of subsystems if following conditions are true:the task in which the VSVI1 macro is called is linked to the subsystem
the subsystem possesses the attribute MEMORY-CLASS=*BY-SLICE
POOL
Contexts of memory pools into which shared code was loaded by means of the ASHARE macro will be searched. The set of memory pool contexts can be restricted by specifying a memory pool scope (SCOPE operand).
HSI=
Specifies whether the output is to contain information on the hardware-software interface (only in conjunction with RUNMOD=ADV).
NO
The HSI code will not be output.
YES
The HSI code and HSI compiler information will be output. This operand value is relevant only for the output of symbol information and may be specified only in conjunction with RUNMOD=ADV.
INNAME=name
Specifies the name of a control section (CSECT), ENTRY or COMMON whose name, load address, length and attributes are to be output.“name” may be up to 32 characters long.
The INNAME operand must be specified in conjunction with the SELECT=BYNAME operand.
INNAME@=
May be specified only if MF=M. Specifies the address of a field containing the name of a control section (CSECT), ENTRY or COMMON.
addr
Address of an auxiliary field which contains the field address searched for.
(r)
r = register containing the field address searched for.
INADDR=
Specifies an address for which the corresponding items of information (name, load address, length and attributes) are to be output.
The INADDR operand must be specified in conjunction with the SELECT=BYADDR operand.
addr
Address of a field which contains the program address searched for.
May be specified only if MF=M.
(r)
r = register containing program address searched for. May be specified only if MF=M.
label
Program address. The address can be specified as a symbolic address or as a constant (X'...'). May be specified only if MF=S or MF=L.
INCTX=name
Specifies a context which is to be searched. “name” may be up to 32 characters long. If the operand is not used the contexts will be searched in accordance with the CTXSEL and CTXPRIV operand values; if CTXSEL=POOL is specified, the contexts will be searched in accordance with the SCOPE operand. The INCTX operand will be ignored if SELECT=CTXLIST has also been specified.
INCTX@=
May be specified only if MF=M.
Specifies the address of a field containing the name of the context which is to be searched.
addr
Address of an auxiliary field which contains the field address searched for.
(r)
r = register containing the field address searched for.
INSTRUCT=addr
This operand is only available if INTVERS=SRVxxx and xxx >= 001 is specified. It must be used with SELECT=BYNAME.
Symbolic address of a structure containing an EEN (extended external name). The structure consists of two 4-byte length fields, the first one containing the length of the extended external name, and the second one containing the address of the extended external name.
INTVERS=
This operand defines the version of the VSVI1 macro interface.
BLSP2
Default; corresponds to macro version 3.
SRV001
Corresponds to macro version 4. This version is supported as of BLSSERV V2.0.
SRV002
Corresponds to macro version 5. This version is supported as of BLSSERV V2.3B.
SRV003
Corresponds to macro version 6. This version is supported as of BLSSERV V2.5A.
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 VSVI1 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 VSVI1 MF=DThe name “xVSVIDS” if no “name” has already been specified, where “x” is the value of the PREFIX operand of a preceding macro
VSVI1 MF=D, PREFIX=x
The default value for “x” is “P”.The name of the longer DSECT containing the parameter list of the VSVI1 macro if the macro
VSVI1 MF=Cwas specified earlier.
LEN=
Specifies whether the lengths are to be included in the information output.
YES
The lengths will be output.
NO
The lengths will not be output.
NAME=
Specifies whether the names of CSECTs, ENTRYs and COMMONs are to be included in the information output.
YES
The names are to be output.
NO
The names are not to be output.
OUTADDR=
Specifies the address of a field into which DBL is to place the information.
addr
Address of an auxiliary field which contains the field address searched for. May be specified only if MF=M.
(r)
r = register containing the field address searched for. May be specified only if MF=M.
label
Symbolic field address.May be specified only if MF=S or MF=L.
OUTLEN=integer
Specifies the length of the output field (in bytes). The minimum length is 4 bytes.
RUNMOD=
Specifies the operating mode in which the VSVI1 macro will be processed.
STD
The macro will be processed in the standard form. The information output in this case is fully compatible with the information supplied by the previous VSVI macro of BS2000 Version 9.5.
In standard form the VSVI1 macro processes only 8-character names in the case of CSECTs, ENTRYs and COMMONs, and only names with up to 16 characters in the case of contexts. This can lead to conflicts if, for example, information on a loaded LLM is to be output, since longer names are truncated.
ADV
The macro will be processed in the extended form. In this form the VSVI1 macro processes names consisting of up to 32 characters.
The following operands are permitted only in conjunction with RUNMOD=ADV:
SELECT=ILELIST, CTXSEL, SCOPE, CTXPRIV, HSI, VERSION.
SCOPE=
Specifies which memory pool contexts are to be considered if CTXSEL=POOL was specified (only in conjunction with RUNMOD=ADV).
ALL
Memory pool contexts will be considered.
GROUP
Only the contexts of common memory pools with the GROUP scope will be considered.
USER_GROUP
Only the contexts of common memory pools with the USER_GROUP scope will be considered.
GLOBAL
Only the contexts of common memory pools with the GLOBAL scope will be considered.
SELECT=
Selects the type of information to be output.
CTXLIST
A list of context names will be output (user (contexts of the task and/or system contexts and/or memory pool contexts and/or local subsystem contexts).
CTXSIZE
Only allowed in combination with RUNMOD=ADV.
The size of the code loaded into a context and the size of the associated link and load information will be output. The size is specified in bytes and is rounded up to a multiple of 4 Kbytes. The name of the context must be defined using INCTX or INCTX@.
ALLLIST
A list containing the names, load addresses, lengths and attributes of all CSECTs, ENTRYs and COMMONs will be output.
MODLIST
A list containing the names, load addresses, lengths and attributes of all CSECTs and COMMONs will be output.
BYNAME
A record containing the name, load address, length and attributes of a single control section (CSECT), ENTRY or COMMON will be output. The name of the symbol must be specified with the INNAME or INSTRUCT (and INTVERS=SRVxxx with xxx >= 001) operand.
BYADDR
A record containing the name, load address, length and attributes of a single control section (CSECT) or COMMON will be output. The address of the symbol must be specified with the INADDR operand.
ILELIST
A list containing information on ILEs in the specified context is to be output. SELECT=ILELIST may be specified only in conjunction with RUNMOD=ADV.
SIZONLY=
Specifies whether the desired information or merely the length of the desired information will be output.
NO
The information will be transferred to the output field.
YES
Only the length of the information, not the information itself, will be transferred to the output field.
SYMTYP=
This operand is available when INTVERS=SRVxxx and xxx >= 003 are specified. It is only meaningful in conjunction with the SELECT=BYNAME operand, and is ignored in any other case.
It specifies the type of the symbol defined with INNAME, INNAME@ or INSTRUCT for which information is requested.
ANY
The type of the symbol searched for is irrelevant.
CSECT
Only CSECTs with the specified name are searched for.
ISL
This specification is only relevant for privileged users. Furthermore, it is also only meaningful if the CP context (see INCTX/INCTX@) or privileged contexts (CTXSEL=ALL/GLOBAL and CTXPRIV=ANY/ALL) are searched.
Only ISL ENTRYs with the specified name are searched for.
NOTISL
Only symbols with the specified name are searched for, the CSECTs or ENTRYs, but not ISL.
TYPE=
Specifies whether the types (CSECT/ENTRY/COMMON) are to be included in the information output.
YES
The types will be output.
NO
The types will not be output.
VERSION=
Specifies whether the output is to contain information on the program version (only in conjunction with RUNMOD=ADV).
NO
The program version will not be output.
YES
The program version will be output. This operand value is relevant only for the output of symbol information and may be specified only in conjunction with RUNMOD=ADV.
Notes on the macro call
At least one of the operands NAME, ADDRESS, LEN, TYPE, CONTEXT, VERSION or HSI must be specified for the output of information.
None of the operands NAME, ADDRESS, LEN, TYPE, CONTEXT, VERSION or HSI needs to be specified if the user merely wishes to check whether
a specified name (INNAME/INSTRUCT operand) is the name of a symbol (SELECT=BYNAME operand),
a specified address (INADDR operand) is available (SELECT=BYADDR operand),
a specified context (INCTX operand) is available (SELECT=ALLLIST or SELECT=MODLIST operand).
In these cases, only the return code is significant.
If the name, address or context cannot be found the following return code is passed:
X'0440003C'
Name of symbol not found
X'04400038'
Address not found
X'04400040'
Context not found
If the name, address or context is found DBL delivers the return code X'00000000'.
The length of the output area into which DBL is to transfer the information has to be defined with the OUTLEN operand. If the specified length is too small the information will be truncated to this length. If the specified length is less than the length of the smallest item of information, no information will be output. In both cases DBL supplies a return code.
If a module contains more than one CSECT, the information selected by DBL is dependent on the SELECT operand, as follows:
with SELECT=BYADDR the information refers to the CSECT containing the address specified by INADDR.
with SELECT=BYNAME, and if INNAME identifies a CSECT name, the information refers to this CSECT.
with SELECT=ALLLIST separate information is output for each CSECT.
The VSVI1 macro attempts to carry on processing as far as possible in the event of an error. If, for example, the operands specify that more than one context has to be searched, and an error occurs while a context is being searched, the VSVI1 macro continues by searching the next context. The cause of the error is reported by DBL in a return code. This return code always refers to the last error that occurred.
If SELECT=BYNAME is specified, either the INNAME or INSTRUCT operand must be specified. However, they cannot be specified together.
When SELECT=BYNAME is set, DBL searches the context only until the first symbol of the specified name (INNAME or INSTRUCT operand) is found. If there are several symbols with the same name, only information on the first symbol found is output.
If just the length of the information is desired (SIZONLY=YES operand), DBL takes the length of the information up to the null entry as the length.
If the memory area specified in OUTADDR is only readable, or if zero was specified for OUTLEN, processing is aborted with a user dump.
If a context list is requested (SELECT=CTXLIST), NO can be specified for the NAME, ADDRESS, LEN, TYPE, CONTEXT, VERSION, HSI and SIZONLY operands.
When information about contexts of common memory pools is being requested (CTXSEL=POOL), the return code X'08400048' may be issued as a result of concurrent access to a common memory pool.
The following applies for nonprivileged users (not $TSOS):
The user-specific values for the operands are ignored and are filled internally by the DBL with CTXPRIV=NO.
For the CTXSEL operand, values other than POOL are ignored and are filled internally by the DBL with CTXSEL=LOCAL.
If VSVI1 is called SELECT=BYNAME but without INCTX, the DBL searches first in the private class 6 memory and in common memory pools. If it does not find the symbol specified, it tries to establish a connection to nonprivileged subsystems.
Possible operand combinations
The following table shows which operands are mandatory or permitted depending on the SELECT operand:
SELECT= | IN | INNAME/ | IN | OUT | OUT | CTX | CTX | SCOPE | SYM |
CTXLIST | - | - | - | P | P | E | E | E | I |
CTXSIZE | - | - | P | P | P | - | - | - | I |
ALLLIST | - | - | E | P | P | E | E | E | I |
MODLIST | - | - | E | P | P | E | E | E | I |
ILELIST | - | - | E | P | P | E | E | E | I |
BYADDR | P | - | E | P | P | E | E | E | I |
BYNAME | - | P | E | P | P | E | E | E | E |
M | Parameter mandatory |
P | Operand permitted |
I | Operand ignored |
- | Operand irrelevant for this SELECT specification. |
Output information when RUNMOD=STD
In RUNMOD=STD operating mode the macro is processed in the standard form. The information output in this case is fully compatible with the information supplied by the previous VSVI macro of BS2000 Version 9.5.
In standard form the VSVI1 macro processes only 8-character names in the case of CSECTs, ENTRYs and COMMONs, and only names with up to 16 characters in the case of contexts. Longer names of CSECTs, ENTRYs and COMMONs are truncated to
8 characters, and longer names of contexts to 16 characters.
The reference size for an item of information output is an entry in the DBL tables. The entry has a fixed length of 36 bytes.
Format of the entries
Byte | Length | Field | Field entry | Coding/Remarks |
0- 7 | 8 | Name of symbol | left-justified with trailing | Character constant |
8-11 | 4 | Load address | - | Hexadecimal constant |
12-15 | 4 | Length | - | Hexadecimal constant |
16 | 1 | Type | - | X'F0' corresponds to CSECT |
17 | 1 | Attributes | 1 or 2 bit per attribute | 27 corresponds to INVISIBILITY |
18-19 | 2 | X' 0000' | Alignment of the following field | |
20-35 | 16 | Name of the | left-justified with trailing | Character constant |
If just the length of the information is desired (SIZONLY=YES operand), this takes up the first 4 bytes of the output field.
Multiple entries are output consecutively in the same sequence. The last entry is followed by a null entry. A pseudoentry is output if the specified program address cannot be found (SELECT=BYADDR operand).
Field | Null entry | Pseudoentry | |
Length | Field entry | ||
Name of CSECT/COMMON/ENTRY | 8 | X'40.......40' | C'ABSOLUTE' |
Load address | 4 | X'0.....0' | X'0.....0' |
Length | 4 | X'F.....F' | X'0.....0' |
Type | 1 | X'C5' | X'00' |
Attribute | 1 | X'00' | X'00' |
Name of context | 16 | X'40.......40' | X'40..........40' |
Notes
The length of the output field is derived from adding together the individual entries. If the length is too small the information will be truncated. The information is not transferred if it is shorter than the minimum length for a requested entry. The minimum length = length of an entry minus the length of items that are not to be output (e.g. NAME=NO).
Only the INVISIBILITY and AMODE attributes are relevant for an ENTRY, and only PAGE and AMODE for a COMMON.
A control section or ENTRY has the INVISIBILITY attribute if it was masked during linking or subsequent loading.
If SELECT=CTXLIST is specified, a list of 16-byte context names is output, each followed by 16 blanks (X'40') to indicate the end of the name.
Format:
CTX1' 'CTX2' '' 'If SELECT=CTXSIZE is specified, the output information consists of two words. The first word contains the size of the code in the context and the second word contains the size of the link and load information for this context. The specification is given in bytes and is rounded up to a multiple of 4 Kbytes.
Output information when RUNMOD=ADV
In RUNMOD=ADV operating mode the macro is processed in the extended form. In extended form the macro processes names up to 32 characters long, and ILE information, HSI code and HSI compiler information may be requested in addition. The reference size for a specified item of information is an entry in the DBL tables. The entry is of variable length, being dependent on the length of the names and the type of information requested.
Format of the entries
Bytes | Length | Field | Field entry | Coding/comment |
0 - 3 | 4 | Load address | — | Hexadecimal constant |
4 - 7 | 4 | Length | — | Hexadecimal constant |
8 | 1 | Type | — | X'F0' = CSECT |
9 | 1 | Attributes | 1 or 2 bit | 27 corresponds to INVISIBILITY |
10 - 11 | 2 | X'0000' | Alignment of following field | |
12 | 1 | HSI code | — | X'01' = 7500 (/390) |
13 | 1 | HSI compiler information | — | Compiler-dependent; |
14 | 1 | Length n of the symbol | — | Hexadecimal constant |
15 | n | Name of the symbol | — | Alphanumeric constant |
15+n | 1 | Length m of the version | — | Hexadecimal constant |
15+(n+1) | m | Version of the program to | — | Alphanumeric constant |
15+(n+1) | 1 | Length l of the context | — | Hexadecimal constant |
15+(n+1) | l | Name of the context | — | Alphanumeric constant |
The total length of an entry may be calculated as follows:
Entry length = 17 + n + m + l
If just the length of the information is desired (SIZONLY=YES operand), this takes up the first 4 bytes of the output field.
Blank entries and pseudoentries
Multiple entries are output consecutively in the same order. The last entry is followed by a null entry. A pseudoentry is output if the specified program address cannot be found (SELECT=BYADDR operand).
Field | Null entry | Pseudoentry | |
Length | Field entry | ||
Load address | 4 | X'0.....0' | X'0.....0' |
Length | 4 | X'F.....F' | X'0.....0' |
Type | 1 | X'C5' | X'00' |
Attribute | 1 | X'00' | X'00' |
Length n of symbol name | 1 | X'08' | X'08' |
Name of symbol | 8 | X'40......40' | C'ABSOLUTE' |
Length m of context name | 1 | X'00' | X'00' |
Notes
If SELECT=CTXLIST is specified, a list of variable-length context names is output. The first byte of each list item contains the length of the context name; the following bytes contain the context name proper. The list is terminated with a list item containing 32 blanks (X'40').
Format:
0DLOCAL#DEFAULT04CTX104CTX220' 'If SELECT=CTXSIZE is specified, the output information consists of two words. The first word contains the size of the code in the context and the second word contains the size of the link and load information for this context. The specification is given in bytes and is rounded up to a multiple of 4 Kbytes.
If a user (not $TSOS) calls the VSVI1 macro with SELECT=BYNAME but without specifying INCTX, and if DBL cannot find this symbol either in this user's class 6 memory or in shared code in memory pools, DBL attempts to establish a connection to the nonprivileged DSSM subsystems.
If SELECT=ILELIST is specified, a formatted list entry is output for each ILE. The context name may also be included in this list on request. If CONTEXT=NO is specified the context name is not output. An entry for an ILE symbol has the following format:
Bytes | Length | Field name | Meaning and/or values |
0 | 1 | STATE | X'01' = ACTIVE |
1 | 1 | CONTROL | X'01' = SYSTEM |
2 | 1 | HSI_CODE | X'01' = 390 |
3 | 1 | RESERVED1 | Reserved (must contain X'00') |
4 | 4 | LOAD_ADDR | Address of the IL routine |
8 | 4 | SERVER_ADDR | Address of the ILE server |
12 | 2 | REF_DISPL | Distance of the external reference to the server within the |
14 | 32 | NAME | Name of the ILE symbol |
46 | 2 | RESERVED2 | Reserved (must contain X'0000') |
48 | 32 | CONTEXT | Name of the context to which the ILE belongs |
The entry format roughly corresponds to the format that is also generated when the ILEMIT macro is called.
The last ILE entry is followed by a blank entry in which all fields (except the NAME field) contain binary zeros. The NAME field contains blanks. A blank entry does not contain a CONTEXT field.
Return information and error flags
Standard header:
+---------------+ | | | | | |c|c|b|b|a|a|a|a| +---------------+
A return code relating to the execution of the VSVI1 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'0020' | The specified length of the output field (OUTLEN operand) is less than |
X'0C' | X'01' | X'0024' | The output field (OUTADDR operand) is not aligned on a halfword |
X'0C' | X'01' | X'0028' | Illegal entry for the SELECT operand. |
X'0C' | X'01' | X'002C' | Illegal entry for an operand. This may be:
|
X'0C' | X'01' | X'002D' | Illegal entry for the SYMTYP operand. |
X'0C' | X'01' | X'0030' | The caller has not specified any of the information operands (NAME,
|
X'08' | X'40' | X'0034' | The length of the output area specified in the OUTLEN operand is less |
X'0C' | X'01' | X'0034' | The length of the output area specified in the OUTLEN operand is too |
X'04' | X'40' | X'0038' | The address specified in the INADDR operand belongs to none of the |
X'04' | X'40' | X'003C' | The name specified in the INNAME or INSTRUCT operand designates |
X'04' | X'40' | X'0040' | The context name specified in the INCTX operand cannot be found or |
X'0C' | X'20' | X'0044' | Internal error while the function was being executed. No output is |
X'08' | X'40' | X'0048' | One or more contexts with global scope are being used by another task. |
X'04' | X'40' | X'004C' | The name of the symbol is longer than 8 characters and RUNMOD=STD |
X'04' | X'40' | X'0050' | The specified context, though present, is empty because all its objects |
X'04' | X'40' | X'0070' | The task is not connected to the memory pool. |
X'0C' | X'20' | X'0198' | No more memory available. |
X'0C' | X'40' | X'0204' | Internal error in memory management. |
X'0C' | X'40' | X'0208' | Internal error in data manager. |
X'0C' | X'40' | X'020C' | Internal error in the symbolic information tables. |
X'0C' | X'20' | X'0300' | Error in $REQM, $RELM (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 PROGA program run, a BIND macro is issued to load a second control section, PROGB, as an overlay. PROGB is stored as an object module in library MACEXMP.LIB. Before and after PROGB is loaded, the VSVI1 macro is called in order to transfer link and load information from the DBL tables to an output area. Both control sections are to execute in 31-bit addressing mode. PROGA is to be loaded below, and PROGB above, the 16-MB boundary. An ENTRY is defined in PROGB. After the BIND macro is called, PROGB is to execute first. Following the execution of PROGB a return branch is to be made to PROGA.
Source listing
PROGA START
PROGA AMODE 31 ————————————————————————————————————————————————————— (1)
PROGA RMODE 24
BALR 3,0
USING *,3
USING BINDDS,6 ——————————————————————————————————————————————— (2)
USING VSVI1DS,7 —————————————————————————————————————————————— (3)
ST 3,AREA11
UNPK AREAH,AREA1
MVC AREAA(8),AREAH
WROUT1 WROUT OUT,ERROR,PARMOD=31 ———————————————————————————————————— (4)
MVI ADR1,X'D1' ————————————————————————————————————————————— (5)
MVC ADR1+1(L'ADR1-1),ADR1
VSVI1 MF=E,PARAM=VSVI1PAR ———————————————————————————————————— (6)
LA 7,VSVI1PAR
CLC YVSVRET,=X'00000000' ——————————————————————————————————— (7)
BNE VSVIERR ———————————————————————————————————————————————— (8)
BACK LA 12,VSVI
BIND BIND MF=E,PARAM=BINDPAR ————————————————————————————————————— (9)
LA 6,BINDPAR
CLC XBINRET,=X'00000000' ——————————————————————————————————— (10)
BE VSVI
MVC OUT+5(28),='BIND ERROR! '
WROUT OUT,ERROR,PARMOD=31 ———————————————————————————————————— (11)
B ERROR
VSVI VSVI1 MF=E,PARAM=VSVI1PAR ———————————————————————————————————— (12)
CLC YVSVRET,=X'00000000' ——————————————————————————————————— (13)
BE MVC
VSVIERR MVC OUT+5(28),='VSVI1 ERROR! '
WROUT OUT,ERROR,PARMOD=31 ———————————————————————————————————— (14)
B ERROR
MVC MVC OUT+5(28),='VSVI1 PROCESSED '
WROUT OUT,ERROR,PARMOD=31 ———————————————————————————————————— (15)
MVC OUT+5(28),='RETURN TO PROGA '
WROUT OUT,ERROR,PARMOD=31
ERROR TERM
*****************
DS 0F
ADR1 DS CL180 —————————————————————————————————————————————————— (16)
OUT DC Y(OUTE-OUT)
DS CL3
DC C'PROGA: 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=PROGB,SYMBLAD=PROGB@,BRANCH=YES,PROGMOD=ANY,*
LIBLINK=PLAMLIB –––––––––––––––––––––––––––––––––––––––––– (9)
VSVI1PAR VSVI1 MF=L,SELECT=ALLLIST,CTXSEL=ALL,OUTADDR=ADR1,OUTLEN=180 ––– (6)
PROGB@ DS A
BINDDS BIND MF=D,PREFIX=X —————————————————————————————————————————— (17)
VSVI1DS VSVI1 MF=D,PREFIX=Y —————————————————————————————————————————— (18)
END
PROGB CSECT PAGE ——————————————————————————————————————————————————— (19)
PROGB AMODE ANY
PROGB RMODE ANY
ENTRY ENTR ——————————————————————————————————————————————————— (20)
ENTR BALR 4,0
USING *,4
ST 4,AREA11
UNPK AREAH,AREA1
MVC AREAA(8),AREAH
WROUT OUT,ERROR,PARMOD=31 ———————————————————————————————————— (21)
BR 12
ERROR TERM
*****************
OUT DC Y(OUTE-OUT)
DS CL3
DC C'PROGB: 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 PROGA. The attribute RMODE=24 means that PROGA 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 VSVI1 macro, which is generated at the symbolic address VSVI1DS as a result of a VSVI1 macro specifying MF=D. |
(4) | The contents of the base register for PROGA are output to indicate the addressing mode and the load address. |
(5) | The output field for the VSVI1 macro is preset to C'J'. |
(6) | The VSVI1 macro is called in its E form. At this point in the program, therefore, only the instruction code is generated. The associated operand list is created at the symbolic address VSVI1PAR by means of a VSVI1 macro specifying MF=L. As a result of the operand values specified in the list, the VSVI1 macro causes a list containing the names, load addresses, lengths and attributes of all CSECTs, ENTRYs and COMMONs to be output before PROGB is loaded. |
(7) | Following execution of the VSVI1 macro, a check is made to verify that the YVSVRET field of the standard header contains the return code X'00000000', which indicates error-free execution of the macro. The name YVSVRET originates from the DSECT that was generated under the symbolic address VSVI1DS as a result of a VSVI1 macro specifying MF=D and PREFIX=Y (see (18)). This DSECT describes the layout of the operand list of the VSVI1 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, VSVI1PAR). |
(8) | If the VSVI1 macro does not execute without error, a branch is made to error exit VSVIERR, an error message is output to SYSOUT and the PROGA program run is terminated. |
(9) | 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:
|
the 31-bit addressing mode is set for PROGB (PROGMOD=ANY)
the program run is continued in PROGB after PROGB is loaded
(BRANCH=YES).
(10) | 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=Y (see (17)). 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). |
(11) | If the BIND macro does not execute without error, an error message is output to SYSOUT and the PROGA program run is terminated. |
(12) | Same as (6), but after PROGB has been loaded. |
(13) | Same as (7), but after PROGB has been loaded. |
(14) | If the VSVI1 macro does not execute without error, an error message is output to SYSOUT and the PROGA program run is terminated. |
(15) | Messages to SYSOUT indicate that the program run has been continued in PROGA and then link and load information has been output by means of the VSVI1 macro. |
(16) | Output field for the VSVI1 macro. |
(17) | The BIND macro with 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). |
(18) | The VSVI1 macro with MF=D generates a DSECT which describes the layout of the operand list of the VSVI1 macro. The operand PREFIX=Y causes the letter Y to be prefixed to all symbolic names in this DSECT (field names and equates). |
(19) | The CSECT statement defines the control section PROGB with the attributes AMODE=ANY and PAGE. |
(20) | ENTRY statement for the symbolic address ENTR. |
(21) | The contents of the base register for PROGB are output to indicate the addressing mode and the load address. |
Runtime listing
/start-assembh
% BLS0500 PROGRAM 'ASSEMBH', VERSION '<ver>' OF '<date>' LOADED
% ASS6010 <ver> OF BS2000 ASSEMBH READY
//compile source=*library-element(macexmp.lib,proga), -
// compiler-action=module-generation(module-format=llm), -
// module-library=macexmp.lib, -
// listing=parameters(output=*library-element(macexmp.lib,proga)), -
// test-support=*aid
% ASS6011 ASSEMBLY TIME: 786 MSEC
% ASS6018 0 FLAGS, 0 PRIVILEGED FLAGS, 0 MNOTES
% ASS6019 HIGHEST ERROR-WEIGHT: NO ERRORS
% ASS6006 LISTING GENERATOR TIME: 232 MSEC
//compile source=*library-element(macexmp.lib,progb), -
// compiler-action=module-generation(module-format=llm), -
// module-library=macexmp.lib, -
// listing=parameters(output=*library-element(macexmp.lib,progb)), -
// test-support=*aid
% ASS6011 ASSEMBLY TIME: 191 MSEC
% ASS6018 0 FLAGS, 0 PRIVILEGED FLAGS, 0 MNOTES
% ASS6019 HIGHEST ERROR-WEIGHT: NO ERRORS
% ASS6006 LISTING GENERATOR TIME: 93 MSEC
//end
% ASS6012 END OF ASSEMBH
/add-file-link link-name=plamlib,file-name=macexmp.lib ———————————————— (1)
/load-executable-program library=macexmp.lib,element-or-symbol=proga - (2)
// program-mode=*any,test-options=*aid
% BLS0523 ELEMENT 'PROGA', VERSION '@' FROM LIBRARY
':2OSG:$QM212.MACEXMP.LIB' IN PROCESS
% BLS0524 LLM 'PROGA', VERSION ' ' OF '<date> <time>' LOADED
/%in back;%in error;%r ——————————————————————————————————————————————— (3)
PROGA: BASE REG.= 80000002 ———————————————————————————————————————————— (4)
STOPPED AT LABEL: BACK , SRC_REF: 53, SOURCE: PROGA , PROC: PROGA
/%d adr1 %x ——————————————————————————————————————————————————————————— (5)
*** TID: 00100136 *** TSN: 1E17 *********************************************
CURRENT PC: 00000054 CSECT: PROGA ***************************************
V'00000144' = ADR1 + #'00000000'
00000144 (00000000) D7D9D6C7 C1404040 00000000 00000384 PROGA .......d
00000154 (00000010) F0200000 D3D6C3C1 D37BC4C5 C6C1E4D3 0...LOCAL#DEFAUL
00000164 (00000020) E3404040 40404040 40404040 00000000 T ....
00000174 (00000030) FFFFFFFF C5000000 40404040 40404040 ~~~~E...
00000184 (00000040) 40404040 40404040 D1D1D1D1 D1D1D1D1 JJJJJJJJ
00000194 (00000050) D1D1D1D1 D1D1D1D1 D1D1D1D1 D1D1D1D1 JJJJJJJJJJJJJJJJ
REPEATED LINES: 4
000001E4 (000000A0) D1D1D1D1 D1D1D1D1 D1D1D1D1 D1D1D1D1 JJJJJJJJJJJJJJJJ
000001F4 (000000B0) D1D1D1D1 JJJJ
/%r PROGB: BASE REG.= 81000002 ———————————————————————————————————————————— (6) VSVI1 PROCESSED RETURN TO PROGA STOPPED AT LABEL: ERROR , SRC_REF: 208, SOURCE: PROGA , PROC: PROGA /%d adr1 %x ——————————————————————————————————————————————————————————— (7) CURRENT PC: 00000126 CSECT: PROGA *************************************** V'00000144' = ADR1 + #'00000000' 00000144 (00000000) D7D9D6C7 C2404040 01000000 0000008A PROGB ........ 00000154 (00000010) F0680000 D3D6C3C1 D37BC4C5 C6C1E4D3 0...LOCAL#DEFAUL 00000164 (00000020) E3404040 C5D5E3D9 40404040 01000000 T ENTR .... 00000174 (00000030) 00000000 F1600000 D3D6C3C1 D37BC4C5 ....1-..LOCAL#DE 00000184 (00000040) C6C1E4D3 E3404040 D7D9D6C7 C1404040 FAULT PROGA 00000194 (00000050) 00000000 00000384 F0200000 D3D6C3C1 .......d0...LOCA 000001A4 (00000060) D37BC4C5 C6C1E4D3 E3404040 40404040 L#DEFAULT 000001B4 (00000070) 40404040 00000000 FFFFFFFF C5000000 ....~~~~E... 000001C4 (00000080) 40404040 40404040 40404040 40404040 000001D4 (00000090) D1D1D1D1 D1D1D1D1 D1D1D1D1 D1D1D1D1 JJJJJJJJJJJJJJJJ 000001E4 (000000A0) D1D1D1D1 D1D1D1D1 D1D1D1D1 D1D1D1D1 JJJJJJJJJJJJJJJJ 000001F4 (000000B0) D1D1D1D1 JJJJ
(1) | The file link name used in the BIND call of program PROGA is assigned. |
(2) | DBL is invoked to link and load the program. |
(3) | The AID command %INSERT is used to define the test points BACK and ERROR. The %RESUME command passes control to the called program. |
(4) | The contents of the base register for PROGA are output. 31-bit addressing is set (bit 231 = 1); the load address is below the 16-MB boundary. |
(5) | The link and load information has been transferred to field ADR1. ADR1 was preset to X'D1'. The VSVI1 macro call was issued before PROGB was loaded. The first 8 bytes reveal the name PROGA for the first control section. It is followed by the load address X'00000000' and the length X'0000037C' (892 bytes). The next two bytes indicate the type and attribute of the control section. Type X'F0' (corresponds to CSECT) and attribute X'20' (corresponds to AMODE=31). The following values (X'0000') are used for alignment. Then comes the 16-byte context name (LOCAL#DEFAULT). The following fields contain the “null entry” for name (X'40....40'), load address (X'00000000'), length (X'FFFFFFFF'), attribute (X'C5') and context name (X'40....40'). |
(6) | After PROGB has been loaded, the program run is continued in PROGB. The contents of the base register are output. 31-bit addressing mode is set. The load address is located above 16 MB. After PROGB has been completed, PROGA is continued. |
(7) | Following loading of PROGB, there are several DBL entries in ADR1. First is the entry for PROGB and the ENTRY in PROGB, then the entry for PROGA. The load address for PROGB is X'01000000', the length X'00000082' (130 bytes). Its type is X'F0' (CSECT) and its attributes X'68' (AMODE=ANY and PAGE). The ENTRY name is C'ENTR', type X'F1' (ENTRY), attribute X'60' (AMODE=ANY). Then comes the 16-byte context name (LOCAL#DEFAULT). This is followed by the entry for PROGA and finally by the null entry. |