assign(1)assign(1) NAME assign - Assigns options for library file open processing SYNOPSIS 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 DESCRIPTION On IRIX systems, the assign command affects I/O statements in program units compiled with the MIPSpro Fortran 90 compiler or compiled with the -f90libs option to the MIPSpro Fortran 77 compiler. The assign command associates options with Fortran unit numbers and file names for use during the library open processing. The ffassign(3C) command provides an interface to assign processing from C. See the ffassign(3C) man page for more details. When using direct access files, the user must assign the file to either the system or global layer for code that works with more than one processor. The default layer for direct access is the cache layer and it does not have the coherency to handle multiple processes doing I/O to the same file. The assign_object argument can take one of the following formats: ------------------------------------------------------------- Format Example Attributeassociation ------------------------------------------------------------- g:io_type g:su Sequentialunformattedopenrequest u:unit_number u:9 Fortranunit9 p:pattern p:file% Filenamesmatchingthepatternfile% f:file_name f:file1 Filenamefile1 file_name myfile Filenamemyfile ------------------------------------------------------------- An assign_object that is a pattern may contain wildcard characters % and _. The % character matches any sequence of 0 or more characters; the _ character matches any single character. The run-time I/O library applies the options to a file connection whenever assign_object is opened. The application of options occurs whenever a file is opened by any of the following: * Fortran I/O Fortran OPEN statement Implicit Fortran open via some I/O statement * FFIO ffopen(3C) library routine fdcp(1) command * Fortran auxiliary I/O WOPEN(3F) library routine OPENMS(3F) library routine OPENDR(3F) library routine AQOPEN(3F) library routine When any of these I/O routines opens a file, they use assign options for any assign_object which applies to the open request. As many as five assign_objects can apply to an open request: * g:all applies to any open. * g:su, g:sf, g:du, g:df, g:aq, and g:ff each apply to types of open requests (for example, Fortran sequential unformatted, Fortran sequential formatted, Fortran direct unformatted, Fortran direct formatted, AQOPEN, and ffopen, respectively). * u:N applies whenever Fortran unit N is opened. * p:pattern applies whenever a file with a name matching pattern is opened. The assign environment can contain only one p:assign_object that matches the current open. The exception is that the p:% pattern 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 the above categories are collected to create the complete set of options used for any particular open operation. The options are collected in the above order, with options collected later in the list of assign_objects overriding those collected earlier. 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. See the examples in the EXAMPLE section. There are two main groups of assign command options: control options and I/O processing options. This man page describes both types of options. Control options These options are available: -I Specifies an incremental assign. All options are added on to the options already assigned to the current assign_object. This option and the -O option are mutually exclusive. -O Specifies a replacement assign. All currently existing assign options for the current assign_object are replaced. This option is the default control option and is mutually exclusive from the -I option. -R Removes all assign options for assign_object. If assign_object is not specified, all currently assigned options for all assign_objects are removed. -V Views options for assign_object. If assign_object is not specified, all currently assigned options for all assign objects are printed. I/O processing options I/O processing options specify aspects of I/O processing. Each option applies to one or more supported I/O type: Fortran I/O, FFIO, or Fortran auxiliary I/O (AQIO, WAIO, DRIO, and MSIO). The special "default" option value is available for all assign attribute options with the exception of the -a option. The "default" option value has the same effect as if the corresponding option were unspecified. It can be used to nullify an option value set in a more general type of assign. For example, the following commands show how you can set a buffer size of 20 blocks for all files except the file smallfile: assign -b 20 g:all assign -b default f:smallfile Options and Arguments -a actualfile Specifies the actual file name. Used by Fortran I/O and auxiliary I/O. When the -a option is assigned to a unit, open processing for the unit results in a connection to actualfile. An error occurs if -a has been specified for a unit that is opened with an explicit FILE= specifier in the OPEN statement. When -a is assigned to a file name, the file name becomes an alias for actualfile. When file_name is specified as the FILE= specifier in an OPEN statement, actualfile is opened instead of file_name. A similar effect occurs if the ln(1) command is used to establish a symbolic link. The -a and -D options cannot both be provided. -b bs Specifies buffer size of the library's I/O buffer in units of 4096-byte blocks. Used by Fortran I/O and auxiliary I/O. On IRIX systems, the default buffer sizes in 4096-byte blocks are as follows: Sequential formatted 8 Sequential unformatted 8 Direct access formatted 16 Direct access unformatted 16 Direct files have 4 buffers. -f fortstd This option specifies the type of Fortran with which to be compatible. Used by Fortran I/O. Valid values for fortstd are: 77 Causes the Fortran file to be compatible with the FORTRAN 77 standard. 90 Causes the Fortran file to be compatible with ANSI X3.198-1991 (Fortran 90 and the Fortran 95 standard). irixf77 Causes the Fortran file to be compatible with SGI's MIPspro Fortran 77 compiling system which runs on IRIX systems. irixf90 Causes the Fortran file to be compatible with the MIPSpro Fortran 90 compiling system. A file's compatibility is established at open time. By default, a Fortran file is compatible with the language from which an OPEN statement or implicit open caused the file to be connected. Implicit opens which result from calls to READC, READCP, WRITEC, or WRITECP result in Fortran 90/95 compatibility mode by default. -s ft Specifies the file type. Used by Fortran I/O. See below for specific values supported on IRIX systems. The file type defines the way records are delimited and how end-of-file is represented. Some ft values also define the internal processing used for a file. Enter one of the following for ft: ft File Type bin Unblocked file structure with buffering. cos or blocked COS blocked structure. text New-line characters delimit the records. This is the default structure for sequential formatted files. u Each read or write request results in an immediate system call. Requests should be made in multiples of 4096 bytes for best performance. unblocked Adjacent records are not delimited from one another. This is the default structure for direct-access unformatted files though default buffer sizes will vary. On IRIX systems, it is also the default structure for direct-access formatted files. Each file type has a set of valid access methods associated with it. The following table lists the valid access methods for each of the file types. In this table, "yes" indicates that the access method is allowed; "no" indicates that it is not allowed; "default"indicates that it is the default method on IRIX systems. -------------------------------------------------------------- Sequential formatted Sequential unformatted Direct formatted Direct unformatted -------------------------------------------------------------- bin No Yes Yes Yes cos|blocked Yes Yes No No sbin Yes Yes Yes Yes text Default No Yes No u No Yes Yes Yes unblocked No Yes Default Default -------------------------------------------------------------- -t Temporary file. Used by Fortran I/O. This causes the file to be deleted when it is disconnected by using a CLOSE statement or at program termination. Unlike STATUS='SCRATCH' on OPEN, the -t option does not affect the default file name selected for a unit. If STATUS='KEEP' is specified on the CLOSE statement, it is silently ignored without error or warning. -y setting Suppress repeat count in list-directed output. setting can be on or off. The default setting is off. -B setting Activate or suppress the passing of the O_DIRECT flag to the open(2) system call. Used by Fortran I/O and FFIO. setting may be on or off. This option is supported by the cache, cachea, and system layers (see the -F option). Use of -B with the system layer requires that the user properly align their I/O requests. The cache and cachea layers will guarantee proper alighment when -B is specified. See the open(2) man page for more information about O_DIRECT. -C charcon Specifies character set conversion. Used by Fortran I/O. This requests that certain I/O processors (currently limited to the Fortran I/O libraries) convert character data from this assumed character set on input and convert it to this character set on output. At this time, charcon must be ASCII. -D fildes Specifies connection to a standard file. Used by Fortran I/O. The -D and -a options cannot be used together. Enter one of the following for fildes: fildes File stdin Connect to file descriptor 0 stdout Connect to file descriptor 1 stderr Connect to file descriptor 2 -F spec[,spec...] FFIO specification. This is a comma-separated list of layers through which data is to be passed. Used by Fortran I/O, auxiliary I/O, and FFIO. See the INTRO_FFIO(3F) man page for details about the FFIO specifications and for details on which layers are available on IRIX systems. Each layer specification is of the following general form: class[.type[.subtype]][:[num1]:[num2]:[num3]] For each class, class specifies the class of processing to be done. Many class values also accept type and/or subtype fields to modify their behavior; other class values accept only the class itself (for example, syscall). Following the type and subtype fields, many classes accept numeric fields to further tune or modify the file processing. Units in these numeric fields differ depending on class. All specification lists end, either implicitly or explicitly, with the system layer. If this layer is not specified, it is added automatically. Acceptable values for class are as follows: class Value bufa Buffering layer. cache Cache layer. cachea Asynchronous cache layer. cos or blocked COS blocking. event Monitors I/O activity. f77 FORTRAN 77/UNIX Fortran record blocking. This is the default structure for sequential unformatted files on IRIX systems. fd Open a specific file descriptor. global IRIX shared file. This is a caching layer which distributes the cache across all PEs. See the INTRO_FFIO(3F) man page for more details. null Syntactic no-op. Not available on IRIX systems. stdin, stdout, or stderr Open file descriptors 0, 1, or 2, respectively (see fd layer). syscall System call I/O. system Generic system layer. text Special character-terminated record. tmf IRIX tape management facility. user/site User layer. vms VAX/VMS record format. For more information on the classes, see the INTRO_FFIO(3F) man page. -N numcon Specifies foreign numeric conversion. Used by Fortran I/O. Fortran unformatted I/O converts numeric data from this assumed numeric format on input, and converts it to this numeric format on output. If this option is used and the -C option is not used, appropriate character defaults are used. Each value for numcon selects a particular type of foreign data conversion. Each option has a mapping that associates each of the native data types with a corresponding foreign data type and length in bits. Appropriate data conversion is done on unformatted input and output operations. The following tables list the values for numcon. Note that "VAX" is an alias for "VMS". --------------------------------------------------- -N option -C default Meaning --------------------------------------------------- none none Nodataconversion default default Nodataconversion cray ASCII CrayPVP(non-IEEE)data conversion mips ASCII Nodataconversion user ASCII Userdefineddataconversion site ASCII Sitedefineddataconversion ibm EBCDIC IBMdataconversion ieee ASCII Generic32-bitIEEEdata conversion ieee_32 (aliasforabove) ieee_64 ASCII CRAY64-bitIEEEdata conversion ieee_le ASCII Little-endian32-bitIEEE data conversion vax ASCII DECVAX/VMSdataconversion vms (aliasforabove) --------------------------------------------------- -S setting Suppress use of comma as a separator in list-directed output. setting can be either on or off. The default setting is off. -T setting Activates or suppresses truncation after write for sequential Fortran files. Used by Fortran I/O. The selection of -T on is standard and is the default setting for most file types. Selecting -T off is useful in applications where GETPOS and SETPOS are used to simulate random access to a file with sequential I/O. The following table describes the -T option settings allowed for the file types specified with the -s option. Unsupported combinations are diagnosed when a Fortran unit is opened. ----------------------------------------- File type -Ton -Toff ----------------------------------------- bin Allowed Default cos or blocked Default Notallowed sbin Default Allowed tape or bmx Default Notallowed text Default Allowed u Allowed Default unblocked Default Allowed ----------------------------------------- FFIO layers specified with the -F option vary in their support for suppressing truncation with -T off. -U setting Produce a form of list-directed output. setting can be either on or off. This setting is a global setting which sets the value for the -y, -S, and -W options all to the same value. The default setting is off. -W setting Suppress compressed width in list-directed output. setting can be either on or off. The default setting is off. -Y setting Skip unmatched namelist group in the namelist input record. setting can be either on or off. The default setting is on. -Z setting Recognize -0.0 for IEEE floating point systems. setting can be either on or off. This option recognizes -0.0 for IEEE floating point systems and writes the minus sign for edit-directed, list-directed, and namelist output. The minus sign is suppressed by default on IRIX systems. The following example suppresses the write of the minus sign for -0.0 for unit 9 on an IEEE floating point system: assign -Z on u:9 The minus sign is suppressed for IRIX systems to prevent problems from hardware instructions and optimizations which may return a -0.0 from a 0.0 value. ENVIRONMENT VARIABLES The FILENV environment variable must be set to use the assign command on IRIX systems. EXAMPLES Example: The following example assigns an actual name (/tmp/foo/filexyz) and a buffer size of 8 sectors to unit 1, removing any previously assigned options to unit 1: assign -a /tmp/foo/filexyz -b 8 u:1 Example: The following example sets up and uses the assign environment file, afile, for a specific program. The assign command specifies that all files with the names matching the BLOCKED% pattern are COS blocked files: env FILENV=afile assign -F cos p:BLOCKED% env FILENV=afile a.out Example: Attributes may be stored in the process environment using the assign or asgcmd commands. The following example uses the assign command: setenv FILENV \$EVAR eval `assign -F f77 foo` The following example uses the asgcmd command: eval `asgcmd -F f77 foo` SEE ALSO asgcmd(1), df(1), ln(1), setf(1), tpmnt(1), write(1) ialloc(2), open(2) acptbad(3F), assign(3F), ffassign(3C), ffopen(3C), fread(3C), intro_ffio(3F), openms(3F), opendr (see openms(3F)), skipbad(3F) MIPSpro Application Programmer's I/O Guide