fopen() and freopen() parameters

Table 1 lists the parameters that are available on the fopen() and freopen() functions, tells you which ones are allowed and applicable for OS I/O, and lists the option values that are valid for the applicable ones. Detailed descriptions of these options follow the table.

recfm=

z/OS XL C/C++ allows you to specify any of the 27 possible RECFM types (listed in Fixed-format records, Variable-format records, and Undefined-format records), as well as the z/OS XL C/C++ RECFMs * and A.

When you are opening an existing file for read or append (or for write, if you have specified DISP=MOD), any RECFM that you specify must match that of the existing file, except that you may specify recfm=U to open any file for read, and you may specify recfm=FBS for a file created as recfm=FB. Specifying recfm=FBS indicates to z/OS XL C/C++ that there are no short blocks within the file. If there are, undefined behavior results.

For variable-format OS files, the RDW, SDW, and BDW contain the length of the record, segment, and block as well as their own lengths. If you open a file for read with recfm=U, z/OS XL C/C++ treats each physical block as an undefined-format record. For files created with recfm=V, z/OS XL C/C++ does not strip off block descriptor words (BDWs) or record descriptor words (RDWs), and for blocked files, it does not deblock records. Using recfm=U is helpful for viewing variable-format files or seeing how records are blocked in the file.

When you are opening an existing PDS or PDSE for write and you specify a RECFM, it must be compatible with the RECFM of the existing data set. FS and FBS formats are invalid for PDS members. For PDSs, you must use exactly the same RECFM. For PDSEs, you may choose to change the blocked attribute (B), because PDSEs perform their own blocking. If you want to read a PDS or PDSE directory and you specify a RECFM, it must be recfm=U.

Specifying recfm=A indicates that the file contains ASA control characters. If you are opening an existing file and you specify that ASA characters exist (>recfm=A) when they do not, the call to fopen() or freopen() fails. If you create a file by opening it for write or append, the A attribute is added to the default RECFM. For more information about ASA, see Using ASA text files.

Specifying recfm=* causes z/OS XL C/C++ to fill in any attributes that you do not specify, taking the attributes from the existing data set. This is useful if you want to create a new version of a data set with the same attributes as the previous version. If you open a data set for write and the data set does not exist, z/OS XL C/C++ uses the default attributes specified in fopen() defaults. This parameter has no effect when you are opening for read or append, and when you use it for non-DASD files.

recfm=+ is identical to recfm=* with the following exceptions:

• If there is no record format for the existing DASD data set, the defaults are assigned as if the data set did not exist.
• When append mode is used, the fopen() fails.

lrecl= and blksize=

The LRECL that you specify on the fopen() call defines the maximum record length that the C library allows. Records longer than the maximum record length are not written to the file. The first 4 bytes of each block and the first 4 bytes of each record of variable-format files are used for control information. For more information, see Variable-format records.

The maximum LRECL supported for fixed, undefined, or variable-blocked-spanned format sequential disk files is 32760. For other variable-length format disk files the maximum LRECL is 32756. Sequential disk files for any format have a maximum BLKSIZE of 32760. The record length can be any size when opening a spanned file and specifying lrecl=X. You can now specify lrecl=X on the fopen() or freopen() call for spanned files. If you are updating an existing file, the file must have been originally opened with lrecl=X for the open to succeed. lrecl=X is useful only for text, record I/O, and blocked I/O.

When you are opening an existing file for read or append (or for write, if you have specified DISP=MOD), any LRECL or BLKSIZE that you specify must match that of the existing file, except when you open an F or FB format file on a disk device without specifying the noseek parameter. In this case, you can specify the S attribute to indicate to z/OS XL C/C++ that the file has no imbedded short blocks. Files without short blocks improve z/OS XL C/C++'s performance.

BLKSIZE=0 will be ignored for an existing data set opened for read or append.

When you are opening an existing PDS or PDSE for write and you specify an LRECL or BLKSIZE, it must be compatible with the LRECL or BLKSIZE of the existing data set. For PDSs, you must use exactly the same values. For PDSEs, the LRECL must be the same, but the BLKSIZE may be different if you have changed the blocking attribute as described under the RECFM parameter above. You can change the blocking attribute, because PDSEs perform their own blocking. The BLKSIZE you choose should be compatible with the RECFM and LRECL. When you open the directory of a PDS or PDSE, do not specify LRECL or BLKSIZE; z/OS XL C/C++ uses the defaults. See Table 1 for more information.

space=(units,(primary,secondary,directory) [rlse | norlse])

This keyword enables you to specify the space parameters for the allocation of a z/OS data set. It applies only to z/OS data sets that you open by filename and do not already exist. If you open a data set by ddname, this parameter has no effect. You cannot specify any whitespace inside the value for the space keyword. You must specify at least one value with this parameter. Any parameter that you specify will be validated for syntax. If that validation fails, then the fopen() or freopen() will fail even if the parameter would have been ignored.

The supported values for units are as follows:

• Any positive integer indicating BLKSIZE
• CYL (mixed case)
• TRK (mixed case)

The primary quantity, the secondary quantity, and the directory quantity all must be positive integers. The primary quantity is always required.

If you specify values only for units and primary, you do not have to specify the inside set of parentheses. You can use a comma to indicate a quantity is to take the default value. For example:

     space=(cyl,(100,,10))  - default secondary value
     space=(trk,(100,,))    - default secondary and directory value
     space=(500,(100,))     - default secondary, no directory

The last parameter, rlse or norlse , controls the disposition of the unused space. If you open a new file for write and specify the space keyword, by default, any unused space will be released when the file is closed. You can preserve the allocated space by specifying norlse. For example:

space=(cyl,(100,,10),norlse)  - does not release unused space 
space=(trk,(100,,),rlse)      - releases unused space
pace=(500,(100,))             - releases unused space

You can specify only the values indicated on this parameter. If you specify any other values, fopen() or freopen() fails. Any values not specified are omitted on the allocation. These values are filled by the system during SVC 99 processing.

type=

You can omit this parameter. If you specify it, the valid values for OS I/O are type=record which opens a file for record I/O, and type=blocked which opens a file for blocked I/O.

acc=

This parameter is not valid for OS I/O. If you specify it, z/OS XL C/C++ ignores it.

password=

This parameter is not valid for OS I/O. If you specify it, z/OS XL C/C++ ignores it.

asis

If you use this parameter, z/OS XL C/C++ does not convert your filenames to upper case. The use of the asis parameter is strongly discouraged, because most of the I/O services used by z/OS XL C/C++ require uppercase filenames.

byteseek

When you specify this parameter and open a file in binary mode, all repositioning functions (such as fseek() and ftell()) use relative byte offsets from the beginning of the file instead of encoded offsets. In previous releases of z/OS XL C/C++, byteseeking was performed only for fixed format binary files. To have the byteseek parameter set as the default for all your calls to fopen() or freopen(), you can set the environment variable _EDC_BYTE_SEEK to Y. See Using environment variables for more information.

noseek

Specifying this parameter on the fopen() call disables the repositioning functions ftell(), fseek(), fgetpos(), and fsetpos() for as long as the file is open. When you have specified NOSEEK and have opened a disk file for read only, the only repositioning function allowed on the file is rewind(), if the device supports rewinding. Otherwise, a call to rewind() sets errno and raises SIGIOERR, if SIGIOERR is not set to SIG_IGN. Calls to ftell(), fseek(), fsetpos(), or fgetpos() return EOF, set errno, and set the stream error flag on.

The use of the noseek parameter may improve performance when you are reading and writing data sets.

Note: If you specify the NOSEEK parameter when you open a file for writing, you must specify NOSEEK on any subsequent fopen() call that simultaneously opens the file for reading; otherwise, you will get undefined behavior.

OS

If you specify this parameter, z/OS XL C/C++ ignores it.

abend= abend | recover

This parameter is ignored for SPC applications. The z/OS XL C/C++ runtime library uses the DCB ABEND exit to intercept abend conditions that occur during OS I/O operations. When an abend condition occurs, DFSMS issues a write-to-programmer message and gives control to the DCB ABEND exit. Within the information provided to the exit, a flag indicates if the abend condition can be ignored. It is not predictable when an abend condition can be ignored, and sometimes the same abend condition (completion code and reason code) can be ignored while at other times it cannot.

When the abend condition can be ignored, the runtime library instructs DFSMS to do so. This allows the runtime library to return gracefully back to the user code with a failing return value, errno set to 92 (meaning an I/O abend was trapped), and diagnostic information in the __amrc structure. DFSMS will have stopped processing the DCB. Only the fldata(), fclose(), and freopen() functions are permitted on the stream after an abend condition is trapped.

When the abend condition cannot be ignored, DFSMS issues the abend and Language Environment condition handling semantics take effect. If condition handling is active, the abend is converted to a Language Environment condition or SIGABND signal. In the absence of a condition handler or signal handler, the default behavior is to terminate the enclave. An application can write its own condition handler or SIGABND handler and try to recover from the error. As is the case when an abend condition can be ignored, DFSMS will have stopped processing the DCB and only the fldata(), fclose(), and freopen() functions are permitted on the stream.

abend

instructs the runtime library to ignore abend conditions that can be ignored. No attempt is made to recover from abend conditions that cannot be ignored.

recover

instructs the runtime library to attempt to recover from an abend issued during certain low-level I/O operations (WRITE / CHECK sequence and CLOSE). If recovery is possible, control will be returned to the user code with a failing return value, errno set to 92, and diagnostic information in the __amrc structure.

The abend keyword specifies the behavior only for the stream being opened. It overrides the setting of the _EDC_IO_ABEND environment variable. See Using environment variables for more information. Also, see Debugging I/O programs for more information on the __amrc structure and handling errors during I/O operations.