MSG 1 TEXT 'EXAMPLE' MESSAGE HEADING
4.5 DIRECTIVES THAT PROVIDE LINKAGE BETWEEN PROGRAMS
This category consists of two directives that enable program modules to be assembled separately and integrated into an executable program. One directive places one or more symbols defined in the module into the object code, making them available for linking. The other directive places symbols used in the module but defined in another module into the object code, allowing them to be linked. The directives are:
• External Definition
• External Reference
• Secondary Reference
• Force Load
4.5.1 EXTERNAL DEFINITION DEF Syntax definition:
[<label>]b ... DEFb ... <symbol>[,<symbol>] ... b ... [<comment>]
DEF makes one or more symbols available to other programs for reference. The use of the label field is optional. When a label is used, the current value of the location counter is assigned to the label. The operation field contains DEF. The operand field contains one or more symbols, separated by commas, to be defined in the program being assembled. The comment field is optional.
The following example shows a DEF directive:
DEF ENTER,ANS
The directive causes the assembler to include symbols ENTER and ANS in the object code so that these symbols are available to other programs. When the DEF directive does not precede the
~---
~ 943441-9701 source statements that contain the symbols, the assembler identifies the symbols as multiply defined symbols.4.5.2 EXTERNAL REFERENCE REF Syntax definition:
[<label>]b ... REFb ... <symbol>L<symbol>] ... b ... [<comment>]
REF provides access to one or more symbols defined in other programs. The use of the label field is optional. When a label is used, the current value of the location counter is assigned to the label.
The operation field contains REF. The operand field contains one or more symbols, separated by commas, to be used in the operand field of a subsequent source statement. The comment field is optional.
The following example shows a REF directive:
REF ARG I ,ARG2
The directive causes the assembler to include symbols ARG I and ARG2 in the object code so that the corresponding addresses may be obtained from other programs. The Prototyping System Assem-bler, PX9ASM, requires that a REF directive precede the first use of a REF'd symbol.
If a sumbol is listed in the REF statement then a corresponding symbol must also be present in a DEF statement in another source module. If a one-to-one matching of symbols does not occur then an error occurs at Link Edit time. The system will generate a summary list of all "unresolved references" .
NOTE
If a symbol in the operand field of an REF directive is the first operand of a DATA directive, the assembler places the value of the symbol at location 0 of the routine. If that routine is loaded at absolute location 0, the symbol will not be linked correctly.
Use of the symbol at other locations will be correctly linked.
4.5.3 SECONDARY EXTERNAL REFERENCE SREF Syntax definition:
[<label>]'b ... SREF ... <symbol>,[<Symbol>] ... 'b ... [<comment>]
SREF provides access to one or more symbols defined in other programs. The use of the label field is optional. When a label is used, the current value of the location counter is assigned to the label.
The operation field contains SREF. The operand field contains one or more symbols, separated by commas, to be used in the operand field of a subsequent source statement. The comment field is optional.
The following example shows a REF directive:
SREF ARGI,ARG2
The directive causes the Link Editor to include symbols ARG I and ARG2 in the object code so that the corresponding addresses may be obtained from other programs.
SREF unlike REF does not require a symbol to have a corresponding symbol listed in a DEF state-ment of another source module .. But the symbol will be an unresolved reference.
~---
~ 943441-9701 NOTESREF is supported by SDSMAC and TXMIRA only.
4.5.4 FORCE LOAD LOAD Syntax definition:
[<J.abel>]t> ... LOADt> ... <Symbol> [,<symbol>] ... t> ... [<comment>]
The LOAD directive is like a REF, but the symbol does not need to be used in the module con-taining the LOAD. The symbol used in the LOAD must be DEFed in some other module. LOADs are used with SREFs. If a one-to-one matching of LOAD-SREF pairs and DEF symbols does not occur, then unresolved references will occur during link editing.
The following example shows the use of the SREF and the LOAD directives:
A1 A2 A3
LOAD C, D LOAD C LOAD E, F
I I
B
SREF C, D, E, F DATA C
DATA D DATA E DATA F
C
I
D E FDEF C DEF D DEF E DEF F
Modules Al uses a branch table in module B to get one of the modules C, D, E, or F. Module Al knows which of the modules C, D, E, and F it will need. Module B has SREF for C, D, E, and F.
Module C has a DEF for C. Module D has a DEF for D. Module E has a DEF for E. Module F has a DEF for F. Module Al has a LOAD for one or more of modules C, D, E, and F as needed.
The LOAD and SREF directives permit module B to be written to handle the most involved case and still be linked together without unneeded modules, since Al only has LOAD directives for the modules it needs.
When a link edit is performed, automatic symbol resolution will pull in the modules appearing in a LOAD directive. (See Section 2.5.1 of the Model 990 Computer Link Editor Reference Manual, part number 949617-9701 for more details on automatic symbol resolution.)