Output Parameters

Output parameters for the function routine are:

SSVI

The function routine performs processing to return the subsystem version information, and returns this information to the caller through settings, field updates, and pointers to information contained in the SSVI control block.

In addition, the information fields (For example, SSVIFMID, SSVIVERS, and SSVICNAM) are defined by, and have meaning only to, the function routine.

SSVI Contents: If the function routine returned successfully to the caller, the function routine may return the following information in the SSVI control block:

Field Name

Description

SSOBRETN

The function routine sets this field to SSVIOK (decimal 0).

SSVIRLEN

The function routine sets this field to the number of bytes that is used to return the requested information.

This value includes the fixed section as well as the system variable section.

SSVIRVER

The function routine sets this field to the version of the SSVI macro used (SSVICVER).

SSVIFLEN

The function routine sets this field to the length of the fixed header output section (SSVIFSIZ).

SSVIASID

A 2-byte field that contains the ASID of the subsystem if the subsystem has an address space and supports the use of this field.

SSVIFMID

The function routine sets this field (left-justified, and padded to the right with blank (X'40') characters) to the function routine's FMID, if available.

SSVIVERS

The function routine sets this field (left-justified, and padded to the right with blank (X'40') characters) to the version of the subsystem installed. The function routine defines and uses the version naming conventions and meanings.

SSVICNAM

The function routine sets this field (left-justified, and padded to the right with blank (X'40') characters) to the processing subsystem's common name. For example, a subsystem defined as 'JOHN' might choose to return the SSVICNAM value of 'JOHNNY'. The subsystem defines the common name.

SSVIPLVL

This 1-byte field contains the product level of the subsystem. The content of the field is defined by the subsystem.

This field should only be used if the caller-supplied version in field SSVIVER is greater than or equal to 2.

SSVISLVL

This 1-byte field contains the service level of the subsystem. The content of the field is defined by the subsystem.

This field should only be used if the caller-supplied version in field SSVIVER is greater than or equal to 2.

SSVIUDOF

The function routine sets this field to zero (there is no installation variable output section).

SSVISDOF

The function routine sets this field to the offset of the start of the system variable section (same value as SSVIFLEN), if the function routine wants to supply system variable information.

The DSECT SSVIVDAT mapping begins at this offset, within the SSVI control block that the caller provided to the function routine. The caller must provide an SSVI control block large enough to contain the fixed section and system variable section beginning at this offset (SSVISDOF) past the start of the fixed section (SSVIHEAD).

The function routine may provide a system variable output section that contains additional information returned to the caller and mapped using SSVIVDAT. If it doesn't provide this, the SSVISDOF field must be set to zero.

The function routine sets the first halfword of this system variable information section to the length of the system variable section (not including itself) in the SSVIVLEN field, so that the first byte of the character string starts past the SSVIVLEN field.

For example, the function routine may choose to return the following character string to the caller:

   ,EXAMPLE_SWITCH='NO'

The function routine places the length of the character string, 20 bytes (decimal) in the SSVIVLEN field, followed by the character string, beginning at the SSVIDAT field. The first byte at the SSVIDAT field contains an EBCDIC value for the comma in front of the word 'EXAMPLE'.

Note that the comma is the first character of the character string even if only a single keyword value is being returned. See the Request Subsystem Version Information Call — SSI Function Code 54 for more information on the syntax of the returned system variable sections. IBM® recommends that your function routine also use the same syntax conventions.

If the function routine returned unsuccessfully to the caller, the system function may provide any of the following processing depending on the reasons for the unsuccessful return:

Insufficient Storage
The function routine has determined that the requestor has not supplied a storage area large enough to contain the requested information. That is, the caller has not provided a value in the SSVILEN field that is large enough to contain both the fixed section, as well as any possible system variable section (length plus actual data). The function routine therefore sets the following fields:
Field Name

Description

SSOBRETN

The function routine sets SSOBRETN to the value of SSVINSTR (decimal 8).

SSVIRLEN
The function routine sets SSVIRLEN to the amount of storage needed to satisfy the request.
The function routine determines the SSVIRLEN value by adding the length of the fixed header section (SSVIFSIZ) to the length of the system variable output section, plus two bytes (for the length value) of the returned string.
Suppose the caller in the example above only provided 30 decimal bytes for the returned information. Our function routine would return decimal 70 in the SSVIRLEN field as follows:
48 — decimal value of the defined symbol SSVIFSIZ

2 — length of the SSVIVLEN field (2 bytes long)

20 — length of the character string (,EXAMPLE_SWITCH='NO').
All other fields in the SSVI control block are not set by the function routine.
Requestor does not provide a valid SSVI
The SSVI control block that is supplied by the caller should be validity-checked by the function routine. The following validations are suggested:
- The SSOBINDV value in the SSOB control block should be non-zero.
- The SSVILEN field supplied by the caller should be equal to or greater than SSVIMSIZ (an equated value within the SSVI).
- The SSVIID field supplied by the caller should contain the EBCDIC characters 'SSVI'.
- The SSVIVER field supplied by the caller should be non-zero.
  The current version of the SSVICVER field is equated to SSVIVONE (decimal 1).
  
  Future versions of the SSVI control block must have their version number increased, so both the caller and the function routine are able to determine what information is expected and provided.
If any of the above conditions are not true, the function routine must set the SSOBRETN field as follows:
Field Name

Description

SSOBRETN

The function routine sets SSOBRETN to the value of SSVIPARM (decimal 16).

All other fields in the SSVI control block are not set by the function routine.
An abend or logical error within the function routine occurs
It is possible that an abend or logical error occurs in your routine. IBM supplies an equate symbol for this return code. If your routine chooses to use it, the function routine must set the following field:
Field Name

Description

SSOBRETN

The function routine sets SSOBRETN to the value of SSVIABLG (decimal 24).

All other fields in the SSVI control block are not set by the function routine.