Types of Input and Output

Table 9-2: Comparison of Binary and Human-Readable Input/Output
Category	Advantages	Disadvantages
Binary I/O	Binary I/O is the simplest and most efficient form of I/O. Binary data is more compact than ASCII data	Binary data is not always portable. Binary data files can only be moved easily to and from computers that share the same internal data representation. Binary data is not directly human readable, so you can’t type it to a workstation’s screen or edit it with a text editor.
ASCII I/O	ASCII data is very portable. It is easy to move ASCII data files to various computers, even computers running different operating systems, as long as they all use the ASCII character set. ASCII data can be edited with a text editor or typed to the workstation’s screen because it uses a human readable format.	ASCII I/O is slower than binary I/O because of the need to convert between the internal binary representation and the equivalent ASCII characters. ASCII data requires more space than binary data to store the same information.

The type of I/O you use is determined by considering the advantages and disadvantages of each method. Also, when transferring data to or from other programs or systems, the type of I/O is determined by the application. The following suggestions are intended to provide an idea of the issues involved, although there are always exceptions:

Data that needs to be human readable should be written using a human-readable character set. Two character sets are ASCII and EBCDIC; PV-WAVE assumes that you are using ASCII. The PV-WAVE routines for human-readable I/O are listed in "ASCII I/O—Free Format" and "ASCII I/O—Fixed Format".

Images and large data sets are usually stored and manipulated using binary I/O in order to minimize processing overhead. The ASSOC function is often the natural way to access such data, and thus is an important function to understand. The ASSOC function is discussed in "Associated Variable Input and Output".

Images stored in TIFF format can be transferred using DC_READ_TIFF and DC_WRITE_TIFF functions. Device Independent Bitmap (DIB) images can be transferred with DC_READ_DIB and DC_WRITE_DIB functions. Other images, either 8-bit or 24-bit, are transferred with the DC_READ_*_BIT and DC_WRITE_*_BIT functions, where the * represents either an 8 or a 24, depending on the type of image data that you have. The various DC routines that can be used to transfer image data are discussed in "Input and Output of Image Data".

Data that needs to be portable should be written using the ASCII character set. Another option is to use XDR (eXternal Data Representation) binary files by specifying the Xdr keyword with the OPEN procedures. This is especially important if you intend to exchange data between computers with markedly different internal binary data formats. XDR is discussed in "External Data Representation (XDR) Files".

For ASCII files, freely formatted I/O is easier to use than explicitly formatted I/O, and is almost as easy as binary I/O, so it is often a good choice for small files. Free format I/O is discussed in "Free Format Input and Output".

The easiest routines to use for the transfer of both images and formatted ASCII data are the DC_READ and DC_WRITE routines. They are easy to use because they automatically handle many aspects of data transfer, such as opening and closing the data file. The “DC” routines are introduced in the next section, "Functions for Simplified Data Connectivity".

PV-WAVE includes a group of I/O functions that begin with the two letters “DC”; this group of functions has been provided to simplify the process of getting your data in and out of PV-WAVE. This group of I/O functions does not replace the READ, WRITE, and PRINT commands, but does provide an easy-to-understand alternative for most I/O situations.

note	The DC_* routines that import and export ASCII data do not support the transfer of data into or from structures. An exception to this is the !DT, or date/time, structure. It is possible to transfer date/time data using DC_* routines.

The functions DC_READ_FREE and DC_READ_FIXED are well-suited for reading column-oriented data; there is no need to use the looping construct necessitated by other PV-WAVE procedures used for reading formatted data. The functions DC_WRITE_FREE and DC_WRITE_FIXED are equally well-suited for writing column-oriented ASCII data files. To see a figure showing a sample column-oriented file, refer to Figure 9-1: Typical File Organization, Column Oriented on page 171.

The DC functions are easy to use because they automatically handle many aspects of data transfer, such as opening and closing the data file. Another advantage of the DC I/O commands is that they recognize C-style format strings, even though all other PV-WAVE I/O routines recognize only FORTRAN-style format strings.

note	By default, DC_WRITE_FREE generates CSV (Comma Separated Value) ASCII data files, and the corresponding function, DC_READ_FREE, easily reads CSV files.

For specific information about any of the DC routines, refer to examples later in this chapter, or refer to individual function descriptions in the PV‑WAVE Reference. For information on the two routines used to perform DC routine error checking, refer to "Other I/O Related Routines".

Binary I/O transfers the internal binary representation of the data directly between memory and the file without any data conversion. Use it for transferring images or large data sets that require higher efficiency. Routines for Binary Input/Output shows the routines for binary I/O.

Table 9-3: Routines for Binary Input/Output
Function	Description
READU, READU_32	Read binary data from the specified file unit.
WRITEU	Write binary data to the specified file unit.
DC_WRITE_8_BIT DC_READ_8_BIT	Write (or read) binary 8-bit data to (or from) a file without having to explicitly choose a LUN.
DC_WRITE_24_BIT DC_READ_24_BIT	Write (or read) binary 24-bit data to (or from) a file without having to explicitly choose a LUN.
DC_WRITE_TIFF DC_READ_TIFF	Write (or read) TIFF image data. You do not have to explicitly choose a LUN.
ASSOC	Map an array definition to a data file, providing efficient and convenient direct access to binary data.
GET_KBRD	Read single characters from the keyboard.

You provide an explicit format string to control the exact format for the input or output of the data. For a column-oriented data file, with data going into more than one variable, this implies that the values in the input or output file line up in well-defined, fixed-width columns, as shown earlier in Figure 9-1: Typical File Organization, Column Oriented on page 171.

Because the data values end up being restricted to certain locations on the line, this style of I/O is called fixed format I/O. The exact format of the character data is specified to the I/O procedure using a format string (via the Format keyword). If no format string is given, default formats for each type of data are applied.

PV-WAVE uses default rules to format the data and uses delimiters to differentiate between different data values in the file. During input, the values in the file do not have to line up with one another because PV-WAVE is not imposing a rigid structure (format) on the file.

You do not have to decide how the data should be formatted because, in the case of input, PV-WAVE automatically looks for delimiters separating data values, and in the case of output, automatically places delimiters between adjacent data values. Because the values are “free” to be anywhere on the line, as long as they are clearly separated by delimiters, this style of I/O is called free format I/O.

For the routines listed in Freely Formatted ASCII I/O Routines, you do not have to provide a format string to transfer the data. (Because the values are all separated with delimiters, no format string is needed.) The free format I/O routines are discussed in more detail in "Free Format Input and Output".

Table 9-4: Freely Formatted ASCII I/O Routines
Procedure	Description
PRINT	Write ASCII data to the standard output file (LUN –1).
READ	Read ASCII data from the standard input file (LUN 0).
PRINTF READF	Write (or read) ASCII data to (or from) the specified LUN.
DC_WRITE_FREE DC_READ_FREE	Write (or read) ASCII data to (or from) a file without having to explicitly choose a LUN.

For the routines shown in Explicitly Formatted ASCII I/O Routines, you use the Format keyword to provide the format string used to transfer the data. The first routines listed (PRINT, READ, PRINTF, READF) recognize FORTRAN-like formats; the DC routines accept either C or FORTRAN format strings. The explicit format I/O routines are discussed in more detail in "Explicitly Formatted Input and Output".

Table 9-5: Explicitly Formatted ASCII I/O Routines
Procedure	Description
PRINT	Write ASCII data to the standard output file (LUN –1).
READ	Read ASCII data from the standard input file (LUN 0).
PRINTF READF	Write (or read) ASCII data to (or from) the specified LUN.
DC_WRITE_FIXED DC_READ_FIXED	Write (or read) ASCII data to (or from) a file without having to explicitly choose a LUN.

note	The STRING function can also generate ASCII output that is sent to a string variable instead of a file. For more information about the STRING function, refer to a later section, "Using the STRING Function to Format Data".

Table 9-6: Additional I/O Routines
Procedure	Description
GET_LUN FREE_LUN	Allocate and free LUNs.
FINDFILE	Locate files that match a file specification.
FLUSH	Ensure all buffered data for a LUN has actually been written to the file.
POINT_LUN LFPOINT_LUN	Position the file pointer.
EOF	Check for the end-of file condition.
INFO, /Files	Print information about open files.
FSTAT LFSTAT	Get detailed information about any LUN.
DC_ERROR_MSG	Returns the text string associated with the negative status code generated by a “DC” data import/export function that does not complete successfully.
DC_OPTIONS	Sets the error message reporting level for all “DC” import/export functions.

For additional information about DC_ERROR_MSG and DC_OPTIONS, refer to their descriptions in the PV‑WAVE Reference. For more information about the rest of the routines shown in the previous table, refer to a later section, "Miscellaneous File Management Tasks".