The blankx or blx layer performs blank compression and expansion on a stream of 8-bit characters. The syntax for this layer is as follows:

blankx[.type]:[num1]:[num2]

blx[.type]:[num1]:[num2]

The keyword specification for this layer is as follows:

blankx.[type][.blxchr=num1][.blnk=num2]

blx.[type][.blxchr=num1][.blnk=num2]

The type field can have one of the following three values:

The num1 field contains the decimal value of the ASCII character used as the escape code to control the blank compression.

The num2 field contains the decimal value of the ASCII character that is the object of the compression. This is usually the ASCII blank (0x20).

The bmx or tape layer handles the interface to online magnetic tapes. The bmx layer uses the tape list I/O interface on Cray Research systems.

For information about the tmf layer on IRIX systems, see the IRIX TMF User's Guide.

A magnetic tape does not use control words to delimit records and files; however, control words are part of the physical representation of the data on the medium. On a magnetic tape, each tape block is considered a record.

The following is the syntax for this layer:

bmx:[num1]:[num2]

tape:[num1]:[num2]

The keyword specification is as follows:

bmx[.bufsize=num1][.num_buffers=num2]

tape[.bufsize=num1][.num_buffers=num2]

The num1 argument specifies the size in 512-word blocks for each buffer. The num2 argument specifies the number of buffers to use.

The bmx layer may be used with ER90 files that have been mounted in blocked mode. The ER90 device places restrictions on the amount of data that can be written to a tape block; see the Tape Subsystem User's Guide, for details.

Table 14-3 describes the EOF and EOD behavior of the bmx layer.

The EOF label is always considered an EOD. For unlabeled tapes without the -T option specified, nothing can be considered an EOF. The double tape mark shows the EOD. For unlabeled tapes specified with -T, nothing can be considered an EOD and every tape mark is returned as an EOF.

No optional fields are permitted.

Lower-level layers are not allowed. Exact implementation depends on operating system and hardware platform.

The bufa layer provides library-managed asynchronous buffering. This can reduce the number of low-level I/O requests for some files. The syntax is as follows:

bufa:[num1]:[num2]

The keyword syntax is as follows:

bufa[.bufsize=num1][.num_buffers=num2]

The num1 argument specifies the size, in 4096-byte blocks, of each buffer. The default buffer size depends on the device where your file is located. The maximum allowed value for num1 on IRIX systems is 32,767. The maximum allowed value on UNICOS and UNICOS/mk systems 1,073,741,823. You may not, however, be able to use a value this large because this much memory may not be available.

The num2 argument specifies the number of buffers. The default is 2.

The c205 layer performs blocking and deblocking of the native type for the CDC CYBER 205 or ETA computer systems. The general format of the specification follows:

c205.w:[recsize]:[bufsize]

The keyword specification follows:

c205.w[.bufsize=num2]

The w is CYBER 205 W-type records and must be specified. The recsize field should not be specified because it is reserved for future use as a maximum record size. The bufsize refers to the working buffer size for the layer and should be specified as a nonnegative decimal number (in bytes).

To achieve maximum performance, ensure that the working buffer size is large enough to completely hold any records that are written, plus the control words. Control words consist of 8 bytes per record. If a record plus control words is written larger than the buffer, the layer must perform some inefficient operations to do the write. If the buffer is large enough, these operations are avoided.

On reads, the buffer size is not as important, although larger sizes usually perform better.

If the next lower-level layer is magnetic tape, this layer does not support I/O.

The cache layer allows recently accessed parts of a file to be cached either in main memory or in a secondary data segment (SDS). This can significantly reduce the number of low-level I/O requests for some files that are accessed randomly. This layer also offers efficient sequential access when a buffered, unblocked file is needed. The syntax is as follows:

cache[.type]:[num1]:[num2][num3]

The following is the keyword specification:

cache[.type][.page_size=num1][.num_pages=num2
[.bypass_size=num3]]

The type argument can be either mem or sds (.sds is not allowed on IRIX systems or on CRAY T3E systems). mem directs that cache pages reside in main memory; sds directs that the pages reside in secondary data segments (SDS). num1 specifies the size, in 4096-byte blocks, of each cache page buffer. The default is 8. The maximum allowed value for num1 on IRIX systems is 32,767. The maximum allowed value on UNICOS and UNICOS/mk systems 1,073,741,823. You may not, however, be able to use a value this large because this much memory may not be available.

num2 specifies the number of cache pages. The default is 4. num3 is the size in 4096-byte blocks at which the cache layer attempts to bypass cache layer buffering. If a user's I/O request is larger than num3, the request might not be copied to a cache page. The default size for num3 on IRIX systems is num3=num1. On UNICOS and UNICOS/mk systems, the default is num3=num1×num2.

When a cache page must be preempted to allocate a page to the currently accessed part of a file, the least recently accessed page is chosen for preemption. Every access stores a time stamp with the accessed page so that the least recently accessed page can be found at any time.

The cachea layer allows recently accessed parts of a file to be cached either in main memory or in a secondary data segment (SDS). This can significantly reduce the number of low-level I/O requests for some files that are accessed randomly.

This layer can provide high write performance by asynchronously writing out selective cache pages. It can also provide high read performance by detecting sequential read access, both forward and backward. When sequential access is detected and when read-ahead is chosen, file page reads are anticipated and issued asynchronously in the direction of file access. The syntax is as follows:

cachea[type]:[num1]:[num2]:[num3]:[num4]

The keyword syntax is as follows:

cachea[type][.page_size=num1][.num_pages=num2][.max_lead=num3][.shared_cache=num4]

Multiple cachea layers in a chain may not contain the same nonzero cache number.

On IRIX systems, stacked shared cachea layers are not supported. On UNICOS and UNICOS/mk systems, stacked shared layers are supported, but in multitasked programs, different files must not mix the order of the shared caches.

The following examples demonstrate this functionality:

The cdc layer handles record blocking for four common record types from the 60-bit CYBER 6000 and 7000 series computer systems, which run the CDC 60-bit NOS, NOS/VE, or SCOPE operating system. The general format of the specification follows:

cdc[.recfmt].[tpfmt]

There is no alternate keyword specification for this layer.

The supported recfmt values are as follows:

The tpfmt field can have one of the following three values that indicate the presence of block trailers and other low-level characteristics.

---

Note: The i and si fields require a lower-level layer that handles records. A stream model in the lower-level layers does not work. The disk field requires a lower layer that handles records when endfile makes exist prior to the end of data.

---

The cos layer performs COS blocking and deblocking on a stream of data. The general format of the cos specification follows:

cos:[.type][.num1]

The format of the keyword specification follows:

cos[.type][.bufsize=num1]

The num1 argument specifies the working buffer size in 4096-byte blocks.

If not specified, the default buffer size is the larger of the following: the large I/O size (UNICOS and UNICOS/mk systems only); the preferred I/O block size (see the stat(2) man page for details), or 48 blocks. See the INTRO_FFIO(3f) man page for more details.

When writing, full buffers are written in full record mode, specifically so that the magnetic tape bmx layer can be used on the system side to read and write COS transparent tapes. To choose the block size of the tape, select the buffer size.

Reads are always performed in partial read mode; therefore, you do not have to know the block size of a tape to read it (if the tape block size is larger than the buffer, partial mode reads ensure that no parts of the tape blocks are skipped).

---

Note: seek operations are supported only to allow for rewind (seek(fd,0,0)), seek-to-end (seek(fd,0,2)) and a GETPOS(3f) or SETPOS(3f) operation, where the position must be on a record boundary.

---

GETPOS(3f) and SETPOS(3f) are not available on IRIX systems.

The er90 layer is not supported on IRIX systems or on CRAY T3E systems. It is available only on UNICOS systems.

The er90 layer handles the interface to the ER90 files. No arguments are accepted.

Lower-level layers are not allowed.

The event layer monitors I/O activity (on a per-file basis) which occurs between two I/O layers. It generates statistics as an ASCII log file and reports information such as the number of times an event was called, the event wait time, the number of bytes requested, and so on. You can request the following types of statistics:

Statistics are reported to stderr by default. The FF_IO_LOGFILE environment variable can be used to name a file to which statistics are written by the event layer. The default action is to overwrite the existing statistics file if it exists. You can append reports to the existing file by specifying a plus sign (+) before the file name, as in this example:

setenv FF_IO_LOGFILE +saveIO

This layer report counts for read, reada, write, and writea. These counts represent the number of calls made to an FFIO layer entry point. In some cases, the system layer may actually use a different I/O system call, or multiple system calls. For example, the reada system call does not exist on IRIX systems, and the system layer reada entry point will use aio_read().

On IRIX systems, amention of the lock layer may be included during report generation even though that layer may not have been specified by the user.

On CRAY T3E systems, if more than one PE is using the event layer, and you set the FF_IO_LOGFILE environment variable, you must use the plus sign (+) before the file name to prevent PE a from overwriting the information written by PE b. Using the plus sign also means that the information will be appended to an existing file.

On CRAY T3E systems, you can also use the FF_IO_LOGFILEPE environment variable to name a file to which statistics are written. The file name will be x.n, where x is the name specified by the environment variable and n is the number of the PE which wrote the file. The default action is to overwrite the existing file. To append information to an existing file, specify a plus sign (+) before the file name.

The event layer is enabled by default and is included in the executable file; you do not have to relink to study the I/O performance of your program. To obtain event statistics, rerun your program with the event layer specified on the assign command, as in this example:

assign -F bufa, event, cachea, event, system

The syntax for the event layer is as follows:

event[.type]

There is no alternate keyword specification for this layer.

The type argument selects the level of performance information to be written to the ASCII log file; it can have one of the following values:

The f77 layer handles blocking and deblocking of the f77 record type, which is common to most UNIX Fortran implementations. The syntax for this layer is as follows:

f77[.type]:[num1]:[num2]

The following is the syntax of the keyword specification:

f77[.type][.recsize=num1][.bufsize=num2]

The type argument specifies the record type and can take one of the following two values:

The num1 field refers to the maximum record size. The num2 field refers to the working buffer size.

To achieve maximum performance, ensure that the working buffer size is large enough to hold any records that are written plus the control words (control words consist of 8 bytes per record). If a record plus control words are larger than the buffer, the layer must perform some inefficient operations to do the write. If the buffer is large enough, these operations can be avoided.

On reads, the buffer size is not as important, although larger sizes will usually perform better.

If the next lower-level layer is magnetic tape, this layer does not support I/O.

The fd layer allows connection of a FFIO file to a system file descriptor. You must specify the fd layer, as follows:

fd:[num1]

The keyword specification is as follows:

fd[
.file_descriptor=num1]

The num1 argument must be a system file descriptor for an open file. The ffopen or ffopens request opens a FFIO file descriptor that is connected to the specified file descriptor. The file connection does not affect the file whose name is passed to ffopen.

All other properties of this layer are the same as the system layer. See “The system Layer”, for details.

The global layer is a caching layer that distributes data across all multiple SHMEM or MPI processes. Open and close operations require participation by all processes which access the file; all other operations are independently performed by one or more processes.

The following is the syntax for the global layer:

global[. type]:[num1]:[num2]

The following is the syntax for the keyword specification:

global[. type][.page_size=num1][.num_pages=num2]

The type argument can be privpos (default), in which is the file position is private to a process or globpos (deferred implementation), in which the file position is global to all processes.

The num1 argument specifies the size in 4096-byte blocks of each cache page. num2 specifies the number of cache pages to be used on each process. If there are n processes, then n×num2 cache pages are used.

num2 buffer pages are allocated on every process which shares access to a global file. File pages are direct-mapped onto processes such that page n of the file will always be cached on process (n mod NPES), where NPES is the total number of processes sharing access to the global file. Once the process is identified where caching of the file page will occur, a least-recently-used method is used to assign the file page to a cache page within the caching process.

The ibm layer handles record blocking for seven common record types on IBM operating systems. The general format of the specification follows:

ibm.[type]:[num1]:[num2]

The keyword specification follows:

ibm[.type][.recsize=num1][.mbs=num2]

The supported type values are as follows:

The f format is fixed-length record format. For fixed-length records, num1 is the fixed record length (in bytes) for each logical record. Exactly one record is placed in each block.

The fb format records are the same as f format records except that you can place more than one record in each block. num1 is the length of each logical record. num2 must be an exact multiple of num1.

The v format records are variable-length records. recsize is the maximum number of bytes in a logical record. num2 must exceed num1 by at least 8 bytes. Exactly one logical record is placed in each block.

The vb format records are variable-length blocked records. This means that you can place more than one logical record in a block. num1 and num2 are the same as with v format.

The vbs format records have no limit on record size. Records are broken into segments, which are placed into one or more blocks. num1 should not be specified. When reading, num2 must be at least large enough to accommodate the largest physical block expected to be encountered.

The num1 field is the maximum record size that may be read or written. The vbs record type ignores it.

The num2 (maximum block size) field is the maximum block size that the layer uses on reads or writes.

The memory-resident (mr) layer lets users declare that a file should reside in memory. The mr layer tries to allocate a buffer large enough to hold the entire file.

The options are as follows:

mr[.type[.subtype]]:num1:num2:num3

The keyword specification is as follows:

mr[.type[.subtype]][.start_size=num1][.max_size=num2]
[.inc_size=num3]

The type field specifies whether the file in memory is intended to be saved or is considered a scratch file. This argument accepts the following values:

The subtype field specifies the action to take when the data can no longer fit in the allowable memory space. It accepts the following values:

The num1, num2, and num3 fields are nonnegative integer values that state the number of 4096-byte blocks to use in the following circumstances:

The num1 and num3 fields represent best-effort values. They are intended for tuning purposes and usually do not cause failure if they are not satisfied precisely as specified (for example, if the available memory space is only 100 blocks and the chosen num3 value is 200 blocks, growth is allowed to use the 100 available blocks rather than failing to grow, because the full 200 blocks requested for the increment are unavailable).

When using the mr layer, large memory-resident files may reduce I/O performance for sites that provide memory scheduling that favors small processes over large processes. Check with your system administrator if I/O performance is diminished.

---

Caution:: Use of the default value for the max parameter can cause program failure if the file grows and exhausts the entire amount of memory available to the process. If the file size might become quite large, always provide a limit.

---

Memory allocation is done by using the malloc(3c) and realloc(3c) library routines. The file space in memory is always allocated contiguously.

When allocating new chunks of memory space, the num3 argument is used in conjunction with realloc as a minimum first try for reallocation.

The nosve layer handles record blocking for five common record types on CDC NOS/VE operating systems.

The general format of the specifications is as follows:

nosve[.type]:[num1]:[num2]

The format of the keyword specifications is as follows:

nosve[.type][.recsize=num1][.mbs=num2]

The supported type fields follow:

The num1 field is the maximum record size that can be read or written. The s and v record types ignore it.

For the nosve.v format, the working buffer size can affect performance. If the buffer size is at least as large as the largest record that will be written, the system overhead is minimized. For the nosve.u record format, num1 and num2 are the same thing. For nosve.f and nosve.d records, the maximum block size must be at least as large as the maximum record size. You can place more than one record in a block.

For nosve.s records, one or more segments are placed in each block (a record is composed of one or more segments).

The null layer is a syntactic convenience for users; it has no effect. This layer is commonly used to simplify the writing of a shell script when a shell variable is used to specify a FFIO layer specification. For example, the following is a line from a shell script with a tape file using the assign command and overlying blocking is expected on the tape (as specified by BLKTYP):

assign -F $BLKTYP,bmx fort.1

If BLKTYP is undefined, the illegal specification list ,bmx results. The existence of the null layer lets the programmer set BLKTYP to null as a default, and simplify the script, as in the following:

assign -F null,bmx fort.1

This is identical to the following command:

assign -F bmx fort.1

The sds layer is not available on CRAY T3E systems or on IRIX systems.

The sds layer lets users declare that a file should reside on SDS. The specification for this layer follows:

sds[.type:[subtype]]:[num1]:[num2]:[num3]

The keyword specification is as follows:

sds[.type[.subtype]][.start_size=num1][.max_size=num2]
[.inc_size=num3]

The type field specifies whether the file to reside in SDS is intended to be saved. This field can have the following values:

The subtype field specifies the action to take when the data can no longer fit in the allowable SDS space. It can have the following values:

The num1, num2, and num3 fields are nonnegative integer values that state the number of 4096-byte blocks to use in the following circumstances.

The num1 and num3 fields are used for tuning purposes and usually do not fail if they are not used precisely as specified. For example, if the available SDS space is only 100 blocks, and the chosen increase (num3) value is 200 blocks, growth is allowed to use the 100 available blocks instead of failing to grow (because the full 200 blocks requested for the increment are unavailable). Similarly, the num3 value of 200 implies allocation in minimum size chunks of 200 blocks. If 200 blocks of contiguous space is unavailable, the allocation is satisfied with whatever space is available.

The specification for sds is equivalent to the following specification:

sds.save.ovfl:0:35184372088832:256

Overflow is provided when the requested data cannot completely reside in SDS. This can occur either because the SDS space requested from the system is not available or because the num2 (maximum size) argument was specified.

When overflow occurs, a message prints to standard error stating the file name and the overflow size. The overflow I/O to the next lower layer depends on the type argument. If save is specified, the sds layer assumes that the part of the file that resides in SDS must eventually be written to the lower-level layer (usually disk).

The overflowed data is written to the lower-level layer at a position in the file that corresponds to the position it will occupy after the SDS-resident data is flushed. Space is reserved at overflow time in the file to accommodate the SDS resident part of the file.

If the scr option is selected, the SDS resident part of the file is considered disposable. Space for it is not reserved in the file on the lower-level layer. The overflow operations behave as though the first overflowed bit in the file is bit 0 of the lower-level layer, as in the following example:

# requests a max of 1 512-word block of SDS
assign -F sds.save.ovfl:0:1 fort.1

Assume that the file does not initially exist. The initial SDS size is 0 blocks, and the size is allowed to grow to a maximum of 1 block. If a single write of 513 words was done to this file, the first 512 words are written to SDS. The remaining word is written to file fort.1 at word position 512.

Words 0 through 511 are not written until the sds layer is closed and the SDS data is flushed to the lower-level layer. Immediately after the write completes, SDS contains 512 words, and fort.1 consists of 513 words. Only the last word contains valid data until the file is closed.

If the assign command is of the following form, it is assumed that the entire file is disposable if 513 words are written to the file:

# requests a max of 1 512-word block of SDS
assign -F sds.scr.ovfl:0:1 fort.1

It is not necessary to reserve space in fort.1 for the SDS data. When the 513 words are written to the file, the first 512 words are written to SDS. The 513th word is written to word 0 of fort.1. After the completion of the write, fort.1 consists of 1 word. The fort.1 file is deleted when the file is closed.

SDS allocation is done through the sdsalloc(3f) library routine. The file space in SDS is allocated (as far as possible) in a contiguous manner, but if contiguous space is not found, any available fragments are used before overflow is forced on any file.

When allocating new chunks of SDS space, the num3 argument is used as a minimum first try for allocation.

The syscall layer directly maps each request to an appropriate system call. The layer does not accept any options on UNICOS or UNICOS/mk systems. On IRIX systems, it has one optional parameter, as follows:

syscall[.cboption]

The cboption argument can have one of the following values:

Lower-level layers are not allowed.

The system layer is implicitly appended to all specification lists, if not explicitly added by the user (unless the syscall, tape, er90, or fd layer is specified). It maps requests to appropriate system calls.

If the file that is opened is a tape file, the system layer becomes the tape layer.

For a description of options, see the syscall layer. Lower-level layers are not allowed.

The text layer performs text blocking by terminating each record with a newline character. It can also recognize and represent the EOF mark. The text layer is used with character files and does not work with binary data. The general specification follows:

text[.type]:[num1]:[num2]

The keyword specification follows:

text[.type][.newline=num1][.bufsize=num2]

The type field can have one of the following three values:

The num1 field is the decimal value of a single character that represents the newline character. The default value is 10 (octal 012, ASCII line feed).

The num2 field specifies the working buffer size (in decimal bytes). If any lower-level layers are record oriented, this is also the block size.

The user and site layers let users and site administrators build layers that meet specific needs. The syntax follows:

user[num1]:[num2]

site:[num1]:[num2]

The open processing passes the num1 and num2 arguments to the layer and are interpreted by the layers.

See "Creating a user Layer," Chapter 15, “Creating a user Layer ” for an example of how to create an FFIO layer.

The vms layer handles record blocking for three common record types on VAX/VMS operating systems. The general format of the specification follows.

vms.[type.subtype]:[num1]:[num2]

The following is the alternate keyword specification for this layer:

vms.[type.subtype][.recsize=num1][.mbs=num2]

The following type values are supported:

In addition to the record type, you must specify a record subtype, which has one of the following four values:

The num1 field is the maximum record size that may be read or written. It is ignored by the s record type.

The num2 field is the maximum segment or block size that is allowed on input and is produced on output. For vms.f.tr and vms.f.bb, num2 should be equal to the record size (num1). Because vms.f.tape places one or more records in each block, vms.f.tapenum2 must be greater than or equal to num1.

For vms.v.bb and vms.v.disk records, num2 is a limit on the maximum record size. For vms.v.tape records, it is the maximum size of a block on tape; more specifically, it is the maximum size of a record that will be written to the next lower layer. If that layer is tape, num2 is the tape block size. If it is cos, it will be a COS record that represents a tape block. One or more records are placed in each block.

For segmented records, num2 is a limit on the block size that will be produced. No limit on record size exists. For vms.s.tr and vms.s.bb, the block size is an upper limit on the size of a segment. For vms.s.tape, one or more segments are placed in a tape block. It functions as an upper limit on the size of a segment and a preferred tape block size.