HP Fortran for OpenVMS
User Manual

You can use OpenVMS logical names to associate logical units with file specifications. A logical name is a string up to 255 characters long that you can use as part of a file specification.

Table 6-3 lists the OpenVMS process logical names for standard I/O devices already associated with particular file specifications.

Table 6-3 Predefined System Logical Names

OpenVMS Logical Name	Meaning	Default
SYS$COMMAND	Default command stream	For an interactive user, the default is the terminal; for a batch job, the default is the batch job input command file.
SYS$DISK	Default disk device	As specified by user.
SYS$ERROR	Default error stream	For an interactive user, the default is the terminal; for a batch job, the default is the batch job log file.
SYS$INPUT	Default input stream	For an interactive user, the default is the terminal; for a batch job, the default is the batch command file.
SYS$OUTPUT	Default output stream	For an interactive user, the default is the terminal; for a batch job, the default is the batch log file.

You can dynamically create a logical name and associate it with a file specification by means of the DCL commands ASSIGN or DEFINE. For example, before program execution, you can define each logical name recognized by your program with a file specification appropriate to your needs without recompiling and relinking the program. For example:

$ DEFINE LOGNAM USERD:[SMITH]TEST.DAT;2

The preceding command creates the logical name LOGNAM and associates it with the file specification USERD:[SMITH]TEST.DAT;2. As a result, this file specification is used whenever the logical name LOGNAM is encountered during program execution.

The following statement opens the file associated with the current definition of the logical name LOGNAM:

OPEN (UNIT=7, FILE='LOGNAM', STATUS='OLD')

Logical names provide great flexibility because they can be associated with either a partial or complete file specification (with either a device or a device and a directory), or even another logical name.

6.6.1.1 Preconnected Files

ACCEPT, TYPE, and PRINT statements do not refer explicitly to a logical unit (a file or device) from which or to which data is to be transferred; they refer implicitly to a default preconnected logical unit. ACCEPT refers to the default input device SYS$INPUT. TYPE and PRINT refer to the default output device SYS$OUTPUT. These defaults can be overridden with appropriate logical name assignments (see Section 6.6.1.2).

READ, WRITE, and REWRITE usually refer to explicit unit numbers. If you do not use an OPEN statement to open logical unit 5 or 6 without setting the appropriate logical name (FORnnn), unit number 5 is associated with SYS$INPUT and unit 6 with SYS$OUTPUT.

At run time, if units 5 and 6 are specified by a record I/O statement (such as READ or WRITE) without having been explicitly opened by an OPEN statement, HP Fortran implicitly opens units 5 and 6 and associates them with their respective operating system standard I/O files if the corresponding logical name is not set.

To redirect I/O to an external disk file instead of these preconnected files, you can either use an OPEN statement to unit 5 and 6 or set the appropriate logical name. If you set the corresponding HP Fortran logical name, the file specified by that HP Fortran logical name is used.

The order of precedence when you open a file is:

• When you explicitly open a preconnected file by using an OPEN statement with a file name for that unit, the Fortran logical name and OpenVMS standard I/O device are not used. The file is no longer considered preconnected.
  If the file name is not present in the OPEN statement, the unit is still preconnected as shown in Table 6-4.
• If the appropriate Fortran logical name is defined, its definition is used instead of the OpenVMS standard I/O logical name.
• If the Fortran logical name is not defined, the OpenVMS standard I/O logical name is used.
• For units not associated with a preconnected OpenVMS standard I/O device, if you omit the file name and file type, the system supplies certain defaults, such as a file name and type of FORnnn.DAT (see Section 6.6.1.2.

Table 6-4 shows the I/O statements and their associated Fortran logical names and OpenVMS standard I/O logical names.

Table 6-4 Implicit Fortran Logical Units

Statement	Fortran Logical Name1	Equivalent OpenVMS Logical Name
READ (*,f) iolist	FOR$READ	SYS$INPUT
READ f,iolist	FOR$READ	SYS$INPUT
ACCEPT f,iolist	FOR$ACCEPT	SYS$INPUT
WRITE (*,f) iolist	FOR$PRINT	SYS$OUTPUT
PRINT f,iolist	FOR$PRINT	SYS$OUTPUT
TYPE f,iolist	FOR$TYPE	SYS$OUTPUT
READ (5),iolist	FOR005	SYS$INPUT
WRITE (6),iolist	FOR006	SYS$OUTPUT

You can change the file specifications associated with these Fortran logical names by using the DCL commands DEFINE or ASSIGN.

6.6.1.2 HP Fortran Logical Names

HP Fortran I/O is usually performed by associating a logical unit number with a device or file. OpenVMS logical names provide an additional level of association; a user-specified logical name can be associated with a logical unit number.

HP Fortran provides predefined logical names in the following form:

FORnnn

The notation nnn represents a logical unit number, any non-negative 4-byte integer (maximum value is 2,147,483,647). For example, for logical unit 12, the predefined logical name would be FOR012; for logical unit 1024, the predefined logical name would be FOR1024.

By default, each Fortran logical name is associated with a file named FORnnn.DAT on your default disk under your default directory. For example:

WRITE (17,200)

If you enter the preceding statement without including an explicit file specification, the data is written to a file named FOR017.DAT on your default disk under your default directory.

You can change the file specification associated with a Fortran logical unit number by using the DCL commands ASSIGN or DEFINE to change the file associated with the corresponding Fortran logical name. For example:

$ DEFINE FOR017 USERD:[SMITH]TEST.DAT;2

The preceding command associates the Fortran logical name FOR017 (and therefore logical unit 17) with file TEST.DAT;2 on device USERD in directory [SMITH].

You can also associate the Fortran logical names with any of the predefined system logical names, as shown in the following examples:

• The following command associates logical unit 10 with the default output device (for example, the batch output stream):

  $ DEFINE FOR010 SYS$OUTPUT

• The following command associates the default command stream with the default input device (for example, the batch input stream):

  $ DEFINE SYS$COMMAND SYS$INPUT

For More Information:

On the DCL commands you can use to assign or deassign logical names, see Appendix D.

6.6.2 Disk Files and File Specifications

Most I/O operations involve a disk file, keyboard, or screen display. You can access the terminal screen or keyboard by using preconnected files, as described in Section 6.6. Otherwise, this chapter discusses disk files.

HP Fortran recognizes logical names for each logical I/O unit number in the form of FORnnn, where nnn is the logical I/O unit number, with leading zeros for fewer than three digits. If a file name is not specified in the OPEN statement and the corresponding FORnnn logical name is not set for that unit number, HP Fortran generates a file name in the form FORnnn.DAT, where n is the logical unit number.

Certain HP Fortran logical names are recognized and preconnected files exist for certain unit numbers. Performing an implied OPEN means that the FILE and DEFAULTFILE specifier values are not specified and a logical name is used, if present.

A complete OpenVMS file specification has the form:

node::device:[directory]filename.filetype;version

For example:

BOSTON::USERD:[SMITH]TEST.DAT;2

You can associate a file specification with a logical unit by using a logical name assignment (see Section 6.6.1) or by using an OPEN statement (see Section 6.6.2). If you do not specify such an association or if you omit elements of the file specification, the system supplies default values, as follows:

• If you omit the node, the local computer is used.
• If you omit the device or directory, the current user default device or directory is used.
• If you omit the file name, the system supplies FORnnn (where nnn is the logical unit number, with leading zeros for one- or two-digit numbers)
• If you omit the file type, the system supplies DAT.
• If you omit the version number, the system supplies either the highest current version number (for input) or the highest current version number plus 1 (for output).

For example, if your default device is USERD and your default directory is SMITH, and you specified the following statements:

READ (8,100) . . . WRITE (9,200)

The default input file specification would be:

USERD:[SMITH]FOR008.DAT;n

The default output file specification would be:

USERD:[SMITH]FOR009.DAT;m

In these examples, n equals the highest current version number of FOR008.DAT and m is 1 greater than the highest existing version number of FOR009.DAT.

You can use the FILE and DEFAULTFILE specifiers in an OPEN statement to specify the complete definition of a particular file to be opened on a logical unit. For example:

OPEN (UNIT=4, FILE='USERD:[SMITH]TEST.DAT;2', STATUS='OLD')

In the preceding example, the existing file TEST.DAT;2 on device USERD in directory SMITH is to be opened on logical unit 4. Neither the default file specification (FOR004.DAT) nor the Fortran logical name FOR004 is used. The value of the FILE specifier can be a character constant, variable, or expression.

HP Fortran provides the following possible ways of specifying all or part of a file specification (directory and file name), such as DISK2:[PROJECT.DATA]:

• The FILE specifier in an OPEN statement typically specifies only a file name (such as TESTDATA) or contains both a directory and file name (such as DISK2:[PROJECT.DATA]TESTDATA).
• The DEFAULTFILE specifier (an HP extension) in an OPEN statement typically specifies a device and/or directory without a file name or a device and/or directory with a file name (such as DISK2:[PROJECT.DATA]TESTDATA).
• If you used an implied OPEN or if the FILE specifier in an OPEN statement did not specify a file name, you can use a logical name to specify a file name or a device and/or directory that contains both a directory and file name (see Section 6.6.1).

In the following interactive example, the file name is supplied by the user and the DEFAULTFILE specifier supplies the default values for the file specification string. The file to be opened is in device and directory DISK4:[PROJ] and is merged with the file name typed by the user into the variable DOC:

CHARACTER(LEN=40) DOC WRITE (6,*) 'Type file name ' READ (5,*) DOC OPEN (UNIT=2, FILE=DOC, DEFAULTFILE='DISK4:[PROJ]',STATUS='OLD')

The DEFAULTFILE specification overrides your process default device and directory.

You can also specify a logical name as the value of the FILE specifier, if the logical name is associated with a file specification. If the logical name LOGNAM is defined to be the file specification USERD:[SMITH]TEST.DAT, the logical name can then be used in an OPEN statement, as follows:

OPEN (UNIT=19, FILE='LOGNAM', STATUS='OLD')

When an I/O statement refers to logical unit 19, the system uses the file specification associated with logical name LOGNAM.

If the value specified for the FILE specifier has no associated file specification, it is regarded as a true file name rather than as a logical name. Suppose LOGNAM had not been previously associated with the file specification by using an ASSIGN or DEFINE command. The OPEN statement would indicate that a file named LOGNAM.DAT is located on the default device, in the default directory.

For an example program that reads a typed file name, uses the typed name to open a file, and handles such errors as the "file not found" error, see Example 7-1.

For a detailed description of OpenVMS file specifications, see the Guide to OpenVMS File Applications.

For More Information:

• On a list of HP Fortran I/O statements, see Table 6-1.
• On record I/O, see Section 6.9.
• On HP Fortran I/O statements and specifier values, including defaults, see Table 6-1.
• On statement syntax, see the HP Fortran for OpenVMS Language Reference Manual.
• On the ERR and IOSTAT specifiers, see Chapter 7.
• On closing files, see Section 6.8.

The OPEN statement connects a unit number with an external file and allows you to explicitly specify file attributes and run-time options using OPEN statement specifiers. Once you open a file, you should close it before opening it again unless it is a preconnected file.

If you open a unit number that was opened previously (without being closed), one of the following occurs:

• If you specify a file specification that does not match the one specified for the original open, the HP Fortran run-time system closes the original file and then reopens the specified file.
  This resets the current record position for the second file.
• If you specify a file specification that does match the one specified for the original open, the file is reconnected without the internal equivalent of the CLOSE and OPEN.
  This lets you change one or more OPEN statement run-time specifiers while maintaining the record position context.

You can use the INQUIRE statement (see Section 6.7) to obtain information about a whether or not a file is opened by your program.

Especially when creating a new file using the OPEN statement, examine the defaults (see the description of the OPEN statement in the HP Fortran for OpenVMS Language Reference Manual) or explicitly specify file attributes with the appropriate OPEN statement specifiers.

The OPEN statement functions and their specifiers are:

• Identify File and Unit
  \UNIT specifies the logical unit number.
  \FILE (or NAME¹) and DEFAULTFILE¹ specify the directory and/or file name of an external file.
  \STATUS or TYPE¹ indicates whether to create a new file, overwrite an existing file, open an existing file, or use a scratch file.
  \STATUS or DISPOSE¹ specifies the file existence status after CLOSE.
• File and Record Characteristics
  \ORGANIZATION¹ indicates the file organization (sequential, relative, or indexed).
  \RECORDTYPE¹ indicates which record type to use.
  \FORM indicates whether records are formatted or unformatted. See Section 6.5.4 and Section 6.4.
  \CARRIAGECONTROL¹ indicates the terminal control type.
  \KEY¹ indicates (when creating an indexed file) the key number, its type, and its location.
  \NOSPANBLOCKS¹ indicates that the records should not span block boundaries.
  \RECL or RECORDSIZE¹ specifies the record size. See Section 6.5.4.
• Special File Open Routine
  \USEROPEN¹ names the routine that will open the file to establish special context that changes the effect of subsequent HP Fortran I/O statements (see Chapter 11).
• File Access, Processing, and Position
  \ACCESS indicates the access mode (direct, keyed, or sequential). See Section 6.9.2.
  \ACTION or READONLY¹ indicates whether statements will be used to only read records, only write records, or read and write records. See Section 6.9.3.
  \POSITION indicates whether to position the file at the beginning of file, before the end-of-file record, or leave it as is (unchanged). See Section 6.9.4.
  \SHARED¹ indicates that other users can access the same file and activates record locking. See Section 6.9.3.
  \MAXREC¹ specifies the maximum record number for direct access.
  \ASSOCIATEVARIABLE¹ specifies the variable containing next record number for direct access.
• File Allocation
  \INITIALSIZE¹ indicates the allocation unit (in blocks) when creating a file.
  \EXTENDSIZE¹ indicates the allocation unit (in blocks) when allocation additional file space.
• Record Transfer Characteristics
  \BLANK indicates whether to ignore blanks in numeric fields.
  \DELIM specifies the delimiter character for character constants in list-directed or namelist output.
  \PAD, when reading formatted records, indicates whether padding characters should be added if the item list and format specification require more data than the record contains.
  \BLOCKSIZE¹ specifies the block physical I/O buffer size.
  \BUFFERCOUNT¹ specifies the number of physical I/O buffers.
  \CONVERT¹ specifies the format of unformatted numeric data. See Chapter 9.
• Error Handling Capabilities
  \ERR specifies a label to branch to if an error occurs. See Chapter 7.
• \IOSTAT specifies the integer variable to receive the error (IOSTAT) number if an error occurs. See Chapter 7.
• File Close Action
  \DISPOSE¹ identifies the action to take when the file is closed.

For More Information:

• On specifier syntax and complete information, see the HP Fortran for OpenVMS Language Reference Manual.
• On the FORM specifier, see Section 6.4.
• On file organizations, see Section 6.5.1.
• On available record types, see Section 6.5.3.
• On the CARRIAGECONTROL specifier, see Section 6.5.4.
• On the RECL (record length) specifier, see Section 6.5.4.
• On shared access to files, see Section 6.9.3.
• On the ERR and IOSTAT specifiers, see Chapter 7.
• On obtaining file information using the INQUIRE statement, see Section 6.7.
• On closing files, see Section 6.8.
• Record I/O transfer, see Section 6.9.6.
• Record advancement, see Section 6.9.5.
• Record positioning, see Section 6.9.4.
• On I/O performance considerations, see Section 5.5.