IEFSSI — Dynamically control a subsystem

Description

Use the IEFSSI macro to dynamically control a subsystem in any of the following ways:
  • Adding and defining a subsystem to the system
  • Activating a subsystem so that its function routines can process function requests
  • Defining a set of optional subsystem characteristics
  • Deactivating a subsystem
  • Swapping the current SSVT with a new SSVT
  • Storing subsystem-defined data for a subsystem
  • Retrieving subsystem-defined data for a subsystem that was previously stored with the put request
  • Query information for all subsystems defined to the SSI
The requests for the macro are:

The IEFSSI macro (REQUEST=QUERY only) is also described in z/OS MVS Programming: Assembler Services Reference ABE-HSP.

For ease of use, the standard form of the macro is shown for each IEFSSI request. The requests are described on the following pages along with the:
  • Standard form syntax diagram
  • Description of the parameters
The following information is described once at the beginning of the IEFSSI macro description:
  • Environment
  • Programming requirements
  • Restrictions
  • Input register information
  • Output register information
  • Performance implications
Following the descriptions of the standard forms of all requests are:
  • Abend codes
  • Return and reason codes
  • Examples

The REQUEST=ADD, REQUEST=ACTIVATE, REQUEST=OPTIONS, REQUEST=DEACTIVATE, REQUEST=SWAP, REQUEST=PUT, REQUEST=GET and REQUEST=QUERY parameters, which designate the services of the IEFSSI macro, are mutually exclusive. You can select only one.

For information about using dynamic subsystem services, see z/OS MVS Using the Subsystem Interface. This topic also includes information about related macros IEFSSVT and IEFSSVTI.

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: For the QUERY request, problem state with any PSW key. The REQUEST=ADD, REQUEST=ACTIVATE, REQUEST=OPTIONS, REQUEST=DEACTIVATE, REQUEST=SWAP, REQUEST=PUT, and REQUEST=GET parameters require one of the following:
  • Supervisor state
  • Any system PSW key
  • PSW key mask (PKM) allowing key 0-7
  • APF authorization
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.
  • For the REQUEST=QUERY parameter, the caller must include the IEFJSQRY macro to map the REQUEST=QUERY output.
  • For the REQUEST=ACTIVATE and REQUEST=SWAP parameters, the subsystem must have created at least one SSI-managed vector table. An SSI-managed vector table is a vector table created with the IEFSSVT REQUEST=CREATE macro.

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=ADD parameter of IEFSSI

The IEFSSI macro with the ADD parameter dynamically adds and defines a subsystem to the system.

Syntax for REQUEST=ADD

The syntax of the IEFSSI REQUEST=ADD 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 address in register (2) - (12).
   
,REQUEST=ADD  
   
   ,CONSNAME=consname consname: RS-type address or address in register (2) - (12).
   ,CONSNAME=0 Default: CONSNAME=0
   
   ,INITRTN=initrtn initrtn: RS-type address or address in register (2) - (12).
   ,INITRTN=NO_INITRTN Default: INITRTN=NO_INITRTN
   
   ,INITPARM=initparm initparm: RS-type address or address in register (2) - (12).
   ,INITPARM=NO_INITPARM Default: INITPARM=NO_INITPARM
   
   ,INITPLEN=initplen initplen: RS-type address or address in register (2) - (12).
   
   ,PLISTVER=IMPLIED_VERSION  
   ,PLISTVER=MAX Default: IMPLIED_VERSION
   ,PLISTVER=plistver plistver: 1
   
   ,RETCODE=retcode retcode: RS-type address or address in register (2) - (12) of fullword output variable
   
   ,RSNCODE=rsncode rsncode: RS-type address or address in 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=ADD

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.

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

When selecting subsystem names, note the following:
  • If you specify a subsystem name with the characters '*' and '?', the DISPLAY SSI command or the IEFSSI REQUEST=QUERY service specifying that subsystem name may return information about subsystems other than this one. The '*' and '?' are treated as wildcard characters for these services.
  • If you specify a subsystem name of '!PRI', the DISPLAY SSI command or the IEFSSI REQUEST=QUERY service specifying that subsystem name returns information about the primary subsystem, even though there is a subsystem named '!PRI'.
Note: If you need to start the subsystem, its name must meet the requirements for the name of a started task. See z/OS MVS JCL Reference for more information.
,REQUEST=ADD
A parameter that specifies that a subsystem is to be dynamically defined.
,CONSNAME=consname
,CONSNAME=0
An optional 8-character parameter that specifies the name (or an address in a register) of a console to which any messages the SSI issues as part of the initialization process are written. If an INITRTN parameter is specified, the console name is passed to the routine named on INITRTN.

The default is 0. If the default parameter is used, the SSI issues messages to the consoles that are receiving the INTIDS attribute.

,INITRTN=initrtn
,INITRTN=NO_INITRTN
An optional 8-character parameter that specifies the name (or an address in a register) of a subsystem initialization routine.

A subsystem initialization routine name that is less than 8 characters long must be padded to the right with blanks. The default is NO_INITRTN.

,INITPARM=initparm
,INITPARM=NO_INITPARM
An optional parameter that specifies the name (or address in a register) of a parameter string that is passed to the subsystem initialization routine. This parameter string can be up to 60 characters long. The INITPLEN parameter specifies the actual length of the passed parameter.

The INITPARM parameter is applicable only if you specify the INITRTN parameter.

,INITPLEN=initplen
A required parameter that contains the length of the parameter string to be passed to the subsystem initialization routine. You must specify this 4-byte parameter if you specify the INITPARM parameter.

INITPLEN can be from 1 to 60 characters long inclusive. If the length is greater than 60, the subsystem is defined but the subsystem initialization routine is not invoked.

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

REQUEST=ACTIVATE parameter of IEFSSI

The IEFSSI macro with the ACTIVATE parameter dynamically activates a subsystem so that its function routines are available to process function requests.

Syntax for REQUEST=ACTIVATE

The syntax of the IEFSSI REQUEST=ACTIVATE 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 address in register (2) - (12).
   
,REQUEST=ACTIVATE  
   
   ,INTOKEN=intoken intoken: RS-type address or address in register (2) - (12).
   ,INTOKEN=NO_INPUT_TOKEN Default: INTOKEN=NO_INPUT_TOKEN
   
   ,PLISTVER=IMPLIED_VERSION  
   ,PLISTVER=MAX Default: IMPLIED_VERSION
   ,PLISTVER=plistver plistver: 1
   
   ,RETCODE=retcode retcode: RS-type address or address in register (2) - (12) of fullword output variable
   
   ,RSNCODE=rsncode rsncode: RS-type address or address in 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=ACTIVATE

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.

,REQUEST=ACTIVATE
A parameter that specifies a subsystem is to be dynamically activated so that its function routines are available to process function requests. Before invoking the IEFSSI macro and issuing the REQUEST=ACTIVATE parameter, the subsystem must be defined to the system, and you must ensure that an SSVT has been built using the IEFSSVT macro with the REQUEST=CREATE parameter.

The ACTIVATE request may also be used to reactivate a subsystem that has been deactivated. To reactivate a subsystem, you can either use the same SSVT as you used to deactivate the subsystem or you can use a new SSVT.

,INTOKEN=intoken
,INTOKEN=NO_INPUT_TOKEN
An optional 32-bit parameter that specifies the name (or an address in a register) of an input token that represents the SSVT that is used when activating the subsystem. The function routines associated with the SSVT are made available for processing requests.
The token must be one that was returned by one of the following:
  • IEFSSVT REQUEST=CREATE
  • IEFSSI REQUEST=DEACTIVATE
  • IEFSSI REQUEST=SWAP
If the INTOKEN parameter is omitted, an SSVT is chosen as follows:
  • The most recently active SSI-managed vector table
  • The last SSI-managed vector table created, if no SSI-managed vector table has been activated

The default is NO_INPUT_TOKEN.

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

REQUEST=OPTIONS parameter of IEFSSI

The IEFSSI macro with the OPTIONS parameter defines a set of optional subsystem characteristics.

Syntax for REQUEST=OPTIONS

The syntax of the IEFSSI REQUEST=OPTIONS 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 address in register (2) - (12) of fullword output variable
   
,REQUEST=OPTIONS  
   
   ,COMMAND=NO Default: COMMAND=NO
   ,COMMAND=YES  
   
   ,REQDSUB=MSTR Default: REQDSUB=MSTR
   ,REQDSUB=PRI  
   
   ,PLISTVER=IMPLIED_VERSION  
   ,PLISTVER=MAX Default: IMPLIED_VERSION
   ,PLISTVER=plistver plistver: 1
   
   ,RETCODE=retcode retcode: RS-type address or address in register (2) - (12) of fullword output variable
   
   ,RSNCODE=rsncode rsncode: RS-type address or address in 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=OPTIONS

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.

,REQUEST=OPTIONS
A parameter that specifies the definition of a set of optional subsystem characteristics. You can set the following subsystem options using this macro:
  • Whether the subsystem responds to SETSSI commands
  • Whether you want the invoking subsystem to start under the MSTR or primary subsystem
IEFSSI REQUEST=OPTIONS is the only way you can specify these optional characteristics.

If you invoke the OPTIONS parameter multiple times for a single subsystem, the most recent invocation determines the resulting characteristics. The defaults listed for the COMMAND and REQDSUB parameters below apply to the first invocation.

If a parameter is not specified on a subsequent invocation, the corresponding subsystem characteristic retains the value that was assigned by the last invocation that specified the parameter.

,COMMAND=NO
,COMMAND=YES
An optional parameter that specifies the whether the subsystem responds to the following commands:
  • SETSSI ACTIVATE
  • SETSSI DEACTIVATE

The meanings are:

NO
The subsystem does not allow SETSSI commands. No is the default.
YES
The subsystem allows SETSSI commands.
You need to specify COMMAND=YES only if the subsystem can tolerate the processing associated with each of the SETSSI commands listed above.
,REQDSUB=MSTR
,REQDSUB=PRI
An optional parameter that specifies whether a START subsystem command causes the subsystem to start under either the MSTR subsystem or the primary subsystem (JES).

When the procedure name on the START command matches a defined subsystem name, the procedure being started is recognized as a subsystem. If the START command does not specify the SUB parameter, the subsystem is started under the control of the subsystem identified by the REQDSUB parameter.

The meanings for REQDSUB=MSTR and REQDSUB=PRI are:
  • REQDSUB=MSTR — The subsystem specified does not require the services of the primary subsystem and starts under the MSTR subsystem. MSTR is the default.
  • REQDSUB=PRI — The subsystem specified requires the services of the primary subsystem and must start under its control. If a START subsystem command is issued before the primary subsystem is available, the processing that the subsystem was doing in response to the START command fails.
,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.

REQUEST=DEACTIVATE parameter of IEFSSI

The IEFSSI macro with the DEACTIVATE parameter deactivates a subsystem.

Syntax for REQUEST=DEACTIVATE

The syntax of the IEFSSI REQUEST=DEACTIVATE 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 address in register (2) - (12).
   
,REQUEST=DEACTIVATE  
   
   ,OUTTOKEN=outtoken outtoken: RS-type address or address in register (2) - (12).
   
   ,PLISTVER=IMPLIED_VERSION  
   ,PLISTVER=MAX Default: IMPLIED_VERSION
   ,PLISTVER=plistver plistver: 1
   
   ,RETCODE=retcode retcode: RS-type address or address in register (2) - (12) of fullword output variable
   
   ,RSNCODE=rsncode rsncode: RS-type address or address in 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=DEACTIVATE

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.

,REQUEST=DEACTIVATE
A parameter that specifies that a subsystem is to be deactivated. This stops any new function requests from being passed to the subsystem function routines.

A subsystem can be reactivated after being deactivated by using the same or a different SSVT.

,OUTTOKEN=outtoken
An optional 32-bit parameter that specifies the name (or an address in a register) of an output token. This is where the token that represents the deactivated SSVT is returned.

This token may be used in a subsequent ACTIVATE request to reactivate the subsystem using the same SSVT.

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

REQUEST=SWAP parameter of IEFSSI

The IEFSSI macro with the SWAP parameter replaces the SSVT that is currently being used to route function requests with a new one.

Syntax for REQUEST=SWAP

The syntax of the IEFSSI REQUEST=SWAP 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 address in register (2) - (12).
   
,REQUEST=SWAP  
   
   ,INTOKEN=intoken intoken: RS-type address or address in register (2) - (12).
   ,INTOKEN=NO_INPUT_TOKEN Default: INTOKEN=NO_INPUT_TOKEN
   
   ,OUTTOKEN=outtoken outtoken: RS-type address or address in register (2) - (12).
   
   ,PLISTVER=IMPLIED_VERSION  
   ,PLISTVER=MAX Default: IMPLIED_VERSION
   ,PLISTVER=plistver plistver: 1
   
   ,RETCODE=retcode retcode: RS-type address or address in register (2) - (12) of fullword output variable
   
   ,RSNCODE=rsncode rsncode: RS-type address or address in 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=SWAP

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.

,REQUEST=SWAP
A parameter that specifies the replacement of the SSVT currently being used to route function requests with a new SSVT. The current SSVT is deactivated and the new SSVT is (re)activated. The subsystem remains continuously active during this process.

When you use a SWAP request to switch SSVTs, it is possible for you to use a subsequent SWAP request to switch the SSVTs again, which restores the old function routines.

A SWAP request that targets an inactive subsystem is treated as an ACTIVATE request, but receives the IEFSSI_WARNING (4) return code.

,INTOKEN=intoken
,INTOKEN=NO_INPUT_TOKEN
An optional 32-bit parameter that specifies the name (or an address in a register) of an input token that represents the SSVT that is used when activating the subsystem. The function routines associated with the SSVT are made available for processing requests.
The token must be one that was returned by either the:
  • IEFSSVT REQUEST=CREATE
  • IEFSSI REQUEST=DEACTIVATE
  • IEFSSI REQUEST=SWAP
If the INTOKEN parameter is omitted, an SSVT is chosen as follows:
  • The most recently active SSI-managed vector table
  • The last SSI-managed vector table created, if no SSI-managed vector table has been activated

The default is NO_INPUT_TOKEN.

,OUTTOKEN=outtoken
An optional 32-bit parameter that specifies the name (or an address in a register) of an output token. This is where the token that represents the deactivated SSVT is returned.

This token may be used in a subsequent SWAP request to reactivate the subsystem using the same SSVT.

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

REQUEST=PUT parameter of IEFSSI

The IEFSSI macro with the PUT parameter stores subsystem-defined data for the subsystem.

Syntax for REQUEST=PUT

The syntax of the IEFSSI REQUEST=PUT 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 address in register (2) - (12).
   
,REQUEST=PUT  
   
,SUBDATA1=subdata1 subdata1: RS-type address or address in register (2) - (12). of a 4-character input area
,SUBDATA2=subdata2 subdata2: RS-type address or address in register (2) - (12). of a 4-character input area
   
   ,PLISTVER=IMPLIED_VERSION  
   ,PLISTVER=MAX Default: IMPLIED_VERSION
   ,PLISTVER=plistver plistver: 1
   
   ,RETCODE=retcode retcode: RS-type address or address in register (2) - (12) of fullword output variable.
   
   ,RSNCODE=rsncode rsncode: RS-type address or address in 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=PUT

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.

,REQUEST=PUT
A parameter that specifies the storage of subsystem-defined data for the subsystem. Two non-contiguous 4-byte fields are available for the subsystem data. One of these fields is typically used to anchor subsystem specific control blocks.

You must specify at least one of the following parameters:

SUBDATA1=subdata1
The name (or address in a register) of a 4-character input area that holds the first 4-bytes of subsystem specific information.
SUBDATA2=subdata2
The name (or address in a register) of a 4-character input area that holds the second 4-bytes of subsystem specific information.
,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.

REQUEST=GET parameter of IEFSSI

The IEFSSI macro with the GET parameter retrieves subsystem-defined data previously stored using the IEFSSI REQUEST=PUT request.

Syntax for REQUEST=GET

The syntax of the IEFSSI REQUEST=GET 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 address in register (2) - (12).
   
,REQUEST=GET  
   
,SUBDATA1=subdata1 subdata1: RS-type address or address in register (2) - (12) of a 4-character output area.
,SUBDATA2=subdata2 subdata2: RS-type address or address in register (2) - (12) of a 4-character output area.
   
   ,PLISTVER=IMPLIED_VERSION  
   ,PLISTVER=MAX Default: IMPLIED_VERSION
   ,PLISTVER=plistver plistver: 1
   
   ,RETCODE=retcode retcode: RS-type address or address in register (2) - (12) of fullword output variable.
   
   ,RSNCODE=rsncode rsncode: RS-type address or address in 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=GET

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.

,REQUEST=GET
A parameter that specifies the retrieval of subsystem-defined data previously stored using the IEFSSI REQUEST=PUT request. Two non-contiguous 4-byte fields are available for the subsystem data.

You must specify at least one of the following parameters:

SUBDATA1=subdata1
The name (or address in a register) of a 4-character output area that holds the first 4-bytes of subsystem specific information identified by the SUBDATA1 parameter on a previous IEFSSI REQUEST=PUT request.
SUBDATA2=subdata2
The name (or address in a register) of a 4-character output area that holds the second 4-bytes of subsystem specific information identified by the SUBDATA2 parameter on a previous IEFSSI REQUEST=PUT request.
,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.

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 address in register (2) - (12).
   
,REQUEST=QUERY  
   
,WORKAREA=workarea workarea: RS-type address or address in register (2) - (12) of an output area.
   
   ,WORKASP=workasp workasp: RS-type address or address in 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 address in register (2) - (12). of fullword output variable
   
   ,RSNCODE=rsncode rsncode: RS-type address or address in 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:
  • ADD — A subsystem has been added to the system
  • ACTIVATE — A subsystem has been activated
  • OPTIONS — A set of optional subsystem characteristics has been defined
  • DEACTIVATE — A subsystem has been deactivated
  • SWAP — The current SSVT has been swapped with a new SSVT
  • PUT — Subsystem-defined data has been stored
  • GET — Subsystem-defined data has been retrieved
  • QUERY — Information for all subsystems defined to the SSI has been queried

Action: None.
04 (04) 300 (12C) Equate Symbol: IEFSSI_DEACT_INACTIVE

Meaning: The subsystem was already inactive. This is a DEACTIVATE request error.

Action: None.
04 (04) 301 (12D) Equate Symbol: IEFSSI_DEACT_OUT_VT_NOT_SSI

Meaning: The subsystem is deactivated, however a previously active vector table was not SSI-managed. OUTTOKEN value is 0. This is a DEACTIVATE request error.

Action: None.
04 (04) 500 (1F4) Equate Symbol: IEFSSI_SWAP_INACTIVE

Meaning: The subsystem was initially active. OUTTOKEN value is 0. This is a SWAP request error.

Action: None.
04 (04) 501 (1F5) Equate Symbol: IEFSSI_SWAP_OUT_VT_NOT_SSI

Meaning: The swap is complete, however the previously active vector table was not SSI-managed. OUTTOKEN value is 0. This is a SWAP request error.

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) 04 (004) Equate Symbol: IEFSSI_NON_DYNAMIC

Meaning: The subsystem is not dynamic.

Action: ReIPL the system and define the target subsystem with either the IEFSSI macro, the SETSSI command, or the keyword format IEFSSNxx parmlib member entry. Note that once a subsystem has been defined, it cannot be deleted or defined again as dynamic.
08 (08) 08 (008) Equate Symbol: IEFSSI_BAD_VT_TOKEN

Meaning: The SSVT token does not correspond to a valid SSVT table.

Action: Correct the token. The token must be one that was returned by either the IEFSSVT REQUEST=CREATE macro, the IEFSSI REQUEST=DEACTIVATE macro, or the IEFSSI REQUEST=SWAP macro.
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.
08 (08) 16 (010) Equate Symbol: IEFSSVT_INIT_PARMS

Meaning: The initialization routine parameter string is too long.

Action: Correct the parameter string so that it is no longer than 60 characters.
12 (0C) 100 (064) Equate Symbol: IEFSSI_DUPLICATE_SUBSYSTEM

Meaning: The subsystem already exists. This is an ADD request error.

Action: Do not perform the ADD request if the existing subsystem is one you want. If the existing subsystem is not the one you want, select another name for the new subsystem, which does not conflict with the name of any existing subsystem name.

You can use the IEFSSI REQUEST=QUERY macro to find all existing names.
12 (0C) 101 (065) Equate Symbol: IEFSSI_INITRTN_NOT_FOUND
Meaning: A usable copy of this initialization routine could not be found. This is an ADD request error. For example:
  • The module was not found.
  • The module was found, but was not APF-authorized.

Action: Correct the initialization routine name or make sure it is present in either LINKLIB or LPALIB, and is APF authorized.
12 (0C) 102 (066) Equate Symbol: IEFSSI_INITRTN_ABEND

Meaning: The initialization routine ended abnormally. This is an ADD request error.

Action: Check the dump produced by the abend and correct the problem with the initialization routine.
12 (0C) 103 (067) Equate Symbol: IEFSSI_ADD_STORAGE

Meaning: Unable to obtain storage for the subsystem definition. This is an ADD request error.

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.
12 (0C) 200 (0C8) Equate Symbol: IEFSSI_SUBSYSTEM_ACTIVE

Meaning: The subsystem is already active. This is an ACTIVATE request error.

Action: None.
12 (0C) 201 (0C9) Equate Symbol: IEFSSI_ACT_NO_ELIGIBLE_VT

Meaning: The SSVT is not specified and a valid default is not available. This is an ACTIVATE request error.

Action: Provide an SSI-managed SSVT using the IEFSSVT REQUEST=CREATE macro.
12 (0C) 500 (1F4) Equate Symbol: IEFSSI_SWAP_NO_ELIGIBLE_VT

Meaning: The SSVT is not specified and a valid default is not available. This is a SWAP request error.

Action: Provide an SSI-managed SSVT using the IEFSSVT REQUEST=CREATE macro.
12 (0C) 502 (1F6) Equate Symbol: IEFSSI_SWAP_ALREADY_ACTIVE

Meaning: The SSVT that is to be made active (specified by the INTOKEN field) is already active. This is a SWAP request error.

Action: None.
12 (0C) 900 (384) Equate Symbol: IEFSSI_QUERY_STORAGE

Meaning: Unable to obtain storage for an output of the QUERY request. This a QUERY request error.

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.
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 1

Submit a request to add subsystem FRED, call the initialization routine and route all initialization messages to the FREDCONS console 
         IEFSSI REQUEST=ADD,SUBNAME=SNAME,INITRTN=INITPGM,             X
               INITPARM=IPARMS,INITPLEN=5,CONSNAME=ICONSOLE,           X
               RETCODE=RETURN_CODE,RSNCODE=REASON_CODE
⋮
SNAME    DC    CL4'FRED'
INITPGM  DC    CL8'FREDPGM '
IPARMS   DC    CL60'HELLO'
ICONSOLE DC    CL8'FREDCONS'
⋮
WORKAREA DSECT 0F
RETURN_CODE DS F
REASON_CODE DS F
WORKLEN  EQU   *-WORKAREA

Example 2

Activate subsystem FRED using the SSVT identified by the SSVTTOK token. Assume that the SSVTTOK token was returned by a previous invocation of the IEFSSVT REQUEST=CREATE macro. 
         IEFSSI REQUEST=ACTIVATE,SUBNAME=SNAME,INTOKEN=SSVTTOK,        X
               RETCODE=RETURN_CODE,RSNCODE=REASON_CODE
⋮

Example 3

Inform the system that the subsystem responds to SETSSI commands and requires the services of the primary subsystem when starting. 
         IEFSSI REQUEST=OPTIONS,SUBNAME=SNAME,COMMAND=YES,REQDSUB=PRI, X
              RETCODE=RETURN_CODE,RSNCODE=REASON_CODE

Example 4

Deactivate a subsystem and return the token of the outgoing SSVT. 
         IEFSSI REQUEST=DEACTIVATE,SUBNAME=SNAME,OUTTOKEN=SSVTTOK,     X
               RETCODE=RETURN_CODE,RSNCODE=REASON_CODE

Example 5

Replace the current set of function routines being used by the subsystem with a new set of function routines. NEWTOK is a token previously returned by the IEFSSVT REQUEST=CREATE service. NEWTOK identifies the incoming SSVT. 
         IEFSSI REQUEST=SWAP,SUBNAME=SNAME,INTOKEN=NEWTOK,             X
               OUTTOKEN=OLDTOK,                                        X
               RETCODE=RETURN_CODE,RSNCODE=REASON_CODE

Example 6

Store the address of the FREDCB subsystem control block for later retrieval by the subsystem function routines. 
         LA    5,FREDCB    Get address of subsystem control block
         ST    5,DATA1     Store address
         LA    4,DATA1     Get address of field containing pointer
         IEFSSI REQUEST=PUT,SUBNAME=SNAME,SUBDATA1=(4),                X
               RETCODE=RETURN_CODE,RSNCODE=REASON_CODE
Note: When using the register notation (4), the register contains the address of the data to be stored, not the data itself. The data stored in this case is the address of the FREDCB control block.

Example 7

Retrieve subsystem-defined data that was previously stored using the IEFSSI REQUEST=PUT service and place the retrieved data at the location whose address is contained in register 5. 
         IEFSSI REQUEST=GET,SUBNAME=SNAME,SUBDATA1=(5),                X
               RETCODE=RETURN_CODE,RSNCODE=REASON_CODE

Example 8

Obtain subsystem information for all subsystems whose name begins with 'JES' and free the storage obtained by the SSI. 
         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