Output Parameters

Output parameters for the function routine are:

SSOBRETN
SSJPRETN
IAZJPSPL (SPOOL Volume Information service)

SSOBRETN Contents: When control returns to the caller and register 15 contains a zero, the SPOOL Volume Information services function places one of the following decimal values in the SSOBRETN field:

Value (Decimal)

Meaning

SSJPOK (0)

Request successful.

SSJPERRW (4)

Request completed with possible errors, see SSJPRETN for reason code.

SSJPERRU (8)

Request cannot be completed because of user error, see SSJPRETN for reason code.

SSJPERRJ (12)

Request cannot be completed, SSJPRETN contains internal reason code.

SSJPPARM (16)

Error in the parameter list. For example, the SSJP extension is an invalid format

It is not an SSJP
The service version number is not supported
The SSJP is not large enough

SSJPSTOR (20)

Request cannot be processed because required storage cannot be obtained. No data can be returned to the caller.

SSJPRETN Contents: In addition to the return code in SSOBRETN, the field SSJPRETN contains the service related error or more specific information about the error. SSJPRETN can be set to one of the following values if SSOBRETN is not zero:

Value (Decimal): Meaning
SSJPUNSF (4): Unsupported subfunction requested.
SSJPNTDS (8): SSJPUSER does not point to the correct control block.
SSJPUNSD (12): Version number in the control block pointed to by SSJPUSER is not correct.
SSJPSMLE (16): Length field in the control block pointed to by SSJPUSER is too small.
SSJPEYEE (20): Eyecatcher in the control block pointed to by SSJPUSER is not correct.
SSJPGETM (128): $GETMAIN failed.
SSJPSTGO (132): STORAGE OBTAIN failed.
SSJPINVA (136): Invalid filter arguments were specified.
SSJPGLBL (140): Function not supported on the global (JES3 only).

SPOOL Volume Information service, IAZJPSPL contents: For the SPOOL Volume Information service (function code SSJPSPOD), the following parameters are returned in IAZJPSPL:

Field Name: Description
JPSPVERO: Subsystem version number (currently X'0200').
JPSPLPTR: Pointer to data for first partition data area.
JPSPNPAR: Number of partition data areas returned.
JPSPTGT: Number of track groups defined across all partitions.
JPSPTGIU: Number of track groups in use across all partitions.
JPSPTKT: Number of tracks across all partitions.
JPSPTKU: Number of tracks in use across all partitions.
JPSPTGAT: Number of active track groups defined across all partitions.
JPSPTGAI: Number of active track groups in use across all partitions.
JPSPTKAT: Number of active tracks across all partitions.
JPSPTKAU: Number of active tracks in use across all partitions.

For each Spool Partition that passes the filter requirements, a Spool Partition element is added to the chain pointed to by JPSPLPTR. Each element is composed of the following sections:

DSECT Name: DSECT Description
SPPHDR: Partition Header Section
SPPPREF: Partition Prefix Section
SPPGENI: Partition General Information Section
SPPJES3I: Partition JES3 Specific Information Section

Each Spool Partition element has a chain of one or more Spool Extent sections. The first of these sections is pointed to by the field SPPFRSTE in the Partition Header section. The Spool Extent information is composed of the following sections:

DSECT Name: DSECT Description
SPEHDR: Spool Extent Header Section
SPEPREF: Spool Extent Prefix Section
SPEGENI: Spool Extent General Information Section
SPEJ2I: Spool Extent JES2 Specific Information Section
SPEJ2AI: Spool Extent JES2 Affinity Specific Information
SPEJ2AE: Spool Extent JES2 Affinity Array Entry
SPEJ3I: Spool Extent JES3 Specific Information

The following is a layout of the various sections of the Spool Information output data area. The basic layout is a chain of Spool Partition Information sections. Each Partition section has a chain of Extent Information sections.

          SSI 82 SPOOL DATA PARAMETER LIST:                 
          +----------------+                                
    JPSPL | . . .          |        NOTE: The output        
          |                |              partition rollup  
          | JPSPLPTR  =--------+          values reside     
          | . . .          |   |          here.             
          +----------------+   |                            
                               |                            
                               |                            
       +-----------------------+                            
       |                                                    
       |                                                    
       |  SPOOL PARTITION INFO SECTION:                     
       +->+----------------+                                
   SPPHDR | SPPNXTP   =-----------> POINTER TO THE NEXT     
          |                |        SPPHDR IN THE CHAIN.    
          | SPPFRSTE  =--------+    ZERO IF END OF CHAIN.   
          | . . .          |   |                            
          +----------------+   |    NOTE: JES2 will always  
  SPPPREF | Prefix Section |   |          have 1 partition. 
          | . . .          |   |          JES3 can have     
          +----------------+   |          multiple.         
  SPPGENI | General        |   |                            
          | Partition Info |   |                            
          | Section        |   |                            
          | . . .          |   |                            
          +----------------+   |                            
 SPPJES3I | Optional JES3  |   |                            
          | Partition      |   |                            
          | Info Section   |   |                            
          | . . .          |   |                            
          +----------------+   |                            
                               |                            
                               |                            
       +-----------------------+                            
       |                                                    
       |                                                    
       |  SPOOL EXTENT INFO SECTION:                        
       +->+----------------+                                
   SPEHDR |                |                                
          | SPENXTE --------------> POINTER TO THE NEXT     
          | . . .          |        SPEHDR IN THE CHAIN.    
          +----------------+        ZERO IF END OF CHAIN.   
  SPEPREF | Prefix Section |                                
          | . . .          |                                
          +----------------+                                
  SPEGENI | General Extent |                                
          | Info Section   |                                
          | . . .          |                                
          +----------------+                                
   SPEJ2I | Optional JES2  | NOTE: Included if JES2         
          | Extent Info    |                                
          | Section        |                                
          | . . .          |                                
          +----------------+                                
  SPEJ2AI | Optional JES2  | NOTE: Included if JES2 and     
          | Extent Affinity|       Affinity exists.         
          | Array Header   |                                
          | Section        |                                
          | . . .          |                                
          +----------------+                                
  SPEJ2AE | Optional JES2  | NOTE: Included if the SPEJ2AI  
  (1..N)  | Extent Affinity|       Extent Array header      
          | Array Elements |       Section is included. #   
          |                |       of elements is SPE2ANUM. 
          | . . .          |
          +----------------+
  SPEJ2MI | Optional JES2  | NOTE: Included if JES2 and     
          | Extent Active  |       extent is associated     
          | Migration Info |       with an active           
          | Section        |       migration.               
          | . . .          |
          +----------------+                                
  SPEJ3I  | Optional JES3  | NOTE: Included if JES3.        
          | Extent Info    |                                
          | Section        |                                
          | . . .          |                                
          +----------------+

Spool Partition Header Section: Each Spool Partition information element begins with a header section. There can be multiple Spool Partitions returned, and the SPPNXTP pointer is used to navigate to the next Spool Partition Header section in the chain.

Note: JES2 will only have a single information element in this chain.

The fields in the SPPHDR section are:

Field Name: Description
SPPEYE: Eyecatcher. Should be set to ‘SPOOLPRT’
SPPOPRF: Offset to the prefix section
SPPNXTP: Address of the next Spool Partition information element
SPPFRSTE: Address of the first Extent section for this Partition

Spool Partition Prefix Section: This section holds the length of all the information reported for this Spool Partition. This length does not include the length of the Spool Partition Header section: This length does include all the storage needed to report both the Spool Partition sections as well as all the related Extent sections. To get addressability to this section, add the SPPOPRF header field to the header (SPPHDR) address.

The fields in the SPPPREF section are:

Field Name: Description
SPPPRLN: Length of the entire Spool Partition element, not including the length of the Partition Header.
SPPPRTP: Type of this section
SPPPRMD: Modifier for this section

Spool Partition General Information Section: This section holds details that are common to both JES2 and JES3.

The fields in the SPPGENI section are:

Field Name

Description

SPPGLN

Length of this section

SPPGTY

Type of this section

SPPGMD

Modifier for this section

SPPGNM

Partition name. (Always set to blanks for JES2)

SPPGTGT

Total Track Groups for all extents in this Partition

SPPGTGU

Total Track Group in use for all extents in this Partition

SPPGTKT

Total Tracks for all extents in this Partition

SPPGTKU

Total Tracks in use for all extents in this Partition

SPPGFLG1

Partition Indicators

Bit Name: Description
SPPGNSPC: Set ON when no free space currently exists in the partition
SPPGACTV: Set ON when active extents exist in the partition
SPPGALOC: Set ON when some extents have space available that is not currently utilized.

SPPGTGAT

Total active Track Groups for all extents in this Partition

SPPGTGAU

Total active Track Group in use for all extents in this Partition

SPPGTKAT

Total active Tracks for all extents in this Partition

SPPGTKAU

Total active Tracks in use for all extents in this Partition

Spool Partition JES3 Specific Information: This section contains a series of flags that describe JES3 Spool Partition information.

The fields in the SPPJES3I section are:

Field Name

Description

SPP3LN

Length of this section

SPP3TY

Type of this section

SPP3MD

Modifier for this section

SPP3OPAR

Overflow partition name

SPP3STSF

Partition Status flags

Bit Value: Description
SPP3ALD: Partition allocation is allowed
SPP3DFTP: This is the default partition
SPP3IDTA: Initialization data exists on this partition
SPP3OVER: This partition has overflowed into another partition
SPP3POVI: At least one other partition might overflow into this partition
SPP3POVO: This partition might overflow into another partition

SPP3THRF

Partition Threshold Flags

Bit Value: Description
SPP3MRG: Marginal threshold exceeded
SPP3MIN: Minimal threshold exceeded

SPP3MRGP

Marginal SLIM threshold percentage

SPP3MINP

Minimal SLIM threshold percentage

Spool Extent Header Section: Each individual Spool Extent Information section begins with a header section. This section holds an offset to the start of the detailed extent information, as well as a pointer to the next extent defined for this spool partition.

To get addressability to this section, use the SPPFRSTE pointer in the partition header (SPPHDR).

There can be multiple extents returned. The SPENXTE pointer is used to navigate to the next extent in the chain.

To get from this header to the extent prefix section for this extent, add the SPEOPRF offset to the extent header (SPEHDR) address.

The fields in the SPEHDR section are:

Field Name: Description
SPEEYE: Eyecatcher. It should be set to ‘SPOOLEXT’
SPEOPRF: Offset to the Extent Prefix section
SPENXTE: Address of the next Extent Header section

Spool Extent Prefix Section: This section holds the combined length of all the sections needed to report information about an individual initiator. To get addressability to this section, add the SPEOPRF header field to the header (SPEHDR) address.

The fields in the SPEPREF section are:

Field Name: Description
SPEPRLN: Combined length of the individual extent sections. This does not include the length of the header section.
SPEPRTP: Type of this section
SPEPRMD: Modifier for this section

Spool Extent General Information Section: This section holds general information about the spool extent.

The fields in the SPEGENI section are:

Field Name

Description

SPEGLN

Length of this section

SPEGTY

Type of this section

SPEGMD

Modifier for this section

SPEGSTS

Extent Status string

SPEGSTSB

Extent Status byte

Field Value: Description
SPEGACT: ACTIVE status
SPEGSTRT: STARTING status
SPEGHALT: HALTING status
SPEGDRN: DRAINING status
SPEGINAC: INACTIVE status
SPEGHELD: HELD status (JES3 Only)
SPEGXTND: EXTENDING status
SPEGMIGR: MIGRATING status
SPEGMAPP: MAPPED status

SPEGFLG1

Extent General Status Flags

Bit Name: Description
SPEGNRML: Set ON when the extent is in ACTIVE status
SPEGRSVD: Set ON when the extent is in RESERVED status
SPEGNSEL: Set ON when work on this extent is not selectable

SPEGPERC

Percent complete for the in-progress $MSPL spool migration command.

SPEGEXTI

Extent identifier. This is the Volume Name in JES2 and the DDNAME in JES3.

SPEGDSNM

Data set name on which this extent physically resides

SPEGTGT

Total track groups

SPEGTGU

Total track groups in use

SPEGTTRK

Total tracks

SPEGTTKU

Total tracks in use

SPEGLCYL

Low cylinder. Note that this is a normalized value (cccCC)

SPEGLHED

Low head

SPEGLMTR

Low MQTR value for JES2; Low MMRRRR value for JES3

SPEGLMM

Defines JES3 extent number

SPEGLRRN

Defines JES3 record number

SPEGHCYL

High Cylinder. Note this is the normalized value (cccCC)

SPEGHHED

High head

SPEGHMTR

High MQTR value for JES2; High MMRRRR value for JES3

SPEGHMM

Defines JES3 extent number

SPEGHRRN

Defines JES3 record number

SPEGTPCY

Tracks per cylinder

SPEGRPTK

Records per track

SPEGTPTG

Tracks per track group

SPEGEXTN

Extent number

SPEGVSER

VOLSER where this extent's data set resides

SPEGLTRK

Low Track Number

SPEGHTRK

High Track Number

Spool Extent JES2 Specific Information: This section holds Extent information specific to JES2.

The fields in the SPEJ2I section are:

Field Name

Description

SPE2LN

Length of this section

SPE2TY

Type of this section

SPE2MD

Modifier for this section

SPE2CMD

Current Command string. This is set to blanks if no command is active.

SPE2CMDB

Current Command byte

Field Value: Description
SPE2NCMD: No command is Active
SPE2STRT: START command
SPE2FRMT: FORMAT command
SPE2HALT: HALT command
SPE2DRN: DRAIN command
SPE2XTND: EXTEND command
SPE2MIGR: MIGRATE command

SPE2FLG1

Extent Status Indicators

Bit Name: Description
SPE2STNT: If set ON, this extent is stunted
SPE2ALLM: If set ON, ALL members have affinity to this volume. The Affinity Array sections do NOT exist. If set OFF, SOME members have affinity to this volume. The Affinity Array sections DO exist.
SPE2MAPT: This extent is a target of MAPPED extents
SPE2ACTM: This extent is either the source or target of an active migration. Section SPEJ2MI has the details.

SPE2LFTK

Largest number of contiguous free tracks

SPE2HTRK

Highest used track relative to the start of the data set

SPE2TARG

Target Extent Identifier. This is the Volume Name in JES2 where this extent is migrating to, or has migrated to.

Spool Extent JES2 Affinity Specific Information Section: This section holds system affinity information specific to JES2.

This section only exists if the SPE2ALLM indicator in the JES2 info section (SPEJ2I) is OFF.

The fields in the SPEJ2AI section are:

Field Name: Description
SPE2ALN: Length of this section
SPE2ATY: Type of this section
SPE2AMD: Modifier for this section
SPE2ANUM: Number of entries in the Affinity Array.
Note: This number can be ZERO in cases where no members match the selection filters.
SPE2ALEN: Length of an entry in the Affinity Array

Spool Extent JES2 Affinity Array Entry: to get addressability to the first array entry, add the SPE2ALN field in the SPEJ2AI JES2 Affinity Array header to the SPEJ2AI Affinity Array header address.

Use the SPE2ANUM and SPE2ALEN fields in the SPEJ2AI JES2 Affinity Array header to loop through the array entries.

This array will not exist if ALL members have affinity to the extent. See the SPE2ALLM indicator for further discussion.

The fields in the SPEJ2AE section are:

Field Name: Description
SPE2EMBR: JES2 member Name
SPE2ESYS: MVS™ System Name

Spool Extent Active Migration JES2 Specific Information Section: only available when the bit SPE2ACTM is ON in the Spool Extent JES2 Specific Information section SPEJ2I.

This section only exists if the SPE2ACTM indicator in the JES2 info section (SPEJ2I) is ON.

The fields in the SPEJ2MI section are:

Field Name

Description

SPE2MLN

Length of this section

SPE2MTY

Type = JES2 Info

SPE2MMD

Type Mod = JES2 Migration

SPE2MFG1

Extent Active Migration Indicators:

Field Name: Description
SPE2M1SR: Extent is source of migration
SPE2M1TG: Extent is target of migration
SPE2M1MV: MOVE migration
SPE2M1MG: MERGE migration
SPE2NCAN: Migration cannot be cancelled
SPE2MERR: Migration failed and is being cleaned up

The following fields are only valid if SPE2M1SR is ON; they document where the source extent is migrating to.

Field Name

Description

SPE2MPH

Migration phase string.

SPE2MPHB

Migration phase byte. Contains one of the following values that matches the migration phase string:

Field Name: Description
SPE2NOMG: No migration active
SPE2MPND: PENDING phase
SPE2MINI: INITIALIZING phase
SPE2MSET: SETUP phase
SPE2MCPY: COPY phase
SPE2MCUP: CATCHUP phase
SPE2MCAN: CANCEL phase
SPE2MBAK: BACKOUT phase
SPE2MCLN: CLEANUP phase

SPE2MMGR

Migrator JES2 MAS member name

SPE2MVSR

Target extent VOLSER that the current extent is migrating to

SPE2MDSN

Target extent SPOOL data set name that the current extent is migrating to

SPEJ2MIS

Size of this section

Spool Extent JES3 Specific Information Section: This section holds Extent information specific to JES3.

The fields in the SPEJ3I section are:

Field Name

Description

SPE3LN

Length of this section

SPE3TY

Type of this section

SPE3MD

Modifier for this section

SPE3RCSZ

Extent record size

SPE3FLG1

Extent Status Indicators:

Bit Name: Description
SPE3STRK: Set ON for a Single Track Table
SPE3BTRK: Set ON when the extent contains a bad track