The I/O library routines apply options to a file connection for all related assign_objects.

If the assign_object is a unit, the application of options to the unit occurs whenever that unit becomes connected.

If the assign_object is a file name or pattern, the application of options to the file connection occurs whenever a matching file name is opened from a Fortran program.

When any of the previously listed library I/O routines open a file, they use assign options for any assign_object s which apply to this open request. Any of the following assign_objects or categories might apply to a given open request:

Options from the assign objects in these categories are collected to create the complete set of options used for any particular open. The options are collected in the listed order, with options collected later in the list of assign objects overriding those collected earlier.

The following is the syntax for the assign command:

The following two specifications cannot be used with any other options:

The following is a summary of the assign command options. For details, see the assign(1) and INTRO_FFIO(3f) man pages.

The following are the assign command attribute options:

Use one of the following formats for assign_object:

When the p: pattern form is used, the % and _ wildcard characters can be used. The % matches any string of 0 or more characters. The _ matches any single character. The % performs like the * when doing file name matching in shells. However, the % character also matches strings of characters containing the / character.

The ASSIGN(3f), ASNUNIT(3f), ASNFILE(3f), and ASNRM(3f) routines can be called from a Fortran program to access and update the assign environment. The ASSIGN routine provides an easy interface to ASSIGN processing from a Fortran program. The ASNUNIT and ASNFILE routines assign attributes to units and files, respectively. The ASNRM routine removes all entries currently in the assign environment.

The calling sequences for the assign library routines are as follows:

CALL ASSIGN (cmd,ier)

CALL ASNUNIT (iunit,astring,ier)

CALL ASNFILE (fname,astring,ier)

CALL ASNRM (ier)

A status of 0 indicates normal return and a status of greater than 0 indicates a specific error status. Use the explain command to determine the meaning of the error status. For more information about the explain command, see the explain(1) man page.

The following calls are equivalent to the assign -s u f:file command:

CALL ASSIGN('assign -s u f:file',ier)
CALL ASNFILE('file','-s u',IER)

The following call is equivalent to executing the assign -I -n 2 u:99 command:

IUN = 99
CALL ASNUNIT(IUN,'-I -n 2',IER)

The following call is equivalent to executing the assign -R command:

CALL ASNRM(IER)

The -a option specifies the actual file name to which a connection is made. This option allows files to be created in alternative directories without changing the FILE= specifier on an OPEN statement.

For example, consider the following assign command issued to open unit 1:

assign -a /tmp/mydir/tmpfile u:1

The program then opens unit 1 with any of the following statements:

WRITE(1) variable          ! implicit open
OPEN(1)                    ! unnamed open
OPEN(1,FORM='FORMATTED')   ! unnamed open

Unit 1 is connected to file /tmp/mydir/tmpfile. Without the -a attribute, unit 1 would be connected to file fort.1.

When the -a attribute is associated with a file, any Fortran open that is set to connect to the file causes a connection to the actual file name. An assign command of the following form causes a connection to file $TMPDIR/joe:

assign -a $TMPDIR/joe ftfile

This is true when any of the following statements are executed in a program:

OPEN(IUN,FILE='ftfile')
CALL AQOPEN(AQP,AQPSIZE,'ftfile',ISTAT)
CALL OPENMS('ftfile',INDARR,LEN,IT)
CALL OPENDR('ftfile',INDARR,LEN,IT)
CALL WOPEN('ftfile',BLOCKS,ISTATS)
WRITE('ftfile') ARRAY

If the following assign command is issued and is in effect, any Fortran INQUIRE statement whose FILE= specification is foo refers to the file named actual instead of the file named foo for purposes of the EXISTS=, OPENED=, or UNIT= specifiers:

assign -a actual f:foo

If the following assign command is issued and is in effect, the -a attribute does not affect INQUIRE statements with a UNIT= specifier:

assign -a actual ftfile

When the following OPEN statement is executed, INQUIRE(UNIT=n,NAME=fname) returns a value of ftfile in fname , as if no assign had occurred:

OPEN(n,file='ftfile')

The I/O library routines use only the actual file (-a) attributes from the assign environment when processing an INQUIRE statement. During an INQUIRE statement that contains a FILE= specifier, the I/O library searches the assign environment for a reference to the file name that the FILE= specifier supplies. If an assign-by-filename exists for the file name, the I/O library determines whether an actual name from the -a option is associated with the file name. If the assign-by-filename supplied an actual name, the I/O library uses the name to return values for the EXIST=, OPENED=, and UNIT= specifiers; otherwise, it uses the file name. The name returned for the NAME= specifier is the file name supplied in the FILE= specifier. The actual file name is not returned.

Fortran I/O uses the text file structure, unblocked file structure, pure file structure, F77 file structure, and COS blocked structure. By default, a file structure is selected for a unit based on the type of Fortran I/O selected at open time. If an alternative file structure is needed, the user can select a file structure by using the -s and -F options on the assign command.

No assign_object can have both -s and -F attributes associated with it. Some file structures are available as -F attributes but are not available as -s attributes. The -F option is more flexible than the -s option; it allows nested file structures and buffer size specifications for some attribute values. The following list summarizes how to select the different file structures with different options to the assign command:

assign -F cos
assign -s cos

assign -F text
assign -s text

assign -F system
assign -s unblocked
assign -s u

assign -F f77

For more information about file structures, see Chapter 7, “File Structures ”.

The following are examples of file structure selection:

The size of the buffer used for a Fortran file can have a substantial effect on I/O performance. A larger buffer size usually decreases the system time needed to process sequential files. However, large buffers increase a program's memory usage; therefore, optimizing the buffer size for each file accessed in a program on a case-by-case basis can help increase I/O performance and can minimize memory usage.

The -b option on the assign command specifies a buffer size, in blocks, for the unit. The -b option can be used with the -s option, but it cannot be used with the -F option. Use the -F option to provide I/O path specifications that include buffer sizes; the -b, and -u options do not apply when -F is specified.

For more information about the selection of buffer sizes, see Chapter 8, “Buffering”, and the assign (1) man page.

The following are some examples of buffer size specification using the assign -b and assign -F options:

The Fortran I/O library can read and write files with record blocking and data formats native to operating systems from other vendors. The assign -F command specifies a foreign record blocking; the assign -C command specifies the type of character conversion; the -N option specifies the type of numeric data conversion. When -N or -C is specified, the data is converted automatically during the processing of Fortran READ and WRITE statements. For example, assume that a record in file fgnfile contains the following character and integer data:

character*4 ch
integer int
open(iun,FILE='fgnfile',FORM='UNFORMATTED')
read(iun) ch, int 

Use the following assign command to specify foreign record blocking and foreign data formats for character and integer data:

assign -F ibm.vbs -N ibm -C ebcdic fgnfile

Fortran unformatted direct-access I/O supports number tuning and memory cache page size (buffer) tuning; it also supports specification of the prevailing direction of file access. The assign -b command specifies the size of each buffer in 4096-byte blocks.

The assign -T option activates or suppresses truncation after the writing of a sequential Fortran file. The -T on option specifies truncation; this behavior is consistent with the Fortran standard and is the default setting for most assign -s fs specifications.

The assign(1) man page lists the default setting of the -T option for each -s fs specification. It also indicates if suppression or truncation is allowed for each of these specifications.

FFIO layers that are specified by using the -F option vary in their support for suppression of truncation with -T off.

The following figure summarizes the available access methods and the default buffer sizes. Figures are given in units of 4096 bytes.

Figure 6-1. Access methods and default buffer size (IRIX systems)