IEFSJSYM — JCL symbol service

The requirements for the caller are:

This service cannot be used reliably until the job has begun execution. Invoking the service before the first job step has started executing is not supported (for example, in exits such as IEFUJI that are invoked before the first job step has started executing).

When using the returned symbol values, the value of the symbol returned will be the last value set prior to or within the current job step (EXEC PGM=statement).

There are no input register requirements for issuing the IEFSJSYM macro.

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.

None.

The syntax of the IEFSJSYM macro with REQUEST= is written as follows:

The parameters are explained as follows:

name

An optional symbol, starting in column 1, that is the name on the IEFSJSYM macro invocation. The name must conform to the rules for an ordinary assembler language symbol.

,DIAGDATA=diagdata

A required output parameter that specifies an area for service to return additional information. To code this parameter, specify an RS-type address, or address in register (2)-(12), of a 16-character field.

,MF=S

,MF=(L,list addr)

,MF=(L,list addr,attr)

,MF=(L,list addr,0D)

,MF=(E,list addr)

,MF=(E,list addr,COMPLETE)

,MF=(E,list addr,NOCHECK)

,MF=(M,list addr)

,MF=(M,list addr,COMPLETE)

,MF=(M,list addr,NOCHECK)

An optional input parameter that specifies the macro form.

Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default value.

Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be coded with the list form of the macro.

Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.

Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.

IBM recommends that you use the modify and execute forms of IEFSJSYM in the following order:

1. Use IEFSJSYM ...MF=(M,list-addr,COMPLETE) to specify appropriate parameters, including all required parameters.
2. Use IEFSJSYM ... MF=(M,list-addr,NOCHECK) to specify the parameters that you want to change.
3. Use IEFSJSYM ...MF=(E,list-addr,NOCHECK) to execute the macro.

,list addr

Specifies the name of a storage area to contain the parameters. For MF=S, MF=E, and MF=M, this can be an RS-type address or an address in register (1)-(12).

,attr

Specifies an optional 1-60 character input string which forces boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.

,COMPLETE

Specifies for the system to check for required parameters, and to supply default values for omitted optional parameters.

,NOCHECK

Specifies for the system to not check for required parameters, and to not supply default values for omitted optional parameters.

,NUMENTRIES=numentries

A required input parameter for REQUEST=GETBYNAME that specifies the number of entries in the CHAR(16) array pointed to by SYMLISTARRAY. To code this parameter, specify an RS-type address or address in register (2)-(12) of a halfword field, or specify a literal decimal value.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=0

Specifies the version of the macro and determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using this parameter, specify it on all macro forms used for a request and with the same value on all of the macro forms. To code this parameter, specify IMPLIED_VERSION, MAX, or 0, as follows:

IMPLIED_VERSION

Specifies the lowest version that allows all of the specified parameters to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.

MAX

Specifies to maximize the parameter list size. Because the supported maximum size can grow from release to release, the amount of storage that your program requires can also change. If your system can tolerate a size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all of the parameters that you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.

0

Specifies to use the currently available parameters.

REQUEST=GETALL

REQUEST=GETBYNAME

A required parameter that specifies the JCL symbols to get. Use REQUEST=GETALL to get all symbol values that were exported. Use REQUEST=GETBYNAME to get specific named symbol values, given an array of symbol names.

,RETCODE=retcode

An optional output parameter into which the return code is copied from GPR 15. If you specify 15, GPR15, REG15, or R15 (within or without parentheses), the value will be left in GPR 15. To code this parameter, specify an RS-type address of a fullword field, or register (2)-(12) or (15), (GPR15), (REG15), or (R15).

,RSNCODE=rsncode

An optional output parameter into which the reason code is copied from GPR 0. If you specify 0, 00, GPR0, GPR00, REG0, REG00, or R0 (within or without parentheses), the value will be left in GPR 0. To code this parameter, specify an RS-type address of a fullword field, or register (0) or (2)-(12), (00), (GPR0), (GPR00), (REG0), (REG00), or (R0).

,SYMBAREALEN=symbarealen

A required input parameter that specifies the length of the SYMBAREA that is provided by the caller. To code this parameter, specify an RS-type address, or address in register (2)-(12) of a fullword field, or specify a literal decimal value.

,SYMLISTARRAY=symlistarray

A required input parameter for REQUEST=GETBYNAME that contains an array of up to 16 character entries, each of which contains a symbol name for which the symbol value is to be returned. Symbol names must be left-justified in the array entry, and if shorter than 16 characters, padded on the right with blank spaces.

A wildcard character (asterisk (*) to match 0 or more characters in the symbol name, or question mark (?) to match exactly one character) can used to specify a generic symbol name. Symbol names should not contain a leading ampersand character (&) or any special character other than a wildcard character.

IEFSJSYM returns a null value (SYDESYMVALUELEN=0) for entries that do not contain valid JCL symbol name; in addition, a return code of IEFSJSYMRC_Warn and a reason code of IEFSJSYMRsn_SymbolNameNotProcessed are set. To code this parameter, specify an RS-type address, or address in register (2)-(12), of a character field.