Using a data set name

Files are opened with a call to fopen() or freopen() in the format fopen("filename", "mode"). The following diagram shows the syntax for the filename argument on your fopen() or freopen() call:

Note: The single quotation marks in the filename syntax diagram must be matched; if you use one, you must use the other.

A sample construct is shown below:

   'qualifier1.qualifier2(member)'

//

Specifying these slashes indicates that the filename refers to a non-POSIX file or data set.

qualifier

Each qualifier is a 1- to 8-character name. These characters may be alphanumeric, national ($, #, @), or the hyphen. The first character should be either alphabetic or national. Do not use hyphens in names for RACF®-protected data sets.

You can join qualifiers with periods. The maximum length of a data set name is as follows:

Generally, 44 characters, including periods.
For a generation data group, 35 characters, including periods.

These numbers do not include a member name or GDG number and accompanying parentheses.

Specifying one or two ampersands before a single qualifier opens a temporary data set. Multiple qualifiers are not valid after ampersands, because the system generates additional qualifiers. Opening two temporary data sets with the same name creates two distinct files. If you open a second temporary data set using the same name as the first, you get a distinct data set. For example, the following statements open two temporary data sets:

   fp  = fopen("//&&myfile","wb+");
   fp2 = fopen("//&&myfile","wb+");

You cannot fully qualify a temporary data set name. The file is created at open time and is empty. When you close a temporary data set, the system removes it.

(member)

If you specify a member, the data set you are opening must be a PDS or a PDSE. For more information about PDSs and PDSEs, see Regular and extended partitioned data sets. For members, the member name (including trailing blanks) can be up to 8 characters long. A member name cannot begin with leading blanks. The characters in a member name may be alphanumeric, national ($, #, @), the hyphen, or the character X'C0'. The first character should be either alphabetic or national.

+number

-number

0

You specify a Generation Data Group (GDG) by using a plus (+) or minus (-) to precede the version number, or by using a 0. For more information about GDGs, see Generation data group I/O.

The Resource Access Control Facility (RACF) expects the data set name to have a high-level qualifier that is defined to RACF. RACF uses the entire data set name when it protects a tape data set.

When you enclose a name in single quotation marks, the name is fully qualified. The file opened is the one specified by the name inside the quotation marks. If the name is not fully qualified, z/OS® XL C/C++ does one of the following:

If your system does not use RACF, z/OS XL C/C++ does not add a high-level qualifier to the name you specified.
If you are running under TSO (batch or interactive), z/OS XL C/C++ appends the TSO user prefix to the front of the name. For example, the statement fopen("a.b","w"); opens a data set tsoid.A.B, where tsoid is the user prefix. If the name is fully qualified, z/OS XL C/C++ does not append a user prefix. You can set the user prefix by using the TSO PROFILE command with the PREFIX parameter.
If you are running under z/OS batch or IMS (batch or online), z/OS XL C/C++ appends the RACF user ID to the front of the name.

If you want your code to be portable between the VM/CMS and z/OS systems and between memory files and disk files, use a name of the format name1.name2, where name1 and name2 are up to 8 characters and are delimited by a period, or use a ddname. You can also add a member name.

For example, the following piece of code can run under Language Environment® for VM and z/OS Language Environment:

   FILE *stream;
   stream = fopen("parts.instock", "r");