IEFSSI — Dynamically query a subsystem

Description

Use the IEFSSI macro to dynamically query a subsystem. The REQUEST=QUERY parameter allows an application to query the following information for all subsystems defined to the SSI:

The subsystem name
If the subsystem is dynamic or not dynamic
If the subsystem is the primary subsystem
If the subsystem is active or inactive
If the subsystem is dynamic, whether it accepts or rejects the SETSSI command
If the subsystem is active, which function codes it supports.
The number of vector tables associated with the subsystem, with a maximum of two vector tables.
The following information for each associated vector table:
- If the vector table is managed by the SSI. A vector table managed by the SSI is a vector table created with the IEFSSVT REQUEST=CREATE macro.
- A locator. This locator is a token if the vector table is is managed by the SSI and is an address if the vector table is not managed by the SSI.
- If the vector table is active
- The function codes supported by the vector table

This information represents a snapshot of the subsystems defined to the SSI when you process the query request.

To obtain information about the primary subsystem without knowing its name, use the query request and specify a subsystem name of '!PRI'.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	For the QUERY request, problem state with any PSW key.
Dispatchable unit mode:	Task
Cross memory mode:	PASN=HASN=SASN
AMODE:	24-bit or 31-bit
ASC mode:	Primary or Access register (AR)
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	Control parameters must be in the primary address space.

Programming requirements

Include the CVT and IEFJESCT mapping macros in your program.
Include the IEFJSRC mapping macro in your program. This macro defines the dynamic SSI return and reason codes.
Include the IEFJSQRY macro to map the REQUEST=QUERY output.

Restrictions

The caller must not have established an EUT FRR.

Input register information

Before issuing the IEFSSI macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Output register information

When control returns to the caller, the GPRs contain:

Register: Contents
0: Reason code
1: Used as a work register by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code

When control returns to the caller, the ARs contain:

Register: Contents
0-1: Used as a work register by the system
2-13: Unchanged
14-15: Used as a work register 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

None.

REQUEST=QUERY parameter of IEFSSI

The IEFSSI macro with the QUERY parameter requests information about subsystems defined to the system.

Syntax for REQUEST=QUERY

The syntax of the IEFSSI REQUEST=QUERY macro is written as follows:

Syntax	Description

`name`	`name`: symbol. Begin `name` in column 1.

␢	One or more blanks must precede IEFSSI.

IEFSSI

␢	One or more blanks must follow IEFSSI.

SUBNAME=`subname`	`subname`: RS-type address or register (2) - (12).

,REQUEST=QUERY

,WORKAREA=`workarea`	`workarea`: RS-type address or register (2) - (12) of an output area.

,WORKASP=`workasp`	`workasp`: RS-type address or register (2) - (12) of an input area.

,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX	Default: IMPLIED_VERSION
,PLISTVER=`plistver`	`plistver`: 1

,RETCODE=`retcode`	`retcode`: RS-type address or register (2) - (12). of fullword output variable

,RSNCODE=`rsncode`	`rsncode`: RS-type address or register (2) - (12). of fullword output variable

,COM=`com`	`com`: comment string
,COM=`NULL`	Default: COM=NULL

,MF=S	Default: 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)

Parameters for REQUEST=QUERY

The parameters are explained as follows:

SUBNAME=subname

A required parameter that specifies the field (or an address in a register) containing the 4-character subsystem name. It must be the name of a subsystem that has been previously defined to the system using SSI services.

This field must be padded to the right with blanks or nulls if it is less than 4 characters long.

For the REQUEST=QUERY parameter, the subsystem name may contain the wildcard characters '*' and '?' to request information about multiple subsystems. The meanings for the wildcard characters are:

*: Matches 0 or more characters.
Use a SUBNAME parameter value of '*' to indicate that information is to be returned for all subsystems.
?: Matches exactly 1 character

Use a SUBNAME parameter value of '!PRI' to indicate that information is to be returned for the primary subsystem.

,REQUEST=QUERY

A parameter that specifies the request to obtain information about a currently defined subsystem named in the SUBNAME parameter.

The output from IEFSSI REQUEST=QUERY is mapped by the IEFJSQRY macro. Subsystems are listed in broadcast order, that is, the order in which they receive broadcast SSI requests.

,WORKAREA=workarea

A required parameter that specifies a name (or register containing the address) of a pointer output field that contains the address of the subsystem information returned by the QUERY request.

The output area is mapped by the IEFJSQRY macro. The JQRYLEN field contains the length of the output area.

,WORKASP=workasp

An optional parameter that specifies a name (or register containing the address) of a one-byte input field that specifies the subpool that the SSI uses to obtain a work area for the returned subsystem information. The caller is responsible for freeing this work area.

IBM® recommends that you use a job-related or task-related subpool. This allows the system to free the associated storage when the job or task ends, if the caller does not free the returned area.

If WORKASP is not specified, the caller's subpool zero is used. Storage for the query information is obtained above 16 megabytes. AMODE 24 callers must switch into AMODE 31 to address this storage. Unauthorized callers may request storage only in the following unauthorized subpools:

0-127
131
132

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=plistver

Specifies the version of the macro. PLISTVER 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 PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:

IMPLIED_VERSION: The lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
MAX: The largest size parameter list currently possible. This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the 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 the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.
1: The currently available parameters.

To code, specify in this input parameter one of the following:

IMPLIED_VERSION
MAX
A decimal value of 1

,RETCODE=retcode

An optional 4-byte parameter that specifies the name of an output field (or a register) where the system places the return code. The return code is copied from general purpose register 15.

,RSNCODE=rsncode

An optional 4-byte parameter that specifies the name of an output field (or a register) where the system places the reason code. The reason code is copied from general purpose register 0.

,COM=com

,COM=NULL

An optional parameter that specifies the character input that appears in the block comment before the macro invocation. Use it to make comments about the macro invocation. The comment must be enclosed in quotation marks if it contains any lower case characters. The default is NULL.

,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)

Use MF=S to specify the standard form of the IEFSSI macro, which builds an in-line parameter list and generates the macro invocation to transfer control to the service.

Use MF=L to specify the list form of the IEFSSI 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. No other parameters may be coded with the list form of the macro.

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

,list addr: A required parameter that specifies the name of a storage area for the parameter list.
,attr: An optional 1- to 60-character input string that contains any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE: An optional parameter that specifies that the system checks for required parameters and supply defaults for omitted optional parameters. This is the default parameter.

ABEND codes

An invocation of the IEFSSI macro may result in an abend code X'8C5'. See z/OS MVS System Codes for an explanation of this abend code.

Return and reason codes

When the IEFSSI macro returns control to your program, GPR 15 (and retcode, if you coded RETCODE) contains a return code. When the value in GPR 15 is not 0, GPR 0 (and rsncode if you coded RSNCODE) contains the reason code.

The IEFJSRC mapping macro provides equate symbols for the return and reason codes. The equate symbols associated with each Return Code are:

Decimal (Hex): Equate Symbols
00 (00): IEFSSI_SUCCESS
04 (04): IEFSSI_WARNING
08 (08): IEFSSI_INVALID_PARAMETERS
12 (0C): IEFSSI_REQUEST_FAIL
20 (14): IEFSSI_SYSTEM_ERROR
24 (18): IEFSSI_UNAVAILABLE

The following table contains return and reason codes, the equate symbols associated with each reason code and the meaning and suggested action for each return and reason code.

Table 1. Return and Reason Codes for the IEFSSI Macro
Return Code decimal (hex)	Reason Code decimal (hex)	Meaning and Action
00 (00)	00 (00)	Equate Symbol: IEFSSI_FUNCTIONS_COMPLETE Meaning: The request completed successfully. The result depends on the request: QUERY — Information for all subsystems defined to the SSI has been queried Action: None.
04 (04)	900 (384)	Equate Symbol: IEFSSI_QUERY_INCOMPLETE Meaning: The data returned by the QUERY request may be incomplete. This is a QUERY request error. Action: Check the JQRY_INCOMPLETE flag for each subsystem that was queried.
08 (08)	00 (000)	Equate Symbol: IEFSSI_SUBSYSTEM_UNKNOWN Meaning: The subsystem is not defined to the SSI. Action: Correct the subsystem name or define a subsystem with either the IEFSSI macro or the SETSSI command.
08 (08)	12 (00C)	Equate Symbol: IEFSSI_INVALID_NAME Meaning: The subsystem name or the routine name contains characters that are not valid. Action: Correct the subsystem name by removing the characters that are not valid.
12 (0C)	900 (384)	Equate Symbol: IEFSSI_QUERY_STORAGE Meaning: Unable to obtain storage for an output of the QUERY request. Action: Check the current use of the system storage to determine why storage was not available. Retry the request later in case storage has become available. See z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXG for more information on the IEFSSI macro.
20 (14)	—	Equate Symbol: IEFSSI_SYSTEM_ERROR Meaning: System error Action: Investigate the following possible causes: Inability to obtain a system resource Abnormal task termination Obtain the system dump, if any, and contact the IBM support center.
24 (18)	—	Equate Symbol: IEFSSI_UNAVAILABLE Meaning: The IEFSSI macro has been invoked too early during system initialization. Action: Delay the invocation of the IEFSSI macro to a later point in the IPL.

Example

Obtain subsystem information for any subsystem whose name begins with 'JES' and free the storage returned by the system.

         IEFSSI REQUEST=QUERY,SUBNAME=SNAME,                           X
               WORKAREA=WAREA,                                         X
               RETCODE=RETURN_CODE,RSNCODE=REASON_CODE
⋮
         L      R5,WAREA
         USING  JQRY_HEADER,R5
         L      R0,JQRYLEN
         STORAGE RELEASE,LENGTH=(0),ADDR=(R5)
⋮
SNAME    DC    CL4'JES*'
WAREA    DS    A
         IEFJSQRY