REPLACE statement

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.