Basic terms

This section explains file processing terms that are often used in the description of the C input/output functions in the alphabetical reference.

Binary file

A binary file is an ordered sequence of bytes. Data written with the aid of C output functions is transferred to the file on a 1:1 basis. In contrast to text files, control characters for line feed and tabs are not rendered effective (see section “Text file”) but are mapped as corresponding EBCDIC values.
Data that is read from a binary file thus corresponds precisely to the data that was originally written to the file.

The following are binary files with stream I/O:

• cataloged PAM files

• temporary PAM files (INCORE)

• cataloged SAM files opened with fopen/fopen64 or freopen/freopen64 in binary mode.

The following are binary files with record I/O:

• cataloged ISAM files

• cataloged SAM files

• cataloged PAM files

if they have been opened in one of the following ways:

• with the fopen/fopen64 or freopen/freopen64 functions in binary mode and with the suffix "type=record".

• with the open/open64 or creat/creat64 functions and the O_RECORD specification.

Binary mode may be specified with the fopen/fopen64 or freopen/freopen64 functions and with the open/open64 or creat/creat64 functions, if O_RECORD is specified.

When you work with the ASCII variants of the input/output functions and binary files, you have to take the following into account:

Since the data is written to a binary file by means of C input functions and read out again in the same format by means of C output functions, changes may have to be made in the case of programs that work with binary files. This is true, for example, when it comes to the processing of text components. In the case of an ISAM file, for example, if the key was stored as an EBCDIC string, you have to ensure that EBCDIC code is not compared with ASCII code in a string comparison.

File descriptor

A file descriptor is a positive integer that is used to identify a file when elementary access operations are performed on it. It is assigned to a file when the file is opened (with open/open64, creat/creat64). Once assigned, the file descriptor is used as the file argument for all further access operations (read, write, close, tell, etc.).

When a program is started, the standard I/O files are automatically opened with the following file descriptors:

0	Standard input
1	Standard output
2	Standard error output

File pointer

A file pointer is a pointer to a structure of type FILE. It is used when processing a file by means of standard access functions (see <stdio.h>). A file pointer is provided for a file when it is opened (with fopen/fopen64, fdopen, freopen/freopen64). This pointer serves as the file argument for all further access operations (fprintf, fwprintf, fscanf, fclose, etc.) on the file.

When a program is started, the standard I/O files are automatically opened with the following file pointers:

stdin	(standard input)
stdout	(standard output)
stderr	(standard error output)

Elementary

Functions that process a file on the basis of file descriptors are referred to as "elementary". This is in contrast to the standard I/O functions, all of which operate on the basis of file pointers. In addition, the elementary functions allow SAM files to be processed as binary files only if O_RECORD is specified. Otherwise SAM files can also be processed as text files.

A number of other implementations (e.g. UNIX, SINIX) provide elementary functions in the form of system calls, which differ from standard functions by virtue of improved performance and greater operating system support. No such distinction is made between a system call and a function in BS2000.

FILE structure

As soon as a file is opened with fopen/fopen64, fdopen or freopen/freopen64, it is automatically assigned a specific structure of type FILE. This structure is defined in <stdio.h> and includes, among other things, the following information on the file:

• pointer to the I/O buffer

• buffer size

• position of the read/write pointer

• size of the file.

The file pointer returned by fopen/fopen64, fdopen or freopen/freopen64 points to this FILE structure.

Read/write pointer

The read/write pointer contains information on the current file position. Data is respectively read or written from this current position onwards.
The structure of information in the read/write pointer varies in accordance with the type of file:

• For binary files with stream I/O it corresponds to the number of bytes, calculated from the beginning of the file.

• For text files it contains information on the current record and the position within this record. The structure differs for SAM and ISAM files. The information is used internally by the runtime system.

• For binary files with record I/O it corresponds to the position after the last record to be read, written or deleted, or to the position reached by an immediately preceding positioning operation.
  For ISAM files with duplicate keys, the read/write pointer is positioned after the last record of a group having identical keys if one of these records has previously been read, written or deleted.

Buffering

For all output functions which write data to text files and binary files with stream I/O (printf, putc, fwrite etc.) the data is stored in an internal C buffer and only written to the external file when a specific event occurs. This event is different for text and binary files.

Text file:

1. A newline character (\n) is detected.

2. The maximum record length for a disk file is reached.

3. For data display terminals: output to the terminal is followed by input from the terminal.

4. The positioning functions fseek/fseek64, fsetpos/fsetpos64, rewind or lseek/lseek64 are called.

5. The fflush function is called; fflush is automatically executed internally when a file is closed (fclose, close) or when a program is terminated normally or with exit.

6. The file is closed.

7. Also, for ANSI functionality: If reading from any text file makes a data transfer necessary from the external file to the internal C buffer, the data of all the ISAM files still stored in buffers is automatically written out to the files.

Even if the data in the buffer does not terminate with a newline character, writing to the external file causes a change of line. Subsequent data is written to a new line (or to a new record).

Exception for ANSI functionality:
If the data of an ISAM file in the buffer does not terminate in a newline character, writing to the external file does not produce a change of line (or change of record).

Subsequent data lengthens the record in the file. When an ISAM file is read, therefore, only newline characters explicitly written by the program are read in.

Binary file:

1. The buffer is full

2. The positioning functions fseek/fseek64, fsetpos/fsetpos64, rewind or lseek/lseek64 are called

3. The fflush function is called (see text file above)

4. The file is closed.

No buffering is performed for INCORE files and or for files with record I/O.

Record-oriented input/output

Record-oriented input/output means that the read/write pointer of the file can only be positioned at the start of a record (or block). Using record-oriented input/output makes efficient file processing adapted to the structure of the BS2000 system possible. The unit for an input/output function call is a record (or block). Additional functions are available which can be used, e.g., to delete or insert records or to access the key in an ISAM file.

Record-oriented processing can be used for cataloged SAM, ISAM and PAM files. The files must be opened in one of the following ways:

• with the functions fopen/fopen64 or freopen/freopen64, qualified with "type=record" in the type parameter and always in binary mode.

• with the functions open/open64 or creat/creat64 and the specification of O_RECORD.
  Among other things, input/output functions which read in and output characters or character strings (up to \n) cannot be used on files with record I/O.

The following functions are used for processing files with record I/O:

close, creat/creat64, fopen/fopen64, freopen/freopen64, fclose, open/open64	Open, close
fread, fwrite, read, write	Read, write
fsetpos/fsetpo64, fgetpos/fgetpos64, flocate, fseek/fseek64, lseek/lseek64, rewind	Position
fdelrec	Delete record

The following functions for file management and error handling can be used unchanged:

feof, ferror, clearerr, unlink, remove, rename

In contrast to stream I/O, no data is buffered in the case of record I/O (see section “Buffering”).

Stream-oriented input/output

Stream-oriented input/output means that the read/write pointer can be positioned on each individual byte in the file. Stream I/O is the conventional processing mode and is set by default, i.e. without any special qualifiers specified for the open functions. Text files can be processed exclusively in this I/O mode.
In contrast to record I/O, the data for output to files with stream I/O is first stored in an internal C buffer and only later written to the external file (see section “Buffering”).

Text file

Text files are only possible for stream I/O.

The following file types are treated as text files:

• cataloged SAM files (no binary mode on open)

• cataloged ISAM files

• system files (SYSDTA, SYSOUT, SYSLST, SYSTERM).

A text file is an ordered sequence of bytes that are combined to form lines (or records). In contrast to binary files, the control characters for space are converted to their appropriate effect depending on the type of text file (see section “White space”). This means that data read from a text file does not correspond precisely to the data that was originally written to it. For a written tab (\t) an appropriate number of blanks is read.

The following points also apply to text files:

• Newline characters not originally written to the file may be read in (see fflush, fseek/fseek64, fsetpos/fsetpos64, lseek/lseek64, rewind).

• Output to SYSOUT and SYSTERM (for writing)
  Each line is started with a blank as a print control character. This causes a line feed.

• Output to SYSLST
  The line starts with a blank as the print control character only if none of the control characters \f, \v, \r or \b is specified in a line.

• The contents of a text file are always interpreted as a sequence of EBCDIC characters. When text files are processed using the ASCII variant of an I/O function (see "C library functions that support ASCII encoding"), the data is therefore converted internally as follows:

  • When data is written to the file, it is converted from ASCII to EBCDIC.

  • When data is read from the file, it is converted from EBCDIC to ASCII.

White space

The control characters for space and the backspace control character ’\b’ (cf. table below) are evaluated by all output functions which write to text files and receive as the argument the control character either as a character constant (starting with \) or as a numerical EBCDIC value.
The decimal or hexadecimal values of the control characters are given in the C and C++ User Guides (EBCDIC table).

Key to table:

X	The control character is converted to its appropriate effect
blank	The control character is written to the file as a text character (EBCDIC value)

	\n	\t	\f	\v	\r	\b
SAM/ISAM	X	X
SYSOUT/SYSTERM	X	X	X
SYSLST	X	X	X	X	X	X

Tab (\t)

The tab character is converted to the corresponding number of spaces. Tab positions are spaced 8 columns apart (1, 9, 17, ...). Spaces are substituted for the tab character when read in.

With SAM and ISAM files, the tab character is converted to spaces by default only when KR functionality has been selected, not for ANSI functionality (see additional specification option "tabexp" for the fopen/fopen64, freopen/freopen64 functions).
KR functionality applies to C/C++ versions prior to V3.0 only.

Line feed (\n)

The newline character is converted to a change of line (change of record). Subsequent read functions then supply a newline character for a change of record.

Page feed (\f)

SYSLST: A page feed is executed and subsequent data is output on a new page. SYSOUT, SYSTERM for writing: The message "please acknowledge" is output at the data display terminal.

Vertical tab (\v)

An appropriate number of blank lines is output to reach the next line tab position. These tab positions are 8 lines apart (1, 9, 17, ...).

Carriage return (\r)

There is no line feed and the cursor is returned to the start of the current line, i.e. subsequent data is written to the same line. This enables characters to be underlined, for example.

Backspace (\b)

The next character is written to the position of the previous character. This allows a letter to be provided with an accent, for example. Strictly speaking, \b is not a white space character (cf. isspace) but a control character (cf. iscntrl).

\r and \b are effective only in conjunction with printers equipped with the overwrite function.