USE OF FDNAMES

FILES AND DEVICES

There are two ways that FDnames may be used for input/output operations. Most commonly, a program reads or writes information without knowing the names of the specific files or devices being used. This case is handled with logical I/O units. Alternatively, the program reads from or writes to a specific file or device, whose name is either built into the program or is obtained as data from the user.

This case is handled with FDUB-pointers.

A summary of the system subroutines that use file names, logical I/O units, and FDUB-pointers is given in the section “Subroutines That Use Files and Devices” inMTS Volume 3: System Subroutine Descriptions, Reference R1003.

Logical I/O Units

When a program is coded, the names of the files and devices to be used for input and output are normally unknown; hence, it is impossible to specify them in the program source statements. Even if the names were known, it would be inconvenient to specify them in the program, since this would require retranslation every time a file or device name was changed. Thus, it is desirable to specify the location of the data at execution time rather than at translation time. To do this, alogical I/O unitis used. A logical I/O unit is a symbolic name which is used in a program to specify the source of data for input or the destination of output information. A logical I/O unit does not name a specific file or device; it simply serves as a reference. When a program is executed, it is necessary to first specify, for each logical I/O unit used by the program, the actual file or device to be used. For example, in FORTRAN, the statement

READ (5,100) P

requests input from logical I/O unit 5. Before this statement can be executed, the user must specify a file or device name to be used whenever logical I/O unit 5 is referenced. This is normally done on the RUN command by specifying a keyword of the form

unit=FDname

For example, to execute the program in the file PROGRAM which contains the above FORTRAN statement, the command

RUN PROGRAM 5=DATAFILE

may be given; whenever the program requires input from logical I/O unit 5, data is read from the file DATAFILE.

The names of the logical I/O units and acceptable synonyms are given below. Minimum abbreviations for the synonyms are underlined. The synonyms will be used in this volume when appropriate.

Units Synonyms SCARDS INPUT SPRINT PRINT SPUNCH OBJECT SERCOM

GUSER 0 through 99

For each of these, except 0 through 99, there is a subroutine of the same name to perform input and/or output on this unit. For 0 through 99, the subroutines READ and WRITE are provided (these subroutines may also be used with the named logical I/O units). These subroutines can be called from both assembly-language programs and higher-level language programs. For example, calling the subroutine INPUT (SCARDS) from a program causes a record to be read from the logical I/O unit INPUT (SCARDS). These subroutines are described in MTS Volume 3: System Subroutine Descriptions, Reference R1003.

Since it is desirable to reduce the amount of typing necessary to specify the information required on a RUN command, some of the logical I/O units have default specifications. The following defaults are provided if no logical I/O unit assignment is given on the RUN command:

Units Defaults INPUT *SOURCE*

PRINT *SINK*

OBJECT *PUNCH*¹

SERCOM *MSINK*

GUSER *MSOURCE*

0–99 none

1*PUNCH* is the default for batch jobs only if the global card estimate is greater than 0;

otherwise, there is no default. OBJECT (SPUNCH) is not defaulted for terminal jobs.

For example, if on a RUN command the logical I/O unit SCARDS is not specified as a particular file or device, it is assigned by default to the current input *SOURCE*. Since most of the translators in MTS use INPUT for source program input and PRINT for compilation listing output, it is often unnecessary to specify these logical I/O units when running the translators, especially in batch mode.

For both batch and conversational mode, it is usually necessary to specify the logical I/O unit for the translator output of the resulting object deck. Logical I/O units 0 through 99 have no default specifications in MTS. There are, however, default specifications for units 5 and 6 within the

FORTRAN I/O library routines during program execution.

The following example given in assembler language illustrates how to perform an input/output operation using subroutines and logical I/O units. This example reads the name of a file from logical I/O unit 5 and performs an indexed write operation to place the line “***DATA LINE***” into line 10 of that file. For the complete descriptions of the subroutines used in this example, seeMTS Volume 3.

READ 5,FNAME,EXIT=ERROR Read file name

CALL SETLIO,(UNIT,FNAME) Assign file to I/O unit

LTR 15,15 Check for error

BNE ERROR

WRITE UNIT,REGION,@I,10000,EXIT=ERROR Write the data line .

FNAME DC CL18' ' UNIT DC CL8'PRINT '

REGION DC C' ***DATA LINE***' Data line The following example is the FORTRAN equivalent of the example given above.

INTEGER*4 MOD/2/,LNUM/10000/

The following example is the C87 equivalent of the example given above.

#include <mts.h>

main()

{ char fname[18];

short inlen;

static const short outlen=16;

static const int unit5 = 5;

static const unsigned int inmods = 0,

outmods = _INDEXED;

error: /* print error message */

}

FDUB-Pointers

It is occasionally necessary for a program to read or write on a specific file or device whose name is not, or cannot, be assigned to a logical I/O unit before or after program execution begins. The FDname may be built into the program (as for example a fixed file of error messages) or may be input data to the program. The program uses a fullword quantity called aFDUB-pointerto refer to this FDname when doing input or output on the file or device. A FDUB-pointer is the location of aFile orDeviceUsage Block, maintained by MTS to control the use of that file or device. When the subroutines READ or WRITE are called, the FDUB-pointer is used as a parameter instead of a logical I/O unit name or number.

A FDUB-pointer is obtained by calling the subroutine GETFD (seeMTS Volume 3) giving it the FDname for the file or device. The FDUB-pointer returned by GETFD can then be used in calls to READ or WRITE to do input or output. It can also be used in calls to a number of other subroutines (see table below). When the program is finished with the FDUB-pointer, the FDUB can be released by calling the subroutine FREEFD.

The following example given in assembler language illustrates how to perform an input/output operation using subroutines and FDUB-pointers. This example reads the name of a file from logical I/O unit 5 and performs an indexed write operation to place the line “***DATA LINE***” into line 10 of that file. The subroutine GDINFO is also to determine if the file specified is a line file. For the complete descriptions of the subroutines used in this example, seeMTS Volume 3.

READ 5,FNAME,EXIT=ERROR Read file name LA 1,FNAME

CALL GETFD Get FDUB-pointer for file

LTR 15,15 Check for error

USING GDDSECT,1 Pointer for GDINFO area CLC GDTYPE,=C'FILE' Check for line file type BNE ERROR

SR 0,0

CALL FREESPAC Release the GDINFO area DROP 1

WRITE FDUB,REGION,@I,10000,EXIT=ERROR Write the data line L 0,FDUB

REGION DC C' ***DATA LINE***' Data line

COPY *GDINFODSECT GDINFO area copy section .

. (GDDSECT has symbol GDTYPE)

The following example is the FORTRAN equivalent of the example given above.

EXTERNAL GETFD,FREEFD,FREESP,GDINF

INTEGER*4 ADROF,FDUB,GDAREA(11),GDTYPE,FILE/'FILE'/

INTEGER*4 MOD/2/,LNUM/10000/

LOGICAL*4 REGION(4)/' ***','DATA',' LIN','E***'/

LOGICAL*1 FNAME(18)

INTEGER*2 LEN/16/