ASASYMBM — Substitute text for symbols

Description

Note: ASASYMBM is a linkable system service.

Use the ASASYMBM service to substitute text for system symbols. You can explicitly call ASASYMBM to substitute text for system symbols in application or vendor programs. The system calls ASASYMBM automatically for system symbols that are specified in:

Dynamic allocations
Job control language (JCL)
Parmlib members
System commands.

The caller of ASASYMBM provides an input string to be substituted (a pattern), an output buffer, and optionally a table of system symbols and associated values. ASASYMBM substitutes values for the system symbols that it finds in the input string. ASASYMBM places the results of the substitution in the specified output buffer.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state with PSW key 8-15
Dispatchable unit mode:	Task
Cross memory mode:	PASN=HASN=SASN
AMODE:	24- or 31-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	Must be in the primary address space.

Programming requirements

To build the parameter area required by ASASYMBM, you must include the ASASYMBP mapping macro (see z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/).
Before calling ASASYMBM, the caller must provide the following in the ASASYMBP mapping macro:
- An input string to be substituted (a pattern) and its length
- An output buffer and its length
- An area in which to place the return code from ASASYMBM.
The caller can optionally provide a symbol table and a timestamp.
To determine the return code from ASASYMBM, the caller must examine the fullword pointed to by the SYMBPRETURNCODE@ field in the ASASYMBP data area.
To determine the length of the output from ASASYMBM, the caller must examine the fullword pointed to by SYMBPTARGETLENGTH@ in the ASASYMBP mapping macro. The output itself is in the area provided by the caller, which is pointed to by SYMBPTARGET@ in ASASYMBP.

For more information about providing input to ASASYMBM in the ASASYMBP mapping macro, see the section on using the symbol substitution service in z/OS MVS Programming: Assembler Services Guide.

Restrictions

The caller cannot have any enabled, unlocked task (EUT) FRRs established.

Input register information

Before linking to ASASYMBM, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:

Register: Contents
13: Address of a standard 72-byte save area in the primary address space

Before linking to ASASYMBM, the caller does not have to place any information into any access register (AR).

Output register information

When control returns to the caller, the GPRs contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

When control returns to the caller, the ARs contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

This service is not appropriate for use in a performance-sensitive area.

Syntax

Use the following form of the LINK macro to invoke the ASASYMBM service:


>>-label-------------------------------------------------------->

>--+-LINK--EP--=--ASASYMBM--,--MF--=--(--E--,--parmarea--)--------------------------------------+-><
   '-LINKX--EP--=--ASASYMBM--,--MF--=--(--E--,--parmarea--)--+--------------------------------+-'   
                                                             '-,--SF--=--(--E--,--parmlist--)-'

Note: As an alternative to using LINK or LINKX, callers in 31-bit AMODE can also:

Issue the MVS™ LOAD macro to load the ASASYMBM service and obtain its entry point address.
Issue the CALL macro to call the service. Specify MF=(E,your_parmlist) on the call.

Parameters

The parameters are explained as follows:

label: The name on the macro invocation.
LINK
LINKX: Names the system service that is to be used for linkage.
EP=ASASYMBM: Specifies the entry point name for the ASASYMBM service.
,MF=(E,parmarea): Specifies the area that you built, mapped by the ASASYMBP macro, that contains the parameter area and optionally points to the system symbol table ASASYMBM is to use.
,SF=(E,parmlist): For use with LINKX when your program is reentrant. Before you call LINKX with this parameter, define parmlist using the LIST form of LINKX.

Return and reason codes

When the ASASYMBM service returns control to your program, the area pointed to by the SYMBPRETURNCODE@ field of the caller-provided ASASYMBP area contains a return code.

Hexadecimal Return Code	Meaning and Action
00	Meaning: The ASASYMBM request completed successfully. The system performed the requested substitution. Action: None required.
04	Meaning: Warning. The caller indicated that the system is to assign a substring of a substitution text to a system symbol. One of the following occurred: The start position in the substring is either beyond the length of the substitution text or zero. The length of the substring is either beyond the length of the substitution text or zero. The length of the substring exceeds the length of the substitution text beyond the specified start position. When the program called ASASYMBM, the SYMBTWARNSUBSTRINGS flag in the ASASYMBP mapping macro indicated that ASASYMBM was to return this return code. The system continues with symbolic substitution. Action: None required. If necessary, see the section on errors in substringing in z/OS MVS Initialization and Tuning Reference. Ensure that the symbols in the input pattern conform to the rules for substringing.
08	Meaning: Warning. The specified buffer is too small to contain all the substitution text. Action: Specify a larger target buffer, or continue processing, using the value returned in the fullword pointed to by the SYMBPTARGETLENGTH@ field to determine how much data was placed into the target buffer.
0C	Meaning: Warning. The length of the text to be substituted in place of a system symbol is null. When the program called ASASYMBM, the SYMBTCHECKNULLSUBTEXT flag in the ASASYMBP mapping macro indicated that ASASYMBM was to return this return code. Action: None required.
10	Meaning: Warning. The system did not find any symbols for which it was to substitute text. The substitution process completed normally. When the program called ASASYMBM, the SYMBTWARNNOSUB flag in the ASASYMBP mapping macro indicated that ASASYMBM was to return this return code. Action: None required.

Examples of calls to ASASYMBM

For examples of calls to ASASYMBM, see the section that describes the symbol substitution service in z/OS MVS Programming: Assembler Services Guide.