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_objects 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:

UNICOS and UNICOS/mk systems:

assign [-I][-O][-a actualfile][-b bs][-c][-d bdr][-f fortstd][-l buflev][ -m setting][-n sz[:st]][-p partlist][-q ocblks][-r setting][-s ft][-t][-u bufcnt][-w setting][-x setting][-y setting][-C charcon][-D fildes][-F spec[,specs]][-L setting][-N numcon][-P scope][-R][-S setting][-T setting][-U  setting][-V][-W  setting][-Y  setting][-Z  setting]assign_object

IRIX systems:

assign [-a actualfile][-b bs][-f fortstd][-s ft][-t][-y setting][-B setting][-C charcon][-D fildes][-F spec[,specs]][-I][-N numcon][-O][-R][-S setting][-T setting][-U setting][-V][-W setting][-Y setting][-Z  setting]assign_object

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

assign -R [assign_object]

assign -V [assign_object]

The following is a summary of the assign command options. For details, see the assign(1) and INTRO_FFIO(3f) man pages. The assign command is implemented through the ASSIGN(3f), ASNFILE(3f), and ASNUNIT(3f) routines for Cray Research Programming Environment releases prior to 1.2.

The following are the assign command control options:

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])

IRIX systems: 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(blank) 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.

To allocate a file on an SSD-resident or memory-resident file system on a UNICOS system, you can use an assign command such as the following:

assign -a /ssd/myfile u: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 five different file structures: text structure, unblocked structure, bmx or tape, pure data structure and COS blocked structure on UNICOS and UNICOS/mk systems (on IRIX systems, the F77 blocked structure is used). 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 (the tape/bmx structure is not available on IRIX systems) :

assign -F cos
assign -s cos

assign -F text

assign -s text

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

assign -F tape
assign -F bmx
assign -s tape
assign -s bmx

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

File allocation can be specified with the -n, -c, and -p options to the assign command. The -n option specifies the amount of disk space to reserve at the time of a Fortran open. The -c and -p options specify the configuration of the allocated space, the -c option specifies contiguous allocation, and the -p option specifies striping (the file system partitions where file allocation will be tried) across disk devices.

There is no guarantee that blocks will actually be allocated on the specified partitions. The partlist argument can be one integer, a range of integers (m-n), a set of integers ( m:n), or a combination of ranges and sets separated by colons. The partition numbers are submitted directly through the ialloc(2) system calls. This option achieves file striping on the specified partition.

You cannot specify the -c and -p options without the -n option. The I/O library issues ialloc system calls to preallocate file space and to process the -c and -p attributes. The ialloc system call requires the -n attribute to determine the amount of file space to reserve.

For example, to specify file allocation on partitions 0 through 2, partition 4, and partitions 6 through 8, contiguous allocation in each partition, and a total of 100 4096-byte blocks of file space preallocated, you would enter the following command:

assign -p 0-2:4:6-8 -c -n 100 foo

The assign -F command has two specifications that alter the device where a file is resident. If you specify -F sds, a file will be SDS-resident; if you specify -F mr, a file will be memory resident. Because the sds and mr flexible file I/O layers do not define a record-based file structure, they must be nested beneath a file structure layer when record blocking is needed.

Examples of device allocation follow:

For more information about device allocation, see Chapter 9, “Devices”.

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, and the -u option specifies the number of buffers maintained for the connected file.

To open unit 1 for direct unformatted access and to specify 10 separate regions of the file that will be heavily accessed, use the following assign command:

assign -u 10 u:1

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. Use assign -T off to suppress truncation in applications in which GETPOS(3f) and SETPOS(3f) are used to simulate random access to a file that has sequential I/O.

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 for UNICOS systems.

Figure 6-1. Access methods and default buffer sizes (UNICOS systems)

The following figure summarizes the available access methods and the default buffer sizes for IRIX systems.

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