IEFSSVT — Create a subsystem vector table

Description

Use the IEFSSVT macro to:
  • Create subsystem vector tables (SSVTs).
  • Modify the subsystem response to function requests by:
    • Disabling existing function codes
    • Enabling new function codes
    • Exchange function routines for a supported function code

The IEFSSVT macro allows users to specify function routines by address or name rather than requiring the subsystem interface (SSI) to load the routines. This is useful if the subsystem wants to load its function routines into global storage, but does not want the routines to be deleted if the address space ends. In this case, the subsystem can perform a load-to-address, rather than a standard load, and pass the addresses to the IEFSSVT macro.

The requests for the macro are:
For ease of use, the standard form of the macro is shown for each IEFSSVT 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 IEFSSVT 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=CREATE, REQUEST=DISABLE, REQUEST=ENABLE, and REQUEST=EXCHANGE parameters 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 IEFSSVTI and IEFSSI.

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: One of the following:
  • Supervisor state
  • Any system 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

Before invoking IEFSSVT, you must invoke IEFSSVTI to build a table of function routines and function codes as input to IEFSSVT.

Also:
  • 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.

Restrictions

The services that IEFSSVT provides are available only to dynamic subsystems, which are those subsystems that have been defined to the SSI in one of the following ways:
  • Processing the keyword format of the IEFSSNxx parmlib member during IPL
  • Issuing the IEFSSI macro
  • Issuing the SETSSI system command.

Input register information

Before issuing the IEFSSVT 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=CREATE parameter of IEFSSVT

The IEFSSVT macro with the CREATE parameter builds the SSVT. An SSVT built with the IEFSSVT REQUEST=CREATE is referred to as an SSI-managed vector table. Only SSI-managed SSVTs can take advantage of the dynamic SSI services. See z/OS MVS Using the Subsystem Interface for more information about dynamic SSI services.

Syntax for REQUEST=CREATE

The syntax of the IEFSSVT REQUEST=CREATE macro is written as follows:

Syntax Description
   
   name name: symbol. Begin name in column 1.
   
␢ One or more blanks must precede IEFSSVT.
   
IEFSSVT  
   
␢ One or more blanks must follow IEFSSVT.
   
SUBNAME=subname  
   
,REQUEST=CREATE  
   
,SSVTDATA=ssvtdata ssvtdata: RS-type address
   
,OUTTOKEN=outtoken outtoken: RS-type address or address in register (2) - (12).
   
   ,SUBPOOL=subpool subpool:. RS-type address or address in register (2) - (12).
   ,SUBPOOL=241 Default: SUBPOOL=241
   
,MAXENTRIES=maxentries maxentries: RS-type address or address in register (2) - (12).
   
   ,LOADTOGLOBAL=NO Default: LOADTOGLOBAL=NO
   ,LOADTOGLOBAL=YES  
   
   ,ERRFUNCT=errfunct errfunct: RS-type address or address in register (2) - (12).
   
   ,PLISTVER=IMPLIED_VERSION Default: IMPLIED_VERSION
   ,PLISTVER=MAX  
   ,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  
   ,MF=(L,list addr list addr: symbol.
   ,MF=(L,list addr,attr) attr: 1- to 60-character input string.
   ,MF=(L,list addr,0D) Default: 0D
   ,MF=(E,list addr) list addr: RS-type address or address in register (1) - (12) of a storage area.
   ,MF=(E,list addr,COMPLETE) Default: COMPLETE
   ,MF=(E,list addr,NOCHECK)  
   

Parameters for REQUEST=CREATE

The parameters are explained as follows:

SUBNAME=subname
A required 4-character parameter that specifies the field (or an address in a register) containing the subsystem name. It must be the name of a subsystem that has been previously defined to the system using dynamic SSI services. See z/OS MVS Using the Subsystem Interface for more information about dynamic SSI services.

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

,REQUEST=CREATE
A parameter that specifies an SSVT is to be built and initialized.
,SSVTDATA=ssvtdata
A required parameter that specifies the name of the function routine input table that associates supported SSVT function codes with function routines. Use the IEFSSVTI macro to build the table. Use this field to contain the name specified by the IEFSSVTI SSVTDATA parameter.
,OUTTOKEN=outtoken
A required 32-bit parameter that specifies the name (or an address in a register) of an output token used to identify the SSVT.
,SUBPOOL=subpool
,SUBPOOL=241
An optional byte parameter that specifies the name (or an address in a register) of an input field that contains the subpool number in which the SSVT is to be built. The subpool must represent common storage. The default is 241.
,MAXENTRIES=maxentries
A required halfword parameter that specifies the name (or an address in a register) of an input field that defines the maximum number of function routine entries that the SSVT can contain. The maximum number must be:
  • Greater than or equal to 1 and less than or equal to 255
  • Greater than or equal to the number of function routines defined in the input table created with the IEFSSVTI macro.
  • The maximum number of function routine entries the calling subsystem requires for the SSVT.
Note: Consider that the value for MAXENTRIES should provide for additional function routines that can be defined through the SET or EXCHANGE parameters of the IEFSSVT service.
,LOADTOGLOBAL=NO
,LOADTOGLOBAL=YES
An optional parameter that specifies that the function routines are to be loaded to global storage. Use this parameter when the function routines:
  • Are specified by name in the function routine input table that the IEFSSVTI macro created
  • Do not reside in the link pack area.

This parameter is ignored if the input function routines are specified by address.

The meanings are:

NO
Indicates that a load-to-global is not necessary for the function routines. No is the default.
YES
Indicates that a load-to-global is necessary for the function routines. The SSI issues a LOAD for each named function routine with the following parameters:
  • EOM=YES
  • LSEARCH=NO
  • GLOBAL=(YES,P)
,ERRFUNCT=errfunct
An optional 8-character parameter that specifies the name (or an address in a register) of an output field that receives the function routine name being processed when an error occurred. Check this output field if you get return code IEFSSVT_LOAD_ERROR (decimal 16) from the IEFSSVT macro.
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 a name (or register) of an output field 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 a name (or register) of an output field 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 IEFSSVT 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 IEFSSVT 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 the MF=E together with the list form of the macro for applications that require reentrant code. The execute form of the IEFSSVT 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=DISABLE parameter of IEFSSVT

The IEFSSVT macro with the DISABLE parameter disables supported function codes.

Syntax for REQUEST=DISABLE

The syntax of the IEFSSVT REQUEST=DISABLE macro is written as follows:

Syntax Description
   
   name name: symbol. Begin name in column 1.
   
␢ One or more blanks must precede IEFSSVT.
   
IEFSSVT  
   
␢ One or more blanks must follow IEFSSVT.
   
SUBNAME=subname  
   
,REQUEST=DISABLE  
   
,SSVTDATA=ssvtdata ssvtdata: RS-type address
   
   ,INTOKEN=intoken intoken: RS-type address or address in register (2) - (12).
   ,INTOKEN=NULL Default: INTOKEN=NULL
   
   ,PLISTVER=IMPLIED_VERSION Default: IMPLIED_VERSION
   ,PLISTVER=MAX  
   ,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  
   ,MF=(L,list addr list addr: symbol.
   ,MF=(L,list addr,attr) attr: 1- to 60-character input string.
   ,MF=(L,list addr,0D) Default: 0D
   ,MF=(E,list addr) list addr: RS-type address or address in register (1) - (12) of a storage area.
   ,MF=(E,list addr,COMPLETE) Default: COMPLETE
   ,MF=(E,list addr,NOCHECK)  
   

Parameters for REQUEST=DISABLE

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 less than 4 characters long.

,REQUEST=DISABLE
A parameter that specifies that you want to disable function codes.
,SSVTDATA=ssvtdata
A required parameter that specifies the name of the function routine input table that identifies the function codes that you want to disable. The IEFSSVTI macro has built the table. This field contains the name specified by the IEFSSVTI SSVTDATA parameter.

For the disable request, the system uses only the function code information. The function routine names or addresses in the input table are ignored.

,INTOKEN=intoken
,INTOKEN=NULL
An optional 32-bit parameter that specifies the name (or an address in a register) of an input token that represents the target SSVT (OUTTOKEN from REQUEST=CREATE). The default is NULL.
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 a name (or register) of an output field 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 a name (or register) of an output field 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 IEFSSVT 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 IEFSSVT 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 the MF=E together with the list form of the macro for applications that require reentrant code. The execute form of the IEFSSVT 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=ENABLE parameter of IEFSSVT

The IEFSSVT macro with the ENABLE parameter activates new function codes or reactivates previously disabled function codes. You can enable new function codes only if the SSVT has available function routine slots to contain any new function routines. An ENABLE request may not need to specify new function routines, if the routine that supports a new code is already supporting a previously enabled code.

Syntax for REQUEST=ENABLE

The syntax of the IEFSSVT REQUEST=ENABLE macro is written as follows:

Syntax Description
   
   name name: symbol. Begin name in column 1.
   
␢ One or more blanks must precede IEFSSVT.
   
IEFSSVT  
   
␢ One or more blanks must follow IEFSSVT.
   
SUBNAME=subname  
   
,REQUEST=ENABLE  
   
,SSVTDATA=ssvtdata ssvtdata: RS-type address
   
   ,INTOKEN=intoken intoken: RS-type address or address in register (2) - (12).
   ,INTOKEN=NULL Default: INTOKEN=NULL
   
   ,LOADTOGLOBAL=NO Default: LOADTOGLOBAL=NO
   ,LOADTOGLOBAL=YES  
   
   ,ERRFUNCT=errfunct errfunct: RS-type address or address in register (2) - (12).
   
   ,PLISTVER=IMPLIED_VERSION Default: IMPLIED_VERSION
   ,PLISTVER=MAX  
   ,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  
   ,MF=(L,list addr list addr: symbol.
   ,MF=(L,list addr,attr) attr: 1- to 60-character input string.
   ,MF=(L,list addr,0D) Default: 0D
   ,MF=(E,list addr) list addr: RS-type address or address in register (1) - (12) of a storage area.
   ,MF=(E,list addr,COMPLETE) Default: COMPLETE
   ,MF=(E,list addr,NOCHECK)  
   

Parameters for REQUEST=ENABLE

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 less than 4 characters long.

,REQUEST=ENABLE
A parameter that specifies that you want to enable the function codes specified in the SSVTDATA parameter.
,SSVTDATA=ssvtdata
A required parameter that specifies the name of the function routine input table that identifies the new function codes that the SSVT supports and their related function routines. Use the IEFSSVTI macro to build the table. This field contains the the name specified by the IEFSSVTI SSVTDATA parameter.
,INTOKEN=intoken
,INTOKEN=NULL
An optional 32-bit parameter that specifies the name (or an address in a register) of an input token that represents the target SSVT. The default is NULL.
,LOADTOGLOBAL=NO
,LOADTOGLOBAL=YES
An optional parameter that specifies that the function routines are to be loaded to global storage. Use this parameter when the function routines:
  • Are specified by name in the function routine input table that the IEFSSVTI macro created
  • Do not reside in the link pack area.

This parameter is ignored if the input function routines are specified by address.

The meanings are:

NO
Indicates that a load-to-global is not necessary for the function routines. This is the default.
YES
Indicates that a load-to-global is necessary for the function routines. The SSI issues a LOAD for the named function routine with the following parameters:
  • EOM=YES
  • LSEARCH=NO
  • GLOBAL=(YES,P)
,ERRFUNCT=errfunct
An optional 8-character parameter that specifies the name (or an address in a register) of an output field that receives the function routine name being processed when an error occurred. Check this output field if you get return code IEFSSVT_LOAD_ERROR (decimal 22) from the IEFSSVT macro.
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 a name (or register) of an output field 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 a name (or register) of an output field 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 IEFSSVT 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 IEFSSVT 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 the MF=E together with the list form of the macro for applications that require reentrant code. The execute form of the IEFSSVT 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=EXCHANGE parameter of IEFSSVT

The IEFSSVT macro with the EXCHANGE parameter exchanges the function routine that supports a function code with a different function routine.

Syntax for REQUEST=EXCHANGE

The syntax of the IEFSSVT REQUEST=EXCHANGE macro is written as follows:

Syntax Description
   
   name name: symbol. Begin name in column 1.
   
␢ One or more blanks must precede IEFSSVT.
   
IEFSSVT  
   
␢ One or more blanks must follow IEFSSVT.
   
SUBNAME=subname  
   
,REQUEST=EXCHANGE  
   
,SSVTDATA=ssvtdata ssvtdata: RS-type address
   
   ,INTOKEN=intoken intoken: RS-type address or address in register (2) - (12).
   ,INTOKEN=NULL Default: INTOKEN=NULL
   
   ,LOADTOGLOBAL=NO Default: LOADTOGLOBAL=NO
   ,LOADTOGLOBAL=YES  
   
   ,ERRFUNCT=errfunct errfunct: RS-type address or address in register (2) - (12).
   
   ,PLISTVER=IMPLIED_VERSION Default: IMPLIED_VERSION
   ,PLISTVER=MAX  
   ,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  
   ,MF=(L,list addr list addr: symbol.
   ,MF=(L,list addr,attr) attr: 1- to 60-character input string.
   ,MF=(L,list addr,0D) Default: 0D
   ,MF=(E,list addr) list addr: RS-type address or address in register (1) - (12) of a storage area.
   ,MF=(E,list addr,COMPLETE) Default: COMPLETE
   ,MF=(E,list addr,NOCHECK)  
   

Parameters for REQUEST=EXCHANGE

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 less than 4 characters long.

,REQUEST=EXCHANGE
A parameter that specifies that you want to exchange existing function routines with new function routines.
,SSVTDATA=ssvtdata
A required parameter that specifies the name of the function routine input table that identifies the new function codes affected by the exchange and the new function routines that support them. Use the IEFSSVTI macro to build the table. This field contains the the name specified by the IEFSSVTI SSVTDATA parameter.
,INTOKEN=intoken
,INTOKEN=NULL
An optional 32-bit parameter that specifies the name (or an address in a register) of an input token that represents the target SSVT. The default is NULL.
,LOADTOGLOBAL=NO
,LOADTOGLOBAL=YES
An optional parameter that specifies that the function routines are to be loaded to global storage. Use this parameter when the function routines:
  • Are specified by name in the function routine input table that the IEFSSVTI macro created
  • Do not reside in the link pack area.

This parameter is ignored if the input function routines are specified by address.

NO
Indicates that a load-to-global is not necessary for the function routines. This is the default.
YES
Indicates that a load-to-global is necessary for the function routines. The SSI issues a LOAD for the named function routine with the following parameters:
  • EOM=YES
  • LSEARCH=NO
  • GLOBAL=(YES,P)
,ERRFUNCT=errfunct
An optional 8-character parameter that specifies the name (or an address in a register) of an output field that receives the function routine name being processed when an error occurred. Check this output field if you get return code IEFSSVT_LOAD_ERROR (decimal 22) from the IEFSSVT macro.
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 a name (or register) of an output field 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 a name (or register) of an output field 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 IEFSSVT 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 IEFSSVT 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 the MF=E together with the list form of the macro for applications that require reentrant code. The execute form of the IEFSSVT 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 IEFSSVT 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 IEFSSVT 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:

Return Code Decimal (Hex) Equate Symbol for Return Code
00 (00) IEFSSVT_SUCCESS
04 (04) IEFSSVT_WARNING
08 (08) IEFSSVT_INVALID_PARAMETERS
12 (0C) IEFSSVT_REQUEST_FAIL
16 (010) IEFSSVT_LOAD_ERROR
20 (014) IEFSSVT_SYSTEM_ERROR
24 (018) IEFSSVT_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 IEFSSVT Macro
Return Code Decimal (hex) Reason Code Decimal (hex)

Equate Symbol for Reason Code
Meaning and Action
00 (00) 00 (00) Equate Symbol: IEFSSVT_FUNCTIONS_COMPLETE
Meaning: The request completed successfully. The result depends on the request:
  • CREATE — An SSVT is created.
  • DISABLE — Supported function codes are disabled.
  • ENABLE — Additional function codes are enabled.
  • EXCHANGE — New function routines replace supported function routines.

Action: None.
04 (04) 00 (00) Equate Symbol: None
08 (08) 00 (00) Equate Symbol: IEFSSVT_SUBSYSTEM_UNKNOWN

Meaning: The subsystem was not defined to the SSI.

Action: None.
08 (08) 04 (004) Equate Symbol: IEFSSVT_NON_DYNAMIC

Meaning: The subsystem is not a dynamic subsystem.

Action: None.
08 (08) 08 (008) Equate Symbol: IEFSSVT_BAD_VT_TOKEN

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

Action: None.
08 (08) 12 (00C) Equate Symbol: IEFSSVT_INVALID_NAME

Meaning: The subsystem name or the routine name contains characters that are not valid.

Action: None.
08 (08) 16 (010) Equate Symbol: IEFSSVT_INVALID_FUNCTION_CODE

Meaning: The function code is outside the valid range.

Action: Correct the function code.
08 08 20 (014) Equate Symbol: IEFSSVT_DUPLICATE_FUNCTION_CODE

Meaning: The function code appears more than once in the function routine input table.

Action: Delete the duplicate specification.
08 08 24 (018) Equate Symbol: IEFSSVT_INVALID_FROUTINE

Meaning: The function routine name or address is null.

Action: If working with a function routine input table in dynamic storage, use the IEFSSVTI SET function to identify the function routine by name or address. If using a static table, the function routine must be identified by name using the IEFSSVTI ENTRY function.
08 08 28 (01C) Equate Symbol: IEFSSVT_NO_FCODES

Meaning: The function routine entry in the function routine input table does not specify any function codes.

Action: Specify the function codes with either the IEFSSVTI ENTRY or SET function.
12 (0C) 00 (00) Equate Symbol: None
12 (0C) 100 (064) Equate Symbol: IEFSSVT_MAX_VECTOR_TABLES

Meaning: The maximum number of SSVTs already exists for the subsystem. This is a CREATE request error.

Action: Additional vector tables cannot be created during the current IPL. Use the IEFSSVT ENABLE and DISABLE services to modify the response of an existing vector table.
12 (0C) 101 (065) Equate Symbol: IEFSSVT_STORAGE

Meaning: Unable to obtain storage for an SSVT. This is a CREATE request error.

Action: Review the use of system storage to determine why sufficient storage was not available. Try the request again later.
12 (0C) 102 (066) Equate Symbol: IEFSSVT_MAXENTRIES_TOO_SMALL

Meaning: The MAXENTRIES value is less than the number of function routines in the function routine input table. This is a CREATE request error.

Action: Correct the MAXENTRIES value. It must be at least as large as the number of function routines represented in the function routine input table.
12 (0C) 103 (067) Equate Symbol: IEFSSVT_MAXENTRIES_TOO_BIG

Meaning: The MAXENTRIES value is greater than the maximum value (255). This is a CREATE request error.

Action: None.
12 (0C) 200 (0C8) Equate Symbol: IEFSSVT_ENABLE_NO_ELIGIBLE_VT

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

Action: Use the IEFSSVT CREATE function to create an SSI-managed vector table.
12 (0C) 201 (0C9) Equate Symbol: IEFSSVT_ENABLE_MAX_ROUTINES

Meaning: The SSVT does not have available space for new function routines. This is an ENABLE request error.

Action: If the subsystem has only one SSI-managed vector table, use the IEFSSVT CREATE function to create a second larger one, which responds to all required function codes.

If the subsystem already has two vector tables, the problem cannot be corrected without re-IPLing the system, unless some function codes can be disabled to make room for the new required function routines.
12 (0C) 202 (0CA) Equate Symbol: IEFSSVT_FUNCTION_ALREADY_ENABLED

Meaning: The subsystem already responds to one of the function codes for which this request was submitted. This an ENABLE request error.

Action: If you want to change the routine that supports the function , use the IEFSSVT EXCHANGE function.
12 (0C) 300 (12C) Equate Symbol: IEFSSVT_DISABLE_NO_ELIGIBLE_VT

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

Action: Create an SSI-managed SSVT using the IEFSSVT CREATE function.
12 (0C) 500 (1F4) Equate Symbol: IEFSSVT_EXCHANGE_NO_ELIGIBLE_VT

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

Action: Create an SSI-managed SSVT using the IEFSSVT CREATE function.
12 (0C) 501 (1F5) Equate Symbol: IEFSSVT_EXCHANGE_MAX_ROUTINES

Meaning: The SSVT does not have available space for new function routines. This an EXCHANGE request error.

Action: If the subsystem has only one SSI-managed vector table, use the IEFSSVT CREATE function to create a second larger one, which responds to all required function codes.

If the subsystem already has two vector tables, the problem cannot be corrected without re-IPLing the system, unless some function codes can be disabled to make room for the new required function routines.

Examples

For the following examples, assume that the function routine input tables have already been built using the IEFSSVTI macro.

Example 1

Create an SSVT, reserving space for 5 function routines. The function routines reside in LPA, so the LOADTOGLOBAL parameter is allowed to default to NO. 
         IEFSSVT REQUEST=CREATE,SUBNAME=SNAME,SSVTDATA=FROUTINE_TABLE, X
               MAXENTRIES=5,OUTTOKEN=NEWTOKEN,ERRFUNCT=BADNAME,        X
               RETCODE=RETURN_CODE,RSNCODE=REASON_CODE
⋮
SNAME    DC    CL4'FRED'
⋮
WORKAREA DSECT 0F
NEWTOKEN DS    CL4
BADNAME  DS    CL8
RETURN_CODE DS F
REASON_CODE DS F
WORKLEN  EQU   *-WORKAREA

Example 2

Enable an additional function code in the SSVT that was created in example 1. The function routine input table ENABLE_TABLE describes only the new function code and its associated function routine. 
IEFSSVT REQUEST=ENABLE,SUBNAME=SNAME,SSVTDATA=ENABLE_TABLE,   X
      INTOKEN=NEWTOKEN,ERRFUNCT=BADNAME,                      X
      RETCODE=RETURN_CODE,RSNCODE=REASON_CODE

Example 3

Disable one of the function codes currently supported by the SSVT created in example 1. The function routine input table DISABLE_TABLE describes only the function code to be disabled. It does not have to provide function routine information. 
IEFSSVT REQUEST=DISABLE,SUBNAME=SNAME,SSVTDATA=DISABLE_TABLE, X
      INTOKEN=NEWTOKEN,                                       X
      RETCODE=RETURN_CODE,RSNCODE=REASON_CODE

Example 4

Change the function routine that responds to one of the function codes supported by the SSVT in example 1. The function routine input table EXCHANGE_TABLE identifies the function code and the new function routine. 
IEFSSVT REQUEST=EXCHANGE,SUBNAME=SNAME,
      SSVTDATA=EXCHANGE_TABLE,                                X
      INTOKEN=NEWTOKEN,ERRFUNCT=BADNAME,                      X
      RETCODE=RETURN_CODE,RSNCODE=REASON_CODE