Name Operation Operand
COM -- DEFINE BLANK COMMON CONTROL SECTION
The COM assembler instruction identifies and reserves a common area of storage that may be referred to by independent assemblies that have been linked and loaded for execution as one overall program•
Appearances of a COM statement after the initial one indicate the resumption of the blank common control section•
When several assemblies are loaded, each designating a common control section, the amount of storage reserved is equal to the longest common control section• The format is:
Name Operation Operand
COM Blank
A se-quence symbol or blank
The common area may be broken up into subfields through use of the DS and DC assembler instructions. Names of subfields are defined relative to the beginning of the common section, as in the DSECT control section.
It is necessary to establish addressabillty relative to a named statement within COM since the COM statement itself cannot have a name. In the following example, addressability to the common area of storage is established relative to the named statement XYZ.
Name Operation Operand
XYZ PDQ
L USING
I, =A(XYZ) XYZ,I MVC
COM DS DS
PDQ(16),=4C'ABCD'
16F 16C
No instructions or constants appearing in a common control section are assembled. Data can only be placed in a common control section through
3-17
,J
execution of the program. A blank common control section may include any assembler language instructions.
If the assignment of common storage is done in the same manner by each independent assembly, reference to a location in common by any assembly results in the same location being referenced. When the blank common control section is assembled, the initial value of the location counter is
set to zero.
SYMBOLIC LINKAGES
Symbols may be defined in one module and referred to in another, thus effectlng symbolic linkages between independently assembled program sections. The linkages can be effected only if the assembler is able to provide information about the linkage symbols to the linkage editor, which resolves these linkage references at load time. The assembler places the necessary information in the external symbol dictionary on the basis of the linkage symbols identified by e.g., the ENTRY and EXTRN instructions. Note that these symbolic linkages are described as linkages between independent modules; more specifically, they are linkages between independently
assembled control sections.
In the module where the linkage symbol is defined (i.e., used as a name), it must also be identified to the assembler by means of the ENTRY
assembler instruction unless the symbol is the name of a CSECT or START statement. It is identified as a symbol that names an entry point, which means that another module may use that symbol in order to effect a branch operation or a data reference. The assembler places this information in the control dictionary.
Similarly, the module that uses a symbol defined in some other module must identify it by the EXTRN or WXTRN assembler instruction. It is identified as an externally defined symbol (i.e., defined in another module) that is used to effect linkage to the point of definition. The assembler places this information in the external symbol dictionary.
Another way to obtain symbolic linkages, is by using the V-type address constant. The subsection "Data Definition Instructions" in Section 5 contains the details pertinent to writing a V-type address constant. It is sufficient here to note that this constant may be considered an indirect linkage point. It is created from an externally defined symbol, but that symbol does not have to be identified by an EXTRN or WXTRN statement. The V-type address constant may be used for external branch references (i.e., for effectlng branches to other programs). It may not be used for external data references (i.e., for referring to data in other programs).
ENTRY -- IDENTIFY ENTRY-POINT SYMBOL
The ENTRY instruction identifies linkage symbols that are defined in one source module and referenced by other modules.
A se-quence symbol or b iank
ENTRY One or more
reloca-table symbols, separated by commas, that also appear as state-ment names
A source module may contain a maximum of i00 ENTRY symbols. ENTRY symbols which are not defined (not appearing as statement names), although invalid, will also count towards this maximum of i00 ENTRY symbols.
The symbols in the ENTRY operand field may be used as operands by other programs. An ENTRY statement operand may not contain a symbol defined in a dummy section or in a blank common control section. The following example identifies the statements named SINE and COSINE as entry points to the program.
Name Operation Operand
ENTRY SINE,COSINE
Note: Labels of START and CSECT statements are automatically treated as entry points to a module. Thus they need not be identified by ENTRY statements.
EXTRN -- IDENTIFY EXTERNAL SYMBOL
The EXTRN instruction identifies linkage symbols used by one source module but identified in another module. Each external symbol must be
identified. This includes symbols that refer to control section names.
The format of the EXTRN statement is:
Name Operation Operand
"A se- EXTRN
quence symbol or blank
One or more reloca-table symbols, separated by commas
3-19
The symbols in the operand field may not appear as the name of statements in the module where the EXTRN statement is. The length attribute of an external symbol is i.
The following example identifies three external symbols. They are used as operands in the module where they appear, but they are defined in some other module.
Name
Operation Operand
EXTRN EXTRN
RATEBL,PAYCALC WITHCALC
An example that employs the EXTRN instruction appears subsequently under "Addressing External Control Sections." °
Note i: A V-type address constant does not have to be identified by an EXTRN statement.
Note 2: When external symbols are used in an expression they may not be paired. Each external symbol must be considered as having a unique relocatability attribute.
Addressin_ External Control Sections
A common way for a program to link to an external control section is to:
I. Create a V-type address constant with the name of the external symbol.
, Load the constant into a general register and branch to the control section via the register.
For example, to link to the control section named SINE, the following coding might be used:
Name Operation Operand MAINPROG
BEGIN
VCON
CSECT BALR USING
L BALR
DC END
2,0
*,2
3,VCON 1,3
V(SINE)
BEGIN
An external symbol naming data may be referred to as follows:
i. Identify the external symbol with the EXTRN instruction, and create an address constant from the symbol.
2. Load the constant into a general register, and use the register for base addressing.
For example, to add to register 3 the contents of a data area named RATETBL, which is in another control section, the following coding might be used:
Name Operation Operand
MAINPROG BEGIN
RATEADDR
CSECT BALR USING
EXTRN
L USING A
DC END
2,0
*,2
RATETBL
4,RATEADDR RATETBL,4
3,RATETBL
A(RATETBL) BEGIN
3-21
The total number of control sections, dummy sections, external symbols and external dummy sections must not exceed 255. Certain constants may cause a symbol to be counted twice: external symbols in V-type address constants (unless they are explicitly defined in an EXTRN or WXTRN statement), and external dummy sections implicitly defined by Q-type address constants and corresponding DSECT statements. (EXTRN and WXTRN statements are discussed in this section; V-type constants in Section 5 under the DC assembler instruction.)
WXTRN -- IDENTIFY WEAK EXTERNAL SYMBOL
The WXTRN statement has the same format as the EXTRN statement. It is used to identify weak external references. The only difference between a weak (WXTRN) and a strong (EXTRN or V-type constant) external reference is that the automatic library call mechanism of the linkage editor or loader is not effective for symbols that are identified in WXTRN statements.
The automatic library call mechanism searches the call library for any unresolved external references. If it finds any of these references, it includes the module where the reference occurs in the load module produced by the linkage editor or loader. Refer to OS Loader and Linkage Editor for a full description of the automatic library call mechanism.
The format of the WXTRN instruction is:
Name Operation Operand
WXTRN A
se-quence symbol or blank
One or more reloca-table symbols, separated by
COrneas
Note: If a V-type address constant is identified by a WXTRN
instruction, the automatic library call mechanism is suppressed for it.