1
[Quoting from a C/370 manual, courtesy of Carl Forde.]
3
C/370 supports three types of input and output: text streams, binary
4
streams, and record I/O. Text and binary streams are both ANSI
5
standards; record I/O is a C/370 extension.
9
Record I/O is a C/370 extension to the ANSI standard. For files
10
opened in record format, C/370 reads and writes one record at a
11
time. If you try to write more data to a record than the record
12
can hold, the data is truncated. For record I/O, C/370 only allows
13
the use of fread() and fwrite() to read and write to the files. Any
14
other functions (such as fprintf(), fscanf(), getc(), and putc())
15
fail. For record-orientated files, records do not change size when
16
you update them. If the new data has fewer characters than the
17
original record, the new data fills the first n characters, where
18
n is the number of characters of the new data. The record will
19
remain the same size, and the old characters (those after) n are
20
left unchanged. A subsequent update begins at the next boundary.
21
For example, if you have the string "abcdefgh":
25
and you overwrite it with the string "1234", the record will look
30
C/370 record I/O is binary. That is, it does not interpret any of
31
the data in a record file and therefore does not recognize control
35
The record model consists of:
37
* A record, which is the unit of data transmitted to and from a
39
* A block, which is the unit of data transmitted to and from a
40
device. Each block may contain one or more records.
42
In the record model of I/O, records and blocks have the following
45
RECFM Specifies the format of the data or how the data is organized
46
on the physical device.
47
LRECL Specifies the length of logical records (as opposed to
50
BLKSIZE Specifies the length of physical records (blocks on the
54
Opening a File by Filename
56
The filename that you specify on the call to fopen() or freopen()
57
must be in the following format:
59
>> ----filename---- ----filetype--------------------
66
filename is a 1- to 8-character string of any of the characters,
67
A-Z, a-z, 0-9, and +, -, $, #, @, :, and _. You can separate it
68
from the filetype with one or more spaces, or with a period.
69
[Further note: filenames are fully case-sensitive, as in Unix.]
71
filetype is a 1- to 8-character string of any of the characters,
72
A-Z, a-z, 0-9, and +, -, $, #, @, :, and _. You can separate it
73
from the filemode with one or more spaces, or with a period. The
74
separator between filetype and filemode must be the same as the
75
one between filename and filetype.
77
filemode is a 1- to 2-character string. The first must be any of
78
the characters A-Z, a-z, or *. If you use the asis parameter on
79
the fopen() or freopen() call, the first character of the filemode
80
must be a capital letter or an asterisk. Otherwise, the function
81
call fails. The second character of filemode is optional; if you
82
specify it, it must be any of the digits 0-6. You cannot specify
83
the second character if you have specified * for the first one.
85
If you do not use periods as separators, there is no limit to how
86
much whitespace you can have before and after the filename, the
87
filetype, and filemode.
90
Opening a File without a File Mode Specified
92
If you omit the file mode or specify * for it, C/370 does one
93
of the following when you call fopen() or freopen():
95
* If you have specified a read mode, C/370 looks for the named file
96
on all the accessed readable disks, in order. If it does not find
97
the file, the fopen() or freopen() call fails.
98
* If you have specified any of the write modes, C/370 writes the file
99
on the first writable disk you have accessed. Specifying a write
100
mode on an fopen() or freopen() call that contains the filename of
101
an existing file destroys that file. If you do not have any
102
writable disks accessed, the call fails.
105
fopen() and freopen() parameters
108
CMS supports only two RECFMs, V and F. [note that MVS supports
109
27(!) different RECFMs.] If you do not specify the RECFM for a
110
file, C/370 determines whether is is in fixed or variable format.
113
For files in fixed format, CMS allows records to be read and
114
written in blocks. To have a fixed format CMS file treated as a
115
fixed blocked CMS file, you can open the file with recfm=fb and
116
specify the lrecl and blksize. If you do not specify a recfm on
117
the open, the blksize can be a multiple of the lrecl, and the
118
file is treated as if it were blocked.
120
For files in variable format, the CMS LRECL is different from the
121
LRECL for the record model. In the record model, the LRECL is
122
equal to the data length plus 4 bytes (for the record descriptor
123
word), and the BLKSIZE is equal to the LRECL plus 4 bytes (for
124
the block descriptor word). In CMS, BDWs and RDWs do not exist,
125
but because CMS follows the record model, you must still account
126
for them. When you specify V, you must still allocate the record
127
descriptor word and block descriptor word. That is, if you want
128
a maximum of n bytes per record, you must specify a minimum LRECL
129
of n+4 and a minimum BLKSIZE of n+8.
131
When you are appending to V files, you can enlarge the record size
132
dynamically, but only if you have not specified LRECL or BLKSIZE
133
on the fopen() or freopen() command that opened the file.
136
If you specify this parameter, the only valid value for CMS disk
137
files is type =record. This opens a file for record I/O.
140
If you use this parameter, you can open files with mixed-case
141
filenames such as JaMeS dAtA or pErCy.FILE. If you specify this
142
parameter, the file mode that you specify must be a capital letter
143
(if it is not an asterisk); otherwise; the function call fails and
144
the value returned is NULL.
147
Reading from Record I/O Files
148
fread() is the only interface allowed for reading record I/O files.
149
Each time you call fread() for a record I/O file, fread() reads
150
one record from the system. If you call fread() with a request for
151
less than a complete record, the requested bytes are copied to your
152
buffer, and the file position is set to the start fo the next
153
record. If the request is for more bytes that are in the record,
154
one record is read and the position is set to the start of the next
155
record. C/370 does not strip any blank characters or interpret any
158
fread() returns the number of items read successfully, so if you
159
pass a size argument equal to 1 and a count argument equal to the
160
maximum expected length of the record, fread() returns the length,
161
in bytes, of the record read. If you pass a size argument equal
162
to the maximum expected length of the record, and a count argument
163
equal to 1, fread() returns either 0 or 1, indicating whether a
164
record of length size read. If a record is read successfully but
165
is less than size bytes long, fread() returns 0.
168
Writing to Record I/O Files
169
fwrite() is the only interface allowed for writing to a file
170
opened for record I/O. Only one record is written at a time. If
171
you attempt to write more new data than a full record can hold or
172
try to update a record with more data than it currently has, C/370
173
truncates your output at the record boundary. When C/370 performs
174
a truncation, it sets errno and raises SIGIOERR, if SIGIOERR is not
177
When you are writing new records to a fixed-record I/O file, if you
178
try to write a short record, C/370 pads the record with nulls out
181
At the completion of an fwrite(), the file position is at the start
182
of the next record. For new data, the block is flushed out to the
183
system as soon as it is full.
187
When you call the fldata() function for an open CMS minidisk file,
188
it returns a data structure that looks like this:
191
unsigned int __recfmF : 1, /* fixed length records */
192
__recfmV : 1, /* variable length records */
193
__recfmU : 1, /* n/a */
194
__recfmS : 1, /* n/a */
195
__recfmBlk : 1, /* n/a */
196
__recfmASA : 1, /* text mode and ASA */
197
__recfmM : 1, /* n/a */
198
__dsorgPO : 1, /* n/a */
199
__dsorgPDSmem : 1, /* n/a */
200
__dsorgPDSdir : 1, /* n/a */
201
__dsorgPS : 1, /* sequential data set */
202
__dsorgConcat : 1, /* n/a */
203
__dsorgMem : 1, /* n/a */
204
__dsorgHiper : 1, /* n/a */
205
__dsorgTemp : 1, /* created with tmpfile() */
206
__dsorgVSAM : 1, /* n/a */
207
__reserve1 : 1, /* n/a */
208
__openmode : 2, /* see below 1 */
209
__modeflag : 4, /* see below 2 */
210
__reserve2 : 9, /* n/a */
212
char __device; __DISK
213
unsigned long __blksize, /* see below 3 */
214
__maxreclen; /* see below 4 */
215
unsigned short __vsamtype; /* n/a */
216
unsigned long __vsamkeylen; /* n/a */
217
unsigned long __vsamRKP; /* n/a */
218
char * __dsname; /* fname ftype fmode */
219
unsigned int __reserve4; /* n/a */
221
/* note 1: values are: __TEXT, __BINARY, __RECORD
222
note 2: values are: __READ, __WRITE, __APPEND, __UPDATE
223
these values can be added together to determine
224
the return value; for example, a file opened with
225
a+ will have the value __READ + __APPEND.
226
note 3: total block size of the file, including ASA
227
characters as well as RDW information
228
note 4: maximum record length of the data only (includes
229
ASA characters but excludes RDW information).
added
removed
proginfo/fileinfo.cms
