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.
On IRIX systems, the assign command affects Fortran programs compiled with the MIPSpro 7 Fortran 90 or programs compiled with the MIPSpro 7.2 and 7.3 F77 compiler and the -craylibs compiler option. It also affects programs that use ffopen(3c).
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.
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 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.
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, g:aq, 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 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
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:
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:
The FILE= specifier or the actual file name.
Library buffer size in 4096-byte blocks.
Contiguous storage. Must be used with the -n option. Deferred implementation on IRIX systems.
Online tape bad data recovery. Specify either skipbad or acptbad for bdr. Deferred implementation on IRIX systems.
Specify 77 to be compatible with the FORTRAN 77 standard and Cray Research's CF77 compiling system.
Specify 90 to be compatible with the Fortran 90 standard and Cray Research's CF90 compiling system.
Specify irixf77 to be compatible with Silicon Graphic's FORTRAN 77 compiling system which runs on IRIX systems.
Specify irixf90 to be compatible with the MIPSpro 7 Fortran 90 compiler.
Kernel buffering. Specify none, ldcache, or full for buflev. If this is not set, the level of buffering is dependent on the type of open operation being performed. Deferred implementation on IRIX systems.
Special handling of a direct access file that will be accessed concurrently by several processes or tasks. Special handling includes skipping the check that only one Fortran unit be connected to a unit, suppressing file truncation to true size by the I/O buffering routines, and ensuring that the file is not truncated by the I/O buffering routines. Enter either on or off for setting. Not available on IRIX systems.
|-n sz [: st]|
Amount of system file space to reserve for a file. This is a number of 4096-byte blocks. Used by Fortran I/O, FFIO, and auxiliary I/O (AQIO, WAIO, DRIO, and MSIO). The optional st value is an obsolete way to specify the -q assign attribute. Use of -q is preferable to using the st value on -n. Deferred implementation on IRIX systems.
File system partition list. Used by Fortran I/O, FFIO, and auxiliary I/O. partlist can be a single number, a range (m-n), a set ( m:n), or a combination of ranges and sets separated by colons. Deferred implementation on IRIX systems.
Number of 4096-byte blocks to be allocated per file system partition. Used by Fortran I/O, FFIO, and auxiliary I/O. Deferred implementation on IRIX systems.
Activate or suppress the passing of the O_RAW flag to the open(2) system call. setting can be either on or off . Not available on IRIX systems.
File type. Enter text, cos, blocked, unblocked, u, sbin, bin, bmx, or tape for ft. The bmx and tape options are not available on IRIX systems.
Buffer count. Specifies the number of buffers to be allocated for a file. Deferred implementation on IRIX systems .
Activate or suppress the passing of the O_WELLFORMED flag to the open(2) system call. Used by Fortran I/O and FFIO. setting may be on or off. Deferred implementation on IRIX systems.
Activate or suppress the passing of the O_PARALLEL flag to the open(2) system call. setting can be either on or off . Not available on IRIX systems.
Suppresses repeat counts in list-directed output. setting can be either on or off . The default setting is off.
Activates or suppresses the passing of the O_DIRECT flag to the open(2) system call. Enter either on or off for setting. Available only on IRIX systems .
Character set conversion information. Enter ascii , ebcdic, or cdc for charcon. If you specify the -C option, you must also specify the -F option. ebcdic and cdc are not supported on UNICOS/mk or IRIX systems.
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.
Activates or suppresses the passing of the O_LDRAW flag to the open(2) system call. Enter either on or off for setting. Not available on IRIX systems .
Foreign numeric conversion specification. See the assign(1) man page for details about allowed values for numcon and for details about hardware platform support.
Specifies the scope of a Fortran unit and allows specification of private I/O on UNICOS systems. See the assign(1) man page for details about allowed values for scope. Deferred implementation on IRIX systems.
Suppresses use of a comma as a separator in list-directed output. Enter either on or off for setting. The default setting is off.
Activates or suppresses truncation after write for sequential Fortran files. Enter either on or off for setting.
Produces a non-UNICOS 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.
Suppresses compressed width in list-directed output. Enter either on or off for setting . The default setting is off.
Skips unmatched namelist groups in a namelist input record. Enter either on or off for setting. The default setting on UNICOS and UNICOS/mk systems is off. The default setting on IRIX systems is on.
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 on IRIX systems 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.
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)
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 (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:
Assign processing lets you tune file connections. The following sections describe several areas of assign command usage and provide examples of each use.
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:
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) :
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) OPEN(IUN,FORM='UNFORMATTED',ACCESS='SEQUENTIAL')
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) OPEN(1,FORM='UNFORMATTED',ACCESS='SEQUENTIAL')
Use the following command to assign unit 10 a COS blocked structure:
assign -F cos u:10
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 unit 1 is to be connected to a large sequential unformatted file with COS blocked structure on UNICOS or UNICOS/mk systems, enter either of the following assign commands to specify a buffer size of 336:
assign -b 336 u:1 assign -F cos:336 u:1
The buffer size for the example was calculated by multiplying tracks-per-cylinder for one type of disk by the track size in sectors of that disk.
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
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:
If unit 1 is a sequential unformatted file that is to be SDS-resident, the following Fortran statements connect the unit:
CALL ASNUNIT(1,'-F cos,sds.scr.novfl:0:100',IER) OPEN(1,FORM='UNFORMATTED')
The -F cos specification selects COS blocked structure. The sds.scr.novfl:0:100 specification indicates that the file should be SDS-resident, that it will not be kept when it is time to close, and that it can grow in size to one hundred 4096-byte blocks.
If unit 2 is a sequential unformatted file that is to be memory resident, the following Fortran statements connect the unit:
CALL ASNUNIT (2,'-F cos,mr',IER) OPEN(2,FORM='UNFORMATTED')
The -F cos,mr specification selects COS blocked structure with memory residency.
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.
The following figure summarizes the available access methods and the default buffer sizes for IRIX systems.
On UNICOS and UNICOS/mk systems, assign command information is stored in the assign environment file, which is named $TMPDIR/.assign by default. To change the location of the current assign environment file, assign the desired path name to the FILENV environment variable.
On IRIX systems, you must set the FILENV environment variable to use the assign command. 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.
The format of the assign environment file is subject to change with each UNICOS or IRIX release.
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:
CALL ASNCTL('LOCAL',1,IER) CALL ASNCTL('NEWLOCAL',1,IER)
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 CALL ASNCTL('LOCAL',1,IER) IUN = 11 C Assign the unblocked file structure CALL ASNUNIT(IUN,'-I -s unblocked',IER) C Open unit 11 OPEN(IUN,FORM='UNFORMATTED')
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 CALL ASNCTL('NEWLOCAL',1,IER) IUN = 11 C Assign a large buffer size CALL ASNUNIT(IUN,'-b 336',IER) C Open unit 11 OPEN(IUN,FORM='UNFORMATTED')