In FSTAT VERSION=2/3, the corresponding data (extent list and data fields or the file-size and last-page pointers) are returned as 4-byte fields. Consequently, these interfaces do not have to be converted for calls in configurations involving files > 32 GB.
However, it is necessary to take account of the semantic problem affecting the OPEN macro, see "OPEN - Open file". All users of this interface should check whether this problem affects their particular implementation.
The FSTAT macro enables the user to request information from the catalog entry of one or more files.
The OUTAREA operand reserves an output area for the general information retrieved from the catalog entry; the STOUTAR operand assigns an output area for statistics.
The assigned output area should be overwritten with X'00' before data is transferred to it, since the unused parts of the output area are not fully deleted to the end.
The information from the catalog entry is transferred to the output area in blocks, and the requested information blocks are shown directly under one another in the output area. If the number of files is known, the size of the output area can be calculated precisely. Otherwise, if the free space available in the output area is too small to hold an information block, no further data is written to the output area, and the free space is filled with X'00'. The field IROLN (Real Output Length) of the input area returns information on the number of bytes that have been transferred to the output area (if the input parameter area is generated with FSTAT MF=D, VERSION=2, XPAND=PLSHORT).
Depending on the number of information blocks to be transferred and the size that is defined for the output area, the following cases may be differentiated:
The output could be completed fully:
Only the requested information is written to the output area; all unused fields contain X'00'.The caller receives the return code:
00 00 0000:
All the requested information was transferred to the output area.
No file matching the selection criteria was found:
No information is written to the output area. The caller receives the following return code:
00 00 0533:
The specified file was not found in pubset '(&00)'.
or
00 00 06CC:
The specified file was not found in pubset '(&00)'.
No output was possible:
If absolutely no data can be written to the output area, the caller receives the following return code:
00 01 05AB:
nvalid address for the area or illegal length specification in the FSTAT macro.
The program should be checked and corrected.
The output could not be completed fully:
If the estimated size of the output area is too small and some of the requested information blocks cannot be transferred as a result, in addition to the main code 06CB (“length specification too small for entry”), an indicator showing which of the two output areas (OUTAREA/STOUTAR) could not be transferred is placed in subcode2.
01 00 06CB:
The catalog entry information could not be transferred fully (for OUTPUT=CEINFO/FNAM-ONLY).
02 00 06CB:
The requested statistics could not be transferred fully (for OUTPUT=STAT-SHORT/STAT-LONG).
03 00 06CB:
Both the catalog entry information and the statistics could not be transferred fully (for OUTPUT=STAT-INFO).
The user can define a larger output area and repeat the FSTAT call in such cases.
The contents and structure of the information to be output depends on which information is selected for retrieval by means of the OUTPUT operand. The following options are available:
OUTPUT = CEINFO / FNAM-ONLY / RC-ONLY / STAT-INFO / STAT-LONG / STAT-SHORT
No output area is required for OUTPUT=RC-ONLY. If OUTPUT=STAT-INFO is specified, the same information as for CEINFO + STAT-LONG is output.
The information blocks can be accessed via an information header. If no blocks are requested, the address pointer for this block is set to null.
The offsets in the respective output areas are calculated relative to the start of the block in which the offset is defined. The offsets in BLOCK_INFORMATION_Header2 are related to BLOCK_INFORMATION_Header1, since both blocks are treated as a single unit.
All the output structures shown below are typical examples in which the block name (e.g. BLOCK_INFORMATION_HEADER) refers to the block headers of the DSECT that can be generated to evaluate the output area.
This DSECT can be generated with the macro:
FSTAT MF=D, XPAND=OUTPUT, VERSION=3.
Output structure for OUTPUT=CEINFO
In this output format, all information from the catalog entry excluding the statistics are output in the area defined by OUTAREA. The desired information can be selected via the CEINFO operand.
CEINFO = | HISTORY | Information on accesses to the file |
SECURITY | Access rights and data security attributes | |
BACKUP | Backup attributes for the file | |
ORGANIZATION | File organization attributes | |
STATUS | Special characteristics of files | |
ALLOCATION | Information on physical attributes of the file | |
VOLUME | Volume list | |
VOLUME-EXTENTS | Volume list and extent list | |
INDEX-INFO | Information on the file generation group | |
FTAM | FTAM (file transfer access method) data |
The following diagram shows the output areas for two files:
BLOCK_INFORMATION_HEADER1 contains the following:
pathname | Path number of the selected file, subdivided into:
|
BLOCK_INFORMATION_HEADER2 contains the address pointers to the information blocks and to the output area of the next file.
offset_next: Offset to the next BLOCK_INFORMATION_HEADER (2 bytes) (start of the output area of the next file)
offset_history: Offset to the HISTORY_BLOCK (2 bytes)
offset_security: (2 bytes)
offset_backup: (2 bytes)
...
The two headers are followed by the information blocks which contain the actually useful information (HISTORY_BLOCK, SECURITY_BLOCK etc.). The description and length of the individual fields can be obtained from the DSECT.
Output structure for OUTPUT=FNAM-ONLY
In this output format, only the path names of the selected files are shown in the output area defined by OUTAREA. Apart from the end criterion in the last byte, the BLOCK_INFORMATION_HEADER1 in the output structure for OUTPUT=FNAM-ONLY is identical to the corresponding header for OUTPUT=CEINFO (see "Programming notes (VERSION=2, 3 and 4)").
End criterion
X'00' | There are no further path names. |
X'01' | Additional path names follow. |
Output structure for OUTPUT=STAT-LONG
In this output format, only the statistics are shown in the output area defined by the STOUTAR operand.
Nonprivileged users are returned information on files that can be stored on one or more pubsets.
The system administrator can also use wildcards to have information on multiple user IDs displayed.
*) Only the system administrator can select multiple user IDs.
The MAIN_HEADER returns the following information:
Statistics
Total number of selected files (4 bytes)
Number of files on public volumes (4 bytes)
Number of files on private volumes (4 bytes)
Number of files on Net-Storage (4 bytes)
Number of files on tape (4 bytes)
Number of files with migration level 1 (HSMS) (4 bytes)
Number of files with migration level 2 (HSMS) (4 bytes)
Number of user IDs (2 bytes)
Number of free PAM pages on public volumes (4 bytes)
Number of free PAM pages on private disk (4 bytes)
Number of free PAM pages on Net-Storage (4 bytes)
Number of free PAM pages at migration level 1 (4 bytes)
Number of free PAM pages at migration level 2 (4 bytes)
offset_pvsid1 | Offset to the first PVSID_HEADER (2 bytes) |
The PVSID_HEADER returns the following information:
Statistics
Catalog ID (4 bytes)
Total number of selected files (4 bytes)
Number of files on public volumes (4 bytes)
Number of files on private volumes (4 bytes)
Number of files on Net-Storage (4 bytes)
Number of files on tape (4 bytes)
Number of files with migration level 1 (HSMS) (4 bytes)
Number of files with migration level 2 (HSMS) (4 bytes)
Number of user IDs (2 bytes)
Number of free PAM pages on public volumes (4 bytes)
Number of free PAM pages on private disk (4 bytes)
Number of free PAM pages on Net-Storage (4 bytes)
Number of free PAM pages at migration level 1 (4 bytes)
Number of free PAM pages at migration level 2 (4 bytes)
offset_nextpvsid | Offset to the next PVSID_HEADER (2 bytes) |
offset_info | Offset to the BLOCK_INFORMATION_HEADER1 of the first selected file for this catalog (4 bytes) (relative to the address of the OUTAREA) |
The USERID_HEADER returns the following information:
Statistics
User ID (8 bytes)
Total number of selected files (4 bytes)
Number of files on public volumes (4 bytes)
Number of files on private volumes (4 bytes)
Number of files on Net-Storage (4 bytes)
Number of files on tape (4 bytes)
Number of files with migration level 1 (HSMS) (4 bytes)
Number of files with migration level 2 (HSMS) (4 bytes)
Number of free PAM pages on public volumes (4 bytes)
Number of free PAM pages on private disk (4 bytes)
Number of free PAM pages on Net-Storage (4 bytes)
Number of free PAM pages at migration level 1 (4 bytes)
Number of free PAM pages at migration level 2 (4 bytes)
offset_info | Offset to the BLOCK_INFORMATION_HEADER1 of the first selected file of this user ID that is found under the catalog ID indicated above (4 bytes) (relative to the address of the OUTAREA) |
Output structure for OUTPUT=STAT-SHORT
In this output format, only the MAIN_HEADER of the output structure for OUTPUT=STAT-LONG is shown (see "Programming notes (VERSION=2, 3 and 4)").
Output structure for OUTPUT=STAT-INFO
This format combines the output structures for OUTPUT=CEINFO and OUTPUT=STAT-LONG. Two output areas, OUTAREA and STOUTAR, must be defined by the user for this purpose. The output area for statistics, STOUTAR (shown to the left in the diagram below), contains references to the output area OUTAREA (shown on the right).
The diagram shows only one user ID in the output area STOUTAR. This corresponds to the selection option for nonprivileged users:
