General files

A z/TPF general file is a single extent of contiguous space on a disk pack formatted for use within a z/TPF environment. A general file data set is a subdivision within that general file. The general file data set contains sequentially organized, but randomly accessible, records of related data.

There can be no more than three general file data sets in a general file. General files are subsystem unique, and each general file data set has an installation-specified number, unique within the subsystem, which identifies it to the user and to the z/TPF system.

Despite the similarity in names, general file data sets are not related in any way to general data sets. General data sets are essentially z/OS® data sets, and are used primarily to pass data between z/TPF and z/OS systems. General data sets are discussed in General data sets.

Records in a general file data set are not duplicated and, within a general file data set, must be of the same length, either 381, 1055, or 4KB bytes.

The z/TPF online file formatter must be used to format a general file, and the starting address of each data set must be recorded in the general file module table (GFMT).

A SIP skeleton (SKCVZD) creates program segment CVZD, the general file definition record that also serves as the general file premount record. General files are defined to the system by adding entries to CVZD and then reassembling and loading CVZD to the online system. The GFMT is initialized from CVZD during IPL when CTKB has been loaded with the initial IPL switch (CK9IPLR) set to X'00'.

Positions 42 through 47 of the volume label (cylinder 0, head 0, record 3) are reserved to record the data set numbers that reside on the general file, and positions 48 through 51 record the subsystem ID. The valid range of data set numbers is 00 through 59, but they do not need to be either consecutive or sequentially ordered.

The data set numbers are used to mount or dismount the data sets. Each data set on a general file disk pack has to be mounted and dismounted separately by the operator. The mount function verifies that the data set number is in the volume label and makes the data set available to an online application program; the dismount function cancels that availability. A bypass option is provided to allow a data set to be mounted without checking the volume label for the data set number.

The system generation process does not place the data set numbers or subsystem ID in the volume label of a general file; rather, the information is placed there by a ZAGFL command. Therefore, the user must mount the data sets with the bypass option until a ZAGFL command is issued to place the necessary data in the label.

Application programs may access a mounted data set with any of the find or file macros, except find single (FINSC P/D) and file single (FILSC P/D), by specifying the GDS=Y parameter on the macro. FNSPC and FLSPC macros do not have a GDS parameter since the target module number is not part of the coded file address. A pseudo module number, constructed from the data set number, is used in place of a symbolic module number for I/O. The valid range of pseudo module numbers is defined at system generation, and is accessible to users in the CONKC macro fields @02GDF and @02GDA. Default pseudo module numbering starts at 230, and the range of pseudo module numbers will be 230 through 230+n for data set numbers 00 through n.

Relative record numbers are device independent; programs using this format do not have to be recorded or reassembled to change a general file from one device to another. Relative record numbering is sequential and starts with 0. Whichever address format the user chooses, records can be read or written either sequentially or randomly by record.

The RAISA macro is provided to increment file addresses in the MCHR and relative record formats by a user-specified count. It may be invoked by either online or offline segments. The generated code accounts for control bits and track overflow in performing the addition, and the result is returned to the caller in the specified data level. When RAISA is called from an offline program with a relative record number as input, a pointer to an 8-byte address suitable for Seek and Search I/O commands is also returned.

The status of a general file data set remains the same over a restart. If it is active at cycle-down time, it will be ready for use again when restart completes.

See z/TPF Operations for more information on these commands.