I Produced Element
2. Program Construction and Execution
2.2.1. Collector Initiation (@MAP) Purpose:
2.2.2.1. Element Inclusion (IN) Purpose:
Allows the user to specifically include an element or all relocatable elements of a file in the collection of a program. An element may be preceded by a filename. The elements indicated on an IN directive are placed in the segment named by the preceding SEG directive (see 2.2.2.14).
All parameters in the IN directive are optional. If all parameters are omitted, IN TPF$. is assumed.
Format:
IN name-1,name-2,name-3, ... ,name-n
IN(bank-list) name-1 ($lcs),name-2($lcs), ... ,name-n($lcs) Parameters:
name
bank-list
$Ics
Description:
Specifies the element or entire file to be included in the collection.
See 1.3, 1.4 for standard file and element notation.
A list of bank-names to be used with local element inclusion.
Specifies which location counters of name-1 are to be included in this part of the program.
Bank-list and $Ics are used only with bank-named collections (see 2.2.5).
By stating FILENAME without a following element name, the user can specify the inclusion of all relocatable elements in a program file. In bank-implied collections if some elements of a file have been explicitly named, these are included as specified and the 'IN' filename serves to bring in only the remaining elements in the file. When specifying an entire file for inclusion, a period must follow the filename.
When name consists of an element name only with no version specified, any RB element with that name irrespective of version, is eligible for inclusion. If RB elements with the same element name but different version names exist in the same file, ambiguities may arise. The CLASS directive (see 2.2.2.8) may be used to overcome the ambiguity. Alternatively, the ambiguity will not be present if the version name is explicitly stated as part of name on the IN statement.
IN name/
must be used to specifically select an RB element with a version name consisting of 12-space characters, which is the default version.
Elements named, but not directly associated with CI filename, are searched for first in TPF$, then in any files named on LIB directives (see 2.2.2.3) and finally in the System Relocatable Library (RLlB$).
In bank-implied collections, an element name may appear on only one IN directive and only once during a collection. A version may be present, but the element name itself may still appear only once.
The version is necessary only if needed to distinguish between elements with the same basic name but different versions. See 2.2.5.6.2 for including an element more than once in a bank-named collection.
UP';'NUM8ER
SPERRY UNIVAC 1100 SIHies Executive Volume 3 System Procl9ss0rs
4144.31
L
_._---
, - - -I
UPD.:' LEVELI
2-7~AGE
Common blocks may be named on IN directives, but must not have an associated implicit or explicit filename because they are imbedded within other elements. For inclusion of a common block in the collection, see 2.2.4.6.
For the order of elements explicitly and impl!icitly included in the collection, see 2.2.3.2 and 2.2.5.7.
For either format FRSTIN may be used instead of IN, as the first element inclusion statement in a .bank-implied collection or after a BANK or SEG statement. When used it specifies that the first named
element is to be positioned at the beginning of the segment it is collected in.
Examples:
1 . 2.
3.
IN SEG
IN SEG
IN
FILEA.,FILEB.
ADAY1 FILEB.BB, .CC,DD
BDAY2
COLLECTOR*F8 ( 1 ) . I NIT /REV
1. All relocatable elements in FILEA end FILEB are included in the collection.
2. Elements BB and CC from file FILEB and element DD, whose filename is not indicated, are included in the collection of segment ADA Y 1.
3. The relocatable element INIT version HEV in file COLLECTOR*F8 F-cycle 1 is included in the collection of segment BDAY2.
2.2.2.2. Element Exclusion (NOT) Purpose:
Names the elements which are to be excluded from the entire collection.
All parameters in the NOT directive are optional. If a" parameters are omitted, NOT TPF$. is assumed.
Format:
NOT name-1,name-2, ... ,name-n Parameters:
name
Description:
Specifies the element, with or without filename, or file to be excluded from the collection. If the version name or filename is omitted, all elements of 1the specified name are bypassed.
When ,a" elements of a file are to be excluded, the entire file may be designated for exclusion with a NOT directive. The effect of NOTing a whole file is to make the file inaccessible for searching as a library file. A period must follow the filename to ensure that it is not interpreted as an element namiB.
If a tHename with no following element names appear in a NOT directive, elements within the named file can be explicitly included during the coUection. This is useful only with TPF$ and SYS$*RLlB$, since these are the only two files which are normally automatically searched.
4144.31
UP-NUMBER
Examples:
SPERRY UNIVAC 1100 Series Executive Volume 3 System Processors
1. @MAP , I A, A
NOT CWW,LRR
2. MAP, I A, A
IN FILEA.
NOT FILEA.CL, .AB
3 . @MAP , I A, A IN FL1.,f-L2.
NOT FL1.XXX, .XX2,FL2.CAT, .CAT2 4 . @MAP , I A, A
IN FIL1.
NOT SYS$*RL I B$ . NOT TPF$.
A
UPDATE LEVEL
2-8
PAGE
1. All elements named CWW and LRR are excluded from the collection; all other relocatable elements in TPFS are included.
2. All elements named CL and AB from FILEA, are excluded from the collection; all other relocatable elements in the file FILEA are included.
3. Elements XXX and XX2 from file FL 1 and elements CAT and CAT2 from file FL2 a're excluded from the collection; all other relocatable elements from files FL 1 and FL2 are included.
4. Relocatable elements from SYSS*RLlB$ and TPF$ are excluded from the collection. All elements from FIL 1 are included.
2.2.2.3. File Search Sequencing (LIB) Purpose:
Specifies which files (libraries) are to be searched by the Collector prior to searching the System Relocatable Library SYS$*RLlB$. Each file named on a LIB statement must have an entry point table created by the @PREP FURPUR function (see 4.2.11), if the file contains elements which will be implicitly included to satisfy external references.
All parameters in the LIB directive are optional, except filename-1.
Format:
LIB filename-1,filename-2, .. .filename-n
LIB filename-1 (bankname/$lcs,bankname/$lcs, ... ).filename-2 ...
LIB (bankname/$Ics,bankname/$Ics ... )
LIB filename-1 ( ),filename-2( " ... filename-n( ) Parameters:
filename
bankname
Specifies the files to be searched, named in the order in which they are to be searched. Those files containing elements not explicitly included in the collection but which define symbols required to satisfy external references, must have been prepped (@PREP).
Specifies a bank in which implicitly included elements are to be placed.
UP-NUMBER
5PERRY UNIVAC 1100 SElries Executive Volume 3 System Processors
, 4144.31
L
- - - -
-A
UPDATE LEVEL
2-9
PAGE
$Ics
( )
Description:
Specifies which location counters of the implicit elements go to correspondin!g banks.
The parameters specified on the last preceding LIB (bankname/$Ics, ... ) directive are to be applied for the filename specified.
The second, third and fourth formats abOVE! and parameters bankname and $Ics are used only in bank--named collections (see 2.2.5.7).
The specified files are searched for elements named for inclusion from that file or from an unspecified file, and when all explicitly included elements have been found, or searched for and not found, the files are searched in the order in which they appear in the directive for satisfying external references.
A file may be searched more than once if the filename appears more than once on a LIB directive.
A file is searched only once for each time it is specified on a LIB directive.
When several LIB directives are given they have a cumulative effect. For example, assume file A has external referEmces satisfied by elements in file B which in turn have external references satisfied by elements in file A. If the elements are not explicitly included by IN directives, the following directive is necessary to ensure the inclusion of all referenced elements:
LIB AB,A
RLiB may be used instead of LIB in all formats. However, the effect in format 3 is lost. Any element from a file on such a statement is marked as being from SYS$*RLlB$. The result is that these elements will not be dumped by @PMD unless the 'L' option is used with the PMD request, nor will they be traced by SNOOPY.
ExamlPles:
1. LIB 2. LIB
CHR1
USE1,USE2,USE3,USE1
1. File CHR'I is searched after TPF$, and before files USE 1, USE2, USE3, USE 1 (a second time) and the System Relocatab!e Library.
2. Files USE 1, USE2, USE3, and USE 1 (a second time) are searched in that order after TPF$ and CHR 1 and before the System Relocatable Library is searched.
2.2.2.4. External Definition Retention (OEF) Purpose:
Specifies entries in the ENTRY$ table. This table contains all the locations and names of the external definitions retained after the collection of the absolute or relocatable element.
NOTE
The DEF and REF (see 2.2.2.5) directives are primarily useful in the collection of reentrant processors and with R option collections.
4144.31 UP-NUMBER
SPERRY UNIVAC 1100 Series Executive Volume 3 System Processors
All parameters in the DEF directive are optional.
Format:
DEF def-1,def-2,def-3, ... ,def-n Parameters:
A UPDATE LEVEL
defs Specifies the external definitions to be retained.
Description:
2-10 PAGE
The DEF directive causes the Collector to build an external definition table and a COMMN$ table which defines the common blocks in a program. The user can address the two tables by the Collector-defined names ENTRY$ and COMMN$, respectively (see 2.2.8). The COMMN$ table will also be built if the DEF directive is present with no parameters.
If the R option was given on the @ MAP control statement, the DEF directive must be used to specify those externalized labels which are to remain externalized in the merged relocatable output.
If no element explicitly named in an IN directive contains the named external definition, a search of the library files (see 2.2.2.3) is made to find an element in which the symbol is defined.
Example:
DEF SIN,COS,SORT
The listed external definitions, SIN, COS, and SORT and their locations are retained after the collection in the ENTRY$ table of the resultant element.
2.2.2.5. External Reference Retention (REF) Purpose:
Creates a list of external references to be retained by the resulting absolute or relocatable element.
No attempt is made to satisfy any references made to names indicated on REF directives. The table of retained external references is program addressable by the Collector-defined name XREF$.
All parameters in the REF directive are optional.
Format:
REF ref-1,ref-2,ref-3, ... ,ref-n Parameters:
refs Specifies the external references to be retained.
Description:
If an external definition that is identical to a REF name is encountered, a diagnostic is printed and the external definition is ignored.
The REF directive causes the Collector to build the COMMN$ table in the same manner as the DEF directive (see 2.2.2.4).
SPERRY UNIVAC 1100 Serlles Executive
I
AI
2-11Volume
3
System Process_o_rs~~~~~~~~~~~~_U_PD_A_T_E_U_V_EL~~~._P_AG_E~~_~~~Example:
REF VALUE1,VALUE2,SUBROUTINE4
The listed external references (VALUE 1, VALUlE2, and SUBROUTINE4) are retained after the collection in the XREF$ table of the resultant element. Any references to these symbols are satisfied with the address of word 3 of the appropriate entry in the XREF$ table (see 2.2.8).
2.2.2.6. Starting Address Redefinition (ENT) Purpose:
ProvidtBs the user with the capability of oVEHriding any start addresses provided by relocatable elements. Upon program initialization, control is transferred to the absolute address of the named symbol.
1F0rmat
EINT name Paraml;}ter:
name
Description:
Must be an externally defined symbol which is the newly defined starting point.
In the absence of an ENT directive, the first start address encountered in processing the relocatable elements becomes the program start address. The start address must be contained in the main segment as this is the only segment initially loaded at execution time. In a bank-named collection, the start address must be contained in the main segment of an initially-based bank (see 2.2.5.2).
Example:
EI'JT GGYP
Control is passed to the absolute address of the symbol GGYP in the main segment.
2.2.2.7. External Reference Definition (EOU) Purpose:
ProvidHs the means to assign, during the collection, a value to an undefined symbol or to change the value of an external definition.
All parameters in the EQU directive are optional except name-1/value-1.
Format:
EOU name-l Ivalue-l ,name-2/value-2,oo.,name-n/value-n
4144.31
UP-NUMBER
Parameters:
names
SPERRY UNIVAC 1100 Series Executive Volume 3 System Processors
Specifies the symbols to be defined
I 2-12
PAGE
values The values to be assigned to the preceding name parameters.
Description:
The assigned values may be as follows:
octal integers (indicated by a leading zero) decimal integers
a symbol
a symbol with an offset (for example, BOB
+
4)Any symbol used in the value parameter must be externally defined in one of the elements specified for inclusion in the collection. If an external definition which duplicates an EOU name is found, the external. definition is ignored and a diagnostic is printed. In bank-named collections, only global symbols may be used on the EOU directive (see 2.2.5.6.2).
Examples:
1. EOU 2. EOU 3. EOU
JOE/0200 AL/BOB+4
JOE/0200, ABE/SAM+10 1. The external reference JOE is defined as 0200.
2. The external reference AL is defined as the value BOB
+
410,3. The external references JOE and ABE are defined as 0200 and SAM