assign

Date:: 03-16-2012

NAME

assign - Assigns options for library file open processing

SYNOPSIS

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

DESCRIPTION

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 man page for more details.

The assign_object argument can take one of the following formats:

Format	Example	Attribute association
g:io_type	g:su	All sequential unformatted open requests
u:unit_number	u:9	Fortran unit 9
p:pattern	p:file%	File names matching the pattern file%
f:file_name	f:file1	File name file1
file_name	myfile	File name myfile

An assign_object that is a pattern may contain the wildcard characters % or _. 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

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 request.
g:su, g:sf, g:du, g:df, g:aq, g:ff: Each applies to a type of open request: Fortran sequential unformatted, Fortran sequential formatted, Fortran direct unformatted, Fortran direct formatted, or ffopen.
u:N: Applies whenever Fortran unit N is opened.
p:pattern: The 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.

Information is stored in the assign environment file. The location of the active assign environment can be changed by assigned a file name to the FILENV environment variable.

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

The following control 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 both supported I/O types: Fortran I/O or FFIO.

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

Other Options and Arguments

In addition to the Command and I/O Processing options, assign supports the following options:

-a actualfile: Specifies the actual file name. Used by Fortran 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.
The -a and -D options are mutually exclusive.

-b bs: Specifies buffer size of the library’s I/O buffer in units of 4096-byte blocks. Used by Fortran I/O.

The default buffer sizes (in 4096-byte blocks) are as follows:

Sequential formatted
128

Sequential unformatted
16

Direct access formatted
Minimum (record length + 1 byte, 16 blocks)
- Direct access formatted files have four buffers.
Direct access unformatted
Maximum (record length, 16 blocks) not to exceed 100 blocks

-f fortstd

This option specifies the type of Fortran with which to be compatible. Used by Fortran I/O. The valid values for fortstd are:

90: Causes the Fortran file to be compatible with the current Cray Fortran compiler.
95: Causes the Fortran file to be compatible with Cray Fortran 95. If this value is set, the list-directed and namelist output of a floating point will remain 0.E+0.

A file’s compatibility is established when it is opened. By default, a Fortran file is compatible with the language from which an OPEN statement or implicit open caused the file to be connected.

-m setting: Activate or suppress special handling of a file which will be accessed concurrently by several processes or tasks. Used by Fortran I/O.

Special handling includes skipping the check that only one Fortran unit can be connected to a file. setting can be on or off.
For files which are written, special handling also includes:
- Suppressing file truncation to true size by the I/O buffering routines. Library buffer routines are usually flushed to disk in their entirety, and a truncation of the file at close time is done to trim the last file page to the correct size.
- Ensuring that the file will not be truncated after the last record written on sequential files (-m on implies -T off).
If the file will be updated, the user is responsible for partitioning file access from all processes, tasks, or processing elements (PE) on library buffer page boundaries. This can be done in the following ways:
- Specify the -b assign option.
- Specify the first numeric parameter on the cache or bufa FFIO layers (for example, -F cache:2 or -F bufa:8).
- Specify no library buffering by using the -F system option.

-s ft: Specifies the file type. Used by Fortran I/O.

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 values for ft:

bin
Unblocked file structure with buffering.

cos or blocked
COS blocked structure.

sbin
Unblocked file structure with ``stdio’’ style buffering. The Fortran I/O library issues I/O that is compatible with the C ffwrite(3c) and ffread(3c) functions. This file type is useful for accessing pipe files. It is not permitted with formatted files.

text
New-line characters delimit the records. This is the default structure for sequential formatted files. On CLE systems it is also the default structure for direct-access formatted files.

u
Each read or write request results in an immediate system call. For best performance, requests should be made in multiples of 4096 bytes.

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.
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, and ``Default’’ or ``**’’ indicates that it is the default method. The f77 layer is the default for sequential unformatted.

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

-u bufcnt: Buffer count. Used by Fortran I/O.

Specifies the number of buffers to be allocated for a file; the default is 4. This option can be used with direct-access unformatted files.

-y setting: Suppress repeat count in list-directed output. setting can be on or off; the default 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: 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. charcon must be one of the following.

ascii (no-op) ebcdic

-D fildes: Specifies connection to a standard file. Used by Fortran I/O.

The -D and -a options are mutually exclusive. Enter one of the following for fildes:

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 and FFIO.

See the intro_ffio(3f) man page for details about the FFIO specification.
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.
The acceptable values for class are described in the following list:

bufa
Buffering layer.

cache
Cache layer.

cachea
Asynchronous cache layer.

cos
COS blocking.

event
Event layer, used to monitor I/O activity between layers. This layer generates statistics in the form of an ASCII log file.

f77
FORTRAN 77/UNIX Fortran record blocking. Default for Fortran unformatted sequential files on CLE systems.

fd
Open a specific file descriptor.

global
(Deferred implementation) This is a caching layer which distributes the cache across multiple SHMEM or MPI processes. See the intro_ffio(3f) man page for more details.

ibm
IBM MVS/VM record formats.

mr
Memory-resident files.

null
Syntactic no-op.

site
Site-specific layer.

stdin, stdout, or stderr
Open file descriptors 0, 1, or 2, respectively. (See the fd layer.)

syscall
System call I/O.

system
Generic system layer.

text
Special character-terminated record.

user
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 table lists the valid values for numcon on different hardware platforms. Note that in these tables, vax is an alias for vms.

----------------------------------------------------------------
-N option     -C default  Meaning
----------------------------------------------------------------
none          none        No data conversion
default       default     No data conversion
cray          ascii       Cray ''classic'' floating-point
ibm           ebcdic      IBM 360/370-style data conversion
vms           ascii       VAX/VMS data conversion
ieee          ascii       Generic IEEE data (no data conversion)
ieee_32                   Generic 32-bit IEEE data. No data
                          conversion except as noted below.*
mips          ascii       SGI MIPS IEEE data conversion (128-bit
                          floating-point is ''double double''
                          format)
ieee_64       ascii       Cray 64-bit IEEE data conversion
ieee_le       ascii       Little endian 32-bit IEEE data
                          conversion
ultrix                    Alias for above
t3e           ascii       Cray 64-bit IEEE data conversion;
                          denormalized numbers flushed to zero
t3d                       Alias for above
user          ascii       User-defined data conversion
site          ascii       Site-defined data conversion
ia            ascii       Intel architecture
swap_endian   ascii       The endian of data and control images
                          is swapped during unformatted input
                          and output.
----------------------------------------------------------------

* Generic 32-bit IEEE data: No data conversion, except for items promoted via -sdefault64, -sreal64, or -sinteger64. They are handled as if they had not been promoted; that is, default-sized variables are read and written as if no -s option is specified.

-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 more file types.
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.
FFIO layers specified with the -F option vary in their support for suppressing truncation with -T off.

--------------------------------------------
File Type         -T on         -T off
--------------------------------------------
bin               Allowed       Default
cos | blocked     Default       Not allowed
sbin              Default       Allowed
text              Default       Allowed
u                 Allowed       Default
unblocked         Default       Allowed
--------------------------------------------

-U setting: Produce an alternate 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 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

NOTES

If the assign command is not specified, the Fortran run-time library will use default assign values based on the type of file access (that is, sequential vs. direct and formatted vs. unformatted).

Fortran unformatted sequential and direct access files by default use the f77 and cache layers respectively. This is equivalent to entering the following assign command values.

assign -F f77 g:su
assign -F cache g:du

Fortran formatted files use the stdio (libc) library. You can access an equivalent FFIO layer by specifying the text layer, using these commands.

assign -F text g:sf
assign -F text g:df

ENVIRONMENT VARIABLES

FILENV must be set.

EXAMPLES

The following examples illustrate the use of the assign command.

Example 1:

This example removes any options previously assigned to unit 1 and assigns an actual name (/tmp/foo/filexyz) and a buffer size of 8 sectors to unit 1.

assign -a /tmp/foo/filexyz -b 8 u:1

Example 2:

To assign unit 11 an unblocked file structure without modifying any other options currently in effect for unit 11, use the -I option as shown below.

assign -I -s unblocked u:11

Example 3:

The following example sets up and uses the assign environment variable, afile, for a specific program. The assign command specifies that all files with names matching the BLOCKED% pattern (names beginning with or consisting of the characters BLOCKED) are COS blocked files.

setenv FILENV afile
assign -F cos p:BLOCKED%

Example 4:

Attributes may be stored in the process environment using the assign command, as shown in the following example.

setenv FILENV afile
assign -F f77 foo