Programming notes for VERSION=0 and VERSION=1

If the FSTAT macro accesses pubsets with large volumes that do not, however, allow large files, interface behavior is unchanged. Access of this kind is always performed without problems.
Problems can occur if pubsets that also allow large files are accessed.

Interface variants that do not need to be converted

FSTAT ...,VERSION=0,<partially-qualified filename> 
FSTAT ...,VERSION=0,<file generation group with GEN=YES>
FSTAT ...,VERSION=1,FNAM

The semantics problem discussed at OPEN macro must be considered, see "OPEN - Open file".
Each user of this interface must check whether this problem applies to their implementation.

Interface variants that need to be checked/converted

FSTAT ...,VERSION=0/1,SHORT/LONG

These variants return the catalog information in BS2000 V10.0 format.
The extent lists and data fields for File-Size and Last-Page-Pointer are output with only 3 bytes. For reasons of compatibility, it is not possible to change the layout of these interfaces.

Calls that refer to large objects cause an overflow in the 3-byte fields.

Two different cases must be distinguished. These depend on the contents of the result list from the FSTAT call:

1. No file >= 32 GB exists in the result list (set of selected files).

   In this instance, FSTAT tolerates the overflow of the 3-byte data field of the PHP in the extent list. The value X'FFFFFF' is assigned to the PHPs that cannot be displayed. It is assumed that the PHPs are never or very rarely evaluated at the interfaces. If this is occasionally not the case, the interface must be converted to version 2 or 3. 
   This achieves the following:

   • The introduction of large volumes can be carried out in a compatible manner, user programs do not need to be changed.

   • FSTAT calls with fully-qualified pathnames can be supported compatibly (except for the PHP overflow in the extent list).

   No conversion is necessary!

2. At least one file >= 32 GB exists in the result list (FSTAT is called with a partially-qualified filename or with wildcards).

   Calls of this kind are rejected with the following return code:

   X'cc'	X'bb'	X'aaaa'	Explanation
   X'00'	X'01'	X'0576'	The selection contains large files.

   The following types of FSTAT interfaces are affected:

   Type		Comment
   I	FSTAT ...	VERSION=0 is set as default
   II	FSTAT ...,VERSION=0
   III	FSTAT ...,VERSION=1,SHORT
   IV	FSTAT ...,VERSION=1,LONG
   V	FSTAT ...,VERSION=1	The SHORT operand is set as default

   These calls must be converted to VERSION=2/3!

Summary of FSTAT calls

FSTAT <fully-qualified pathname>,VERSION=0/1

• Access only to small files (less than 32 GB):
  No action necessary ¹⁾

• Large files are also accessed (>= 32 GB):
  If the call is made with one of the types I to V, conversion to VERSION=2/3 is necessary, with the exception of types I and II where the file generation group and GEN=YES are specified.

FSTAT <partially-qualified pathname or pathname with wildcards>,VERSION=0/1

• The result list contains only small files (less than 32 GB):
  No action necessary ¹⁾

  Warning!
  You must ensure that the requirements are always fulfilled.
  This is probably only possible for pathnames that contain wildcards in the catalog ID and otherwise contain fully-qualified components.

¹ “No action necessary” applies here if the result list contains only small files and the overflow of the 3-byte data field of the PHP in the extent list does not present a problem. If this is not the case, conversion to VERSION=2/3 is necessary.

• The result list can also contain large files (>= 32 GB): 
  If the call is made with one of the types III to V, conversion to VERSION=2/3 is necessary.

Conclusion

When using the FSTAT interface with VERSION < 2 and FORM=LONG or FORM=SHORT, it is necessary to convert to the most recent interface version under the following circumstances:

1. Large files should be accessible with the FSTAT call in the affected program.

2. The pathname in the FSTAT call is partially-qualified or contains wildcards and it cannot be assumed that the result list contains no large files. Calls with wildcards in the catalog ID are particularly critical here.

It may be necessary to convert the data structures in the program as well as the interface. 

Control using the system parameter FST32GB

FST32GB only affects the following FSTAT interfaces:

• Version=0 (corresponds to Version=710) when a fully-qualified filename is specified (although not when a file generation group is specified with GEN=YES)

• Version=1 (corresponds to Version=800), where the FNAM operand was not specified

Whether the existence of a file >= 32 GB in the list of selected files leads to the FSTAT call being rejected with the X'00000576' return code (FST32GB=0, default setting) or whether an overflow of the 3-byte fields is always tolerated (FST32GB=1) is set globally on the system by systems support staff. In the latter case, the value X'FFFFFF' is assigned to the data fields that cannot be displayed.

Note

The system parameter FST32GB is not evaluated if the FSTAT indicator (see below) is set.

Control using the FSTAT indicator

Behavior equivalent to FST32GB=1, i.e. ignoring the overflow, can be activated for specific interfaces for FSTAT types I to V using an indicator.

Note

The FSTAT indicator has a higher priority than the system parameter FST32GB. If the FSTAT indicator is set, FST32GB is not evaluated.
The indicator must be set directly in the parameter list; no support is provided in the FSTAT macro.

Description of the bits in the corresponding DSECT:

         FSTAT MF=D,PARMOD=31,VERSION=710 
IDBFLAG2 DS    X                                FLAGS 2
IDBLOPYE EQU   X'04'                            2-2 S LARGE PUBSET ACCESS=YES 
         FSTAT MF=D,PARMOD=31,VERSION=800 
IFLAG0   DC    B'10001100'                      
ILOPY    EQU   X'04'                            2-2 S LARGE PUBSET ACCESS=YES