The REPLACE statement is used to replace or delete external symbols.
The external symbol can name a section, an entry point, an external
reference, or a pseudoregister.
One section can be replaced with another. All references within
the input module to the old section are changed to the new section.
Any external references to the old section from other modules are
unresolved unless changed.
A section can be deleted. The section name is deleted from the
external symbol dictionary. External references from other modules
to a deleted section also remain unresolved. If there are references
to any address within a deleted section, the section name in changed
to an external reference.
If the first symbol in the REPLACE statement refers to a symbol
that is not a section or common area, the results will be the same
as if a CHANGE statement were coded. The first symbol is replaced
by the second symbol. The first symbol is deleted when the second
symbol is omitted.
The syntax of the REPLACE statement is:
REPLACE [-IMMED,]externalsymbol1[(externalsymbol2)]…
- -IMMED
- causes REPLACE to operate against the modules that have already
been included in the module being built rather than against the next
input module .
- externalsymbol1, externalsymbol2
- Names an external symbol to be replaced or deleted. If you only
specify externalsymbol1, the external symbol
is deleted. If you specify externalsymbol2 in
parentheses following externalsymbol1, externalsymbol1 is replaced by externalsymbol2.
You can delete or replace any number of external symbols with one
REPLACE statement.
Placement: The REPLACE statement must immediately
precede either the module containing the external symbol to be replaced
or deleted, or the INCLUDE statement specifying the module. The scope
of the REPLACE statement is across the immediately following program
or object module.
Note: - If during automatic library call the replacement symbol is still
undefined in the module, the binder attempts to resolve the reference
from SYSLIB.
- When a section containing unresolved external references is deleted,
the binder removes these references from the ESDs.
- When using the binder, if no INCLUDE statement follows the REPLACE
statement, the request is ignored.
- If the REPLACE statement appears in a module included from a data
set in an automatic call library, it will be ignored if it is not
followed by a module from the same data set.
- Restrictions apply whenever both CHANGE and REPLACE operations
are performed on the same included program or object module. You might
need to delete one of several sections and at the same time rename
references to that section (all within the scope of the same INCLUDE)
to some other external symbol. To change more than one entry name
within the original section to a single new external symbol, you must
specifically include the section that resolves the new external symbol,
prior to the change operation.
- When using a REPLACE statement to replace or delete a named common
area, the common area must be defined in the first program or object
module following the REPLACE statement.
- When deleting an entry name, if there are any references to it
within the same input module, the entry name is changed to an external
reference.
- The -IMMED option is not allowed during autocall processing.
- externalsymbol1 may be specified using
the syntax $PRIVxxxxxx (where xxxxxx is 6 hexadecimal digits) to represent
an unnamed symbol. To determine the appropriate value to use it, it
is necessary to rebind the single module and produce a MAP and/or
XREF. The $PRIVxxxxxx symbol names from the binder output can be used
in REPLACE statements on the very next bind of the single module. Names
$PRIV000000 - $PRIV00000F are reserved by the Binder and may not be
used as externalsymbol1.