Chapter 6. The assign Environment

Fortran programs require the ability to alter many details of a Fortran file connection. You may need to specify device residency, an alternative file name, a file space allocation scheme, file structure, or data conversion properties of a connected file.

This chapter describes the assign(1) command and the ASSIGN(3f) library routine, which are used for these purposes. The ffassign command provides an interface to assign processing from C. See the ffassign man page for details about its use.

assign Basics

The assign(1) command passes information to Fortran OPEN statements and to the ffopen(3c), AQOPEN(3f), WOPEN(3f), OPENDR(3f), and OPENMS(3f) routines.

This information is called the assign environment; it consists of the following elements:

  • A list of unit numbers

  • File names

  • File name patterns that have attributes associated with them

Any file name, file name pattern, or unit number to which assign options are attached is called an assign_object. When the unit or file is opened from Fortran, the options are used to set up the properties of the connection.

Open Processing

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:

  • g:all options apply to any open request.

  • g:su, g:sf, g:du, , and g:ff each apply to types of open requests (for example, sequential unformatted, sequential formatted, and so on).

  • u:unit_number applies whenever unit unit_number is opened.

  • p:pattern applies whenever a file whose name matches pattern is opened. The assign environment can contain only one p: assign_object which matches the current open file. The exception is that the p:%pattern (which uses the % wildcard character) is silently ignored if a more specific pattern also matches the current filename being opened.

  • f:filename applies whenever a file with the name filename is opened.

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 assign Command

The following is the syntax for the assign command:

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.


Specifies an incremental assign. All attributes are added to the attributes already assigned to the current assign_object . This option and the -O option are mutually exclusive.


Specifies a replacement assign. This is the default control option. All currently existing assign attributes for the current assign_object are replaced. This option and the -I option are mutually exclusive.


Removes all assign attributes for assign_object. If assign_object is not specified, all currently assigned attributes for all assign_object s are removed.


Views attributes for assign_object. If assign_object is not specified, all currently assigned attributes for all assign_objects are printed.

The following are the assign command attribute options:

-a actualfile

The FILE= specifier or the actual file name.

-b bs

Library buffer size in 4096-byte blocks.

-f fortstd

Fortran standard.

Specify 77 to be compatible with the FORTRAN 77 standard.

Specify 90 to be compatible with the Fortran 90 standard.

Specify irixf77 to be compatible with SGI's FORTRAN 77 compiling system which runs on IRIX systems.

Specify irixf90 to be compatible with the MIPSpro 7 Fortran 90 compiler.

-s ft

File type. Enter text, cos, blocked, unblocked, u, sbin, or bin for ft.


Temporary file.

-y setting

Suppresses repeat counts in list-directed output. setting can be either on or off . The default setting is off.

-B setting

Activates or suppresses the passing of the O_DIRECT flag to the open(2) system call. Enter either on or off for setting.

-C charcon

Character set conversion information. Enter ascii for charcon. If you specify the -C option, you must also specify the -F option.

-D fildes

Specifies a connection to a standard file. Enter stdin, stdout, or stderr for fildes.

-F spec [, specs]

Flexible file I/O (FFIO) specification. See the assign(1) man page for details about allowed values for spec and for details about hardware platform support. See the INTRO_FFIO(3f) man page for details about specifying the FFIO layers.

-N numcon

Foreign numeric conversion specification. See the assign(1) man page for details about allowed values for numcon and for details about hardware platform support.

-S setting

Suppresses use of a comma as a separator in list-directed output. Enter either on or off for setting. The default setting is off.

-T setting

Activates or suppresses truncation after write for sequential Fortran files. Enter either on or off for setting.

-U setting

Produces a form of list-directed output. This is a global setting which sets the value for the -y, -S, and -W options. Enter either on or off for setting. The default setting is off.

-W setting

Suppresses compressed width in list-directed output. Enter either on or off for setting . The default setting is off.

-Y setting

Skips unmatched namelist groups in a namelist input record. Enter either on or off for setting. The default setting is on.

-Z setting

Recognizes -0.0 for IEEE floating point systems and writes the minus sign for edit-directed, list-directed, and namelist output. Enter either on or off for setting. The default setting is off.


Specifies either a file name or a unit number for assign_object. The assign command associates the attributes with the file or unit specified. These attributes are used during the processing of Fortran OPEN statements or during implicit file opens.

Use one of the following formats for assign_object:

  • f:file_name (for example, f:file1)

  • g:io_type; io_type can be su, sf, du, df, ff, or aq (for example, g:ff)

  • p:pattern (for example, p:file%)

  • u:unit_number (for example, u:9)

  • file_name (for example, myfile)

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.

Related Library Routines

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)



Fortran character variable that contains a complete assign command in the format that is also acceptable to the ISHELL(3f) routine.


Integer variable that is assigned the exit status on return from the library interface routine.


Integer variable or constant that contains the unit number to which attributes are assigned.


Fortran character variable that contains any attribute options and option values from the assign command. Control options -I, -O, and -R can also be passed.


Character variable or constant that contains the file name to which attributes are assigned.

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

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


assign and Fortran I/O

Assign processing lets you tune file connections. The following sections describe several areas of assign command usage and provide examples of each use.

Alternative File Names

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:

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:


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.

File Structure Selection

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 command

COS blocked

assign -F cos
assign -s cos


assign -F text
assign -s text


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

F77 blocked

assign -F f77

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

The following are examples of file structure selection:

  • To select unblocked file structure for a sequential unformatted file:

    IUN = 1
    CALL ASNUNIT(IUN,'-s unblocked',IER)

  • You can use the assign -s u command to specify the unblocked file structure for a sequential unformatted file. When this option is selected, the I/O is unbuffered. Each Fortran READ or WRITE statement results in a read(2) or write(2) system call such as the following:

    CALL ASNFILE('fort.1','-s u',IER)

  • Use the following command to assign unit 10 a COS blocked structure:

    assign -F cos u:10

Buffer Size Specification

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:

  • If unit 1 is a large sequential file for which many Fortran READ or WRITE statements are issued, you can increase the buffer size to a large value, using the following assign command:

    assign -b 336 u:1

  • If file foo is a small file or is accessed infrequently, minimize the buffer size using the following assign command:

    assign -b 1 f:foo

Foreign File Format Specification

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

Direct-access I/O Tuning

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.

Fortran File Truncation

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)

Access methods and default buffer size (IRIX systems)

The assign Environment File

To use the assign command, you must set the FILENV environment variable. FILENV can contain the pathname of a file which will be used to store assign information or it can specify that the information should be stored in the process environment.

Local assign

The assign environment information is usually stored in the assign environment file. Programs that do not require the use of the global assign environment file can activate local assign mode. If you select local assign mode, the assign environment will be stored in memory. Thus, other processes could not adversely affect the assign environment used by the program.

The ASNCTL(3f) routine selects local assign mode when it is called by using one of the following command lines:


Example 6-1. local assign mode

In the following example, a Fortran program activates local assign mode and then specifies an unblocked data file structure for a unit before opening it. The -I option is passed to ASNUNIT to ensure that any assign attributes continue to have an effect at the time of file connection.

C    Switch to local assign environment
     IUN = 11
C    Assign the unblocked file structure
     CALL ASNUNIT(IUN,'-I -s unblocked',IER)
C    Open unit 11

If a program contains all necessary assign statements as calls to ASSIGN, ASNUNIT, and ASNFILE, or if a program requires total shielding from any assign commands, use the second form of a call to ASNCTL , as follows:

C    New (empty) local assign environment
     IUN = 11
C    Assign a large buffer size
     CALL ASNUNIT(IUN,'-b 336',IER)
C    Open unit 11