TOPS-20 Monitor Calls User's Guide

Chapter 3 Using files

3.1 Overview

All information stored in the DECSYSTEM-20 is kept in files. The basic unit of storage in a file is a page containing bytes from 1 to 36 bits in length. Thus, a sequence of pages constitutes a file. In most cases, files have names. Although all files are handled in the same manner, certain operations are unavailable for files on particular devices.

Programs can reference files by several methods:

In a sequential byte-by-byte manner.
In a multiple byte or string manner.
In a random byte-by-byte manner if the particular file-storage device allows it.
In a page-mapping or section-mapping manner for files on disk.

Byte and string input/output are the most common types of operations.

Generally, all programs perform I/O by moving bytes of data from one location to another. For example, programs can move bytes from one memory area to another, from memory to a disk file, and from the user's terminal to memory. In addition, a program can map multiple 512-word pages or 512-page sections from a disk file into memory or vice versa.

Data transfer operations on files require four steps:

Establishing a correspondence between a file and a Job File Number (JFN), because all files are referenced by JFNs.
Opening the file to establish the data mode, access mode, and byte size and to set up the monitor tables that permit data to be accessed.
Transferring data either to or from the file.
Closing the file to complete any I/O, to update the directory if the file is on the disk, and to release the monitor table space used by the file.

Some operations on files do not require the execution of all four steps above. Examples of these operations are: deleting or renaming a file, or changing the access code or account of a file. Although these operations do not require all four steps, they do require that the file has a JFN associated with it (step 1 above).

It is possible for disk files on the DECSYSTEM-20 to be simultaneously read or written by any number of processes. To make sharing of files possible, all instances of opening a specific file in a specific directory cause a reference to the same data. Therefore, data written into a file by one process can immediately be seen by other processes reading the file.

Access to files is controlled by the 6-digit (octal) file access code assigned to a file when it is created. This code indicates the types of access allowed to the file for the three classes of users: the owner of the file, the users with group access to the file, and all other users. (Refer to the TOPS-20 User's Guide for more information on the file access codes.) If the user is allowed access to a file, he requests the type of access desired when opening the file with the OPENF% monitor call (refer to Section 3.4.1) in his program. If the access requested in the OPENF% call does not conflict with the current access to the file, the user is granted access. Essentially, the current access to the file is set by the first user who opens it.

Thus, for a user to be granted access to a specific file, two conditions must be met:

The file access code must allow the user to access the file in the desired manner (for example, read, write).
The file must not be opened for a conflicting type of access.

3.2 Job File Number

The Job File Number (JFN) is one of the more important concepts in the operating system because it serves as the identifier of a particular file on a particular device during a process' execution. It is a small integer assigned by the system upon a request from the user's program. JFNs are usually assigned sequentially starting with 1.

The JFN is valid for the job in which it is assigned and may be used by any process in the job. The system uses the JFN as an index into the table of files associated with the job and always assigns a JFN that is unique within the job. Even though a particular JFN within the job can refer to only one file, a single file can be associated with more than one JFN. This occurs when two or more processes are using the same file concurrently. In this case, each of the processes will probably have a different JFN for the file, but all of the JFNs will be associated with the same file.

3.3 Associating a file with a JFN

In order to reference a file, the first step the user program must complete is to associate the specific file with a JFN. This correspondence is established with the GTJFN% (Get Job File Number) monitor call. One of the arguments to this call is the string representing the desired file. The string can be specified within the program (that is, come from memory) or can be accepted as input from the user's terminal or from another file. The string can represent the complete specification for the file:

dev:<directory>name.typ.gen;T(temporary);P(protection);A(account);(device dependent attributes)

If you omit any fields of the specification, the system can provide values for all except the name field. Refer to the TOPS-20 User's Guide for a complete explanation of the specification for a file.

Table 3-1 lists the values the system will assign to fields not specified by the input string.

Table 3-1: Standard System Values for File Specifications
Field	Value
Device	DSK:
Directory	Directory to which user is currently connected.
Name	No default; this field must be specified.
Type	Null.
Generation	number The highest existing generation number if the file is an input file. The next higher generation number if the file is an output file.
Protection	Protection of next lower generation of file, if one exists; otherwise, protection as specified in the directory.
Account	Account specified when user logged in.

If the string specified identifies a single file, the monitor returns a JFN that remains associated with that file until either the process releases the JFN or the job logs off the system. After the assignment of the JFN is complete, the user's program uses the JFN in all references to that file.

The user's program can set up either the short or the long form of the GTJFN% monitor call. The long form of the GTJFN% call requires an argument block; the short form does not. The long form of GTJFN% has functions and flexibility not available in the short form of the call. The short form of GTJFN% allows a file specification to be obtained from a string in memory or from a file, but not from both. Fields not specified by the input are taken from the standard system values for those fields (refer to Table 3-1). This form is sufficient for most uses of the call. The long form allows a file specification to be obtained from both a string in memory and a file. If both are given as arguments, the string is used first, and then the file is used if more fields are needed to complete the specification. This form also allows the user's program to specify nonstandard values to be used for fields not given and to request the assignment of a specific JFN.

3.3.1 GTJFN% Monitor Call

The GTJFN% monitor call assigns a JFN to the specified file. It accepts two words of arguments. These argument words are different depending on the form of GTJFN% being used. The user's program indicates the desired GTJFN% form by setting bit 17(GJ%SHT) of AC1 to 1 for the short form or by clearing bit 17(GJ%SHT) for the long form.

3.3.1.1 Short Form of GTJFN%

The short form of the GTJFN% monitor call requires the following two words of arguments.

                 0                        17 18                       35
                !=======================================================!
        AC1     !         flag bits         ! default generation number !
                !=======================================================!


                 0                                                    35
                !=======================================================!
        AC2     !     source designator for file specification per      !
                !          bit 16  (GJ%FNS) of AC1                      !
                !=======================================================!

The flag bits that can be specified in AC1 are described in Table 3-2.

Table 3-2: GTJFN% Flag Bits

Bit

Symbol

Meaning

GJ%FOU

The file specification given is to be assigned the next higher generation number. This bit indicates that a new version of a file is to be created and is normally set if the file is for output use.

GJ%NEW

The file specification given must not refer to an existing file (that is, the file must be a new file).

GJ%OLD

The file specification given must refer to an existing file. This bit has no effect on a parse-only JFN. (See bit GJ%OFG.)

GJ%MSG

One of the appropriate messages is to be printed after the file specification is obtained. The message is printed only if the user types the ESC key to end his file specification (that is, he is using recognition input).
[NEW FILE]
[NEW GENERATION]
[OLD GENERATION]
[OK] if GJ%CFM (bit 4) is off
[CONFIRM] if GJ%CFM (bit 4) is on

GJ%CFM

Confirmation from the user will be required to verify that the file specification obtained is correct. To confirm the file specification, the user can press the RETURN key.

GJ%TMP

The file specified is to be a temporary file.

GJ%NS

Only the first file specification in a multiple logical name assignment is to be searched for the file.

GJ%ACC

The JFN specified is not to be accessed by inferior processes in this job. However, any process can access the file by acquiring a different JFN. To prevent the file from being accessed by other processes, the user's program can set OF%RTD (bit 29) in the OPENF call (refer to Section 3.4.1).

GJ%DEL

The file specified is not to be considered as deleted, even if it is marked as deleted.

9-10

GJ%JFN

These bits are off in the short form of the GTJFN call (refer to Section 3.3.1.2 for their description).

GJ%IFG

The file specification given is allowed to have one or more of its fields specified with a wildcard character (* or %). This bit is used to process a group of files and is generally used for input files. The monitor verifies that at least one value exists for each field that contains a wildcard and assigns the JFN to the first file in the group.

The monitor also verifies that fields not containing wildcards represent a new or old file according to the setting of GJ%NEW and GJ%OLD.

GJ%OFG

The JFN is to be associated with the given file specification string only and not to the actual file. The string may contain a wildcard character (* or %) in one or more of its fields. It is checked for correct punctuation between fields, but is not checked for the validity of any field. This bit allows a JFN to be associated with a file specification even if the file specification does not refer to an actual file. The JFN returned cannot be used to refer to an actual file (for example, cannot be used in an OPENF call) but can be used to obtain the original input string via the JFNS monitor call (refer to Section 3.7.2).

GJ%FLG

Flags are to be returned in the left half of AC1 on a successful return.

GJ%PHY

Logical names specified for the current job are to be ignored and the physical device is to be used.

GJ%XTN

This bit is off in the short form of the GTJFN call (refer to Section 3.3.1.2 for its description).

GJ%FNS

The contents of AC2 are to be interpreted as follows:

If this bit is on, AC2 contains an input JFN in the left half and an output JFN in the right half. The input JFN is used to obtain the file specification to be associated with the JFN. The output JFN is used to indicate the destination for printing the names of any fields being recognized. To omit either JFN, the user's program must specify the symbol .NULIO (377777).
If this bit is off, AC2 contains a pointer to a string in memory that specifies the file to be associated with the JFN.

GJ%SHT

This bit must be on (set) for the short form of the GTJFN% call; it must be off for the long form of the call.

18-35

The generation number of the file (between 1 and 377777) or one of the following:

0(.GJDEF)	to indicate that the next higher generation number of the file is to be used if GJ%FOU (bit 0) is on, or to indicate that the highest existing generation number of the file is to be used if GJ%FOU is off. (This value is usually used in this field.)
-1(.GJNHG)	to indicate that the next higher generation number of the file is to be used if no generation number is supplied.
-2(.GJLEG)	to indicate that the lowest existing generation number of the file is to be used.
-3(.GJALL)	to indicate that all generation numbers (*) of the file are to be used and that the JFN is to be assigned to the first file in the group. (Bit GJ%IFG must be set.)

If the GTJFN% call is given with the appropriate flag bit set (GJ%IFG or GJ%OFG), the file specification given as input can have a wildcard character (either an asterisk or a percent sign) appearing in the directory, name, type, or generation number field. (The percent sign cannot appear in the generation number field.) The wildcard character is interpreted as matching any existing occurrence of the field. For example, the specification

        <LIBRARY>*.MAC

identifies all the files with the file type .MAC in the directory named <LIBRARY>. The specification

        <LIBRARY>MYFILE.FO%

identifies all the files in directory <LIBRARY> with the name MYFILE and a three-character file type in which the first two characters are .FO. Upon completion of the GTJFN call, the JFN returned is associated with the first file found in the group according to the following:

in numerical order by directory number
in alphabetical order by filename
in alphabetical order by file type
in ascending numerical order by generation number

The GNJFN% (Get Next JFN) monitor call can then be given to assign the JFN to the next file in the group (refer to Section 3.7.3). Normally, a program that accepts wildcard characters in a file specification will successively reference all files in the group using the same JFN and not obtain another JFN for each one.

If execution of the GTJFN% call is not successful because problems were encountered in performing the call, the JFN is not assigned and an error code is returned in the right half of AC1. The execution of the program continues at the instruction following the GTJFN% call.

If execution of the GTJFN% call is successful, the JFN assigned is returned in the right half of AC1 and various bits are set in the left half, if flag bits 11, 12, or 13 were on in the call. (The bits returned on a successful call are described in Table 3-3.) If bit 11, 12, or 13 was not on in the call, the left half of AC1 is zero. The execution of the program continues at the second instruction after the GTJFN% call.

Table 3-3: Bits Returned on GTJFN% Call
Bit	Symbol	Meaning
0	GJ%DEV	The device field of the file specification contains wildcard characters.
1	GJ%UNT	The unit field of the file specifications contains wildcard characters. This bit is never set because wildcard characters are not allowed in unit fields.
2	GJ%DIR	The directory field of the file specification contains wildcard characters.
3	GJ%NAM	The filename field of the file specification contains wildcard characters.
4	GJ%EXT	The file type field of the file specification contains wildcard characters.
5	GJ%VER	The generation number field of the file specification contains wildcard characters.
6	GJ%UHV	The file used has the highest generation number because a generation number of 0 was given in the call.
7	GJ%NHV	The file used has the next higher generation number because a generation number of 0 or -1 was given in the call.
8	GJ%ULV	The file used has the lowest generation number because a generation number of -2 was given in the call.
9	GJ%PRO	The protection field of the file specification was given.
10	GJ%ACT	The account field of the file specification was given.
11	GJ%TFS	The file specification is for a temporary file.
12	GJ%GND	Files marked for deletion are not considered when assigning JFNs in subsequent calls. This bit is set if GJ%DEL was not set in the call.
13	GJ%NOD	The node name field of the file specification was given.
17	GJ%GIV	Invisible files were not considered when assigning JFNs.

Examples of the short form of the GTJFN% monitor call are shown in the following paragraphs.

The following sequence of instructions is used to obtain, from the user's terminal, the specification of an existing file.

        MOVX AC1,GJ%OLD+GJ%FNS+GJ%SHT
        MOVE AC2,[.PRIIN,,.PRIOU]
        GTJFN%

The bits specified for AC1 indicate that the file specification given must refer to an existing file (GJ%OLD), that the file specification is to be accepted from the input JFN in AC2 (GJ%FNS), and that the short form of the GTJFN% call is being used (GJ%SHT). Because the right half of AC1 is zero, the standard generation number algorithm will be used. In this GTJFN% call, the file with the highest existing generation number is used. Because GJ%FNS is set in AC1, the contents of AC2 are interpreted as containing an input JFN and an output JFN. In this example, the file specification is obtained from the terminal (.PRIIN).

The following sequence of instructions is used to obtain, from the user's terminal, the specification of an output file and to require confirmation from the user once the file specification has been obtained.

        MOVX AC1,GJ%FOU+GJ%MSG+GJ%CFM+GJ%FNS+GJ%SHT
        MOVE AC2,[.PRIIN,,.PRIOU]
        GTJFN%

In this example, the bits specified for AC1 indicate that

the file obtained is to be an output file (GJ%FOU),
after the file specification is obtained, a message is to be typed (GJ%MSG),
the user is required to confirm the file specification that was obtained (GJ%CFM),
the file specification is to be obtained from the input JFN in AC2 (GJ%FNS),
the short form of the GTJFN% call is being used (GJ%SHT).

Because the right half of AC1 is zero, the generation number given to the file will be one greater than the highest generation number existing for the file. The contents of AC2 are interpreted as containing an input JFN and an output JFN because GJ%FNS is set in AC1.

The following sequence of instructions is used to obtain the name of an existing file from a location in the user's program.

        MOVX AC1,GJ%OLD+GJ%SHT
        MOVE AC2,[POINT 7,NAME]
        GTJFN%
           .
           .
           .

   NAME:ASCIZ/MYFILE.TXT/

The bits specified for AC1 indicate that the file obtained is to be an existing file (GJ%OLD) and that the short form of the GTJFN% call is being used (GJ%SHT). Since the right half of AC1 is zero, the file with the highest generation number will be used. Because GJ%FNS is not set, the contents of AC2 are interpreted as containing a pointer to a string in memory that specifies the file to be associated with the JFN. The setup of AC2 indicates that the string begins at location NAME in the user's program. The file specification obtained from location NAME is MYFILE.TXT.

An alternate way of specifying the same file is the sequence

        MOVX AC1,GJ%OLD+GJ%SHT
        HRROI AC2,[ASCIZ/MYFILE.TXT/]
        GTJFN%

3.3.1.2 Long Form of GTJFN%

The long form of the GTJFN% monitor call requires the following two words of arguments:

              0                        17 18                       35
             !=======================================================!
      AC1    !             0             ! address of argument table !
             !=======================================================!

              0                                                    35
             !=======================================================!
      AC2    !   pointer to ASCIZ file specification string, or 0    !
             !=======================================================!

The argument block for the long form is described in Table 3-4.

Table 3-4: Long Form GTJFN% Argument Block
Word	Symbol	Meaning
0	.GJGEN	Flag bits appear in the left half and generation number appears in the right half.
1	.GJSRC	An input JFN appears in the left half and an output JFN appears in the right half. To omit either JFN, the user's program must specify the symbol .NULIO (377777).
2	.GJDEV	Pointer to ASCIZ string that specifies the device to be used when none is given. If this word is 0, DSK will be used.
3	.GJDIR	Pointer to ASCIZ string that specifies the directory to be used when none is given. If this word is 0, the user's connected directory will be used.
4	.GJNAM	Pointer to ASCIZ string that specifies the filename to be used when none is given. If this word is 0, the input must specify the filename.
5	.GJEXT	Pointer to ASCIZ string that specifies the file type to be used when none is given. If this word is 0, a null type will be used.
6	.GJPRO	Pointer to ASCIZ string or 3B2+octal protection code. This word indicates the protection to be used when none is given. If this word is 0, the protection as specified in the directory will be used.
7	.GJACT	Pointer to ASCIZ string or 3B2+decimal account number. This word indicates the account to be used when none is given. If this word is 0, the account specified when the user logged in will be used.
10	.GJJFN	The JFN to assign to the file specification if flag bit GJ%JFN is set in word .GJGEN (word 0) of the argument block.
11-17		Additional words allowed if flag bit GJ%XTN (bit 15) is set in word .GJGEN (word 0) of the argument block. These additional words are used when performing command input parsing and are described in the TOPS-20 Monitor Calls Reference Manual.

The flag bits accepted in the left half of .GJGEN (word 0) of the argument block are the same as those accepted in the short form of the GTJFN% call. The entire set of flag bits is listed in Table 3-2.

The generation number values accepted in the right half of .GJGEN (word 0) of the argument block can be 0, -1, -2, -3, or a specified number, although 0 is the normal case. Refer to Bits 18-35 of Table 3-2 for explanations of these values.

If execution of the GTJFN% call is successful, the JFN assigned is returned in the right half of AC1 and various bits are set in the left half if flag bits 11, 12 or 13 were on in the call. Refer to Table 3-3 for the explanations of the bits returned. Execution of the program continues at the second instruction following the call.

If execution of the GTJFN call is not successful, the JFN is not assigned and an error code is returned in the right half of AC1. The execution of the program continues at the instruction following the GTJFN% call.

The following sequence of instructions obtains a specification for an existing file from the user's terminal, assigns the JFN to the next higher generation of that file, and specifies default fields to be used if the user omits a field when he gives his file specification.

             MOVEI AC1,JFNTAB
             SETZ AC2,
             GTJFN%
              .
              .
              .
   JFNTAB:   GJ%FOU
             XWD .PRIIN,.PRIOU
             0
             POINT 7,[ASCIZ/TRAIN/]   ;default directory
             0
             POINT 7,[ASCIZ/MEM/]     ;default file type
             0
             0
             0

The address of the argument table for the GTJFN% call (JFNTAB) is given in the right half of AC1. AC2 contains 0, which means no pointer to a string is given; thus, fields for the file specification will be taken only from the user's terminal. The first word of the argument block contains a flag bit for the GTJFN% call. This bit (GJ%FOU) indicates that the next higher generation number is to be assigned to the file. The second word of the argument block indicates that the file specification is to be obtained from the user's terminal, and any output generated because of the user employing recognition is to be printed on his terminal. If the user does not supply a directory name as part of his file specification, the directory <TRAIN> will be used. And if the user does not give a file type, the type MEM will be used. If the user omits other fields from his specification, the system standard value (refer to Table 3-1) will be used.

3.3.1.3 Summary of GTJFN%

The GTJFN% monitor call is required to associate a JFN with a particular file. In most cases, the short form of the GTJFN% call is sufficient for establishing this association. However, the long form is more powerful because it provides the user's program more control over the file specification that is obtained. The following summary compares the characteristics of the two forms of the GTJFN% monitor call.

Short Form	Long Form
Assigns a JFN to a file. System decides the JFN to assign.	Assigns a JFN to a file. User program may request a particular JFN.
Accepts the file specification from a string in memory or a file.	Accepts the file specification from a string in memory and a file.
Uses standard system values for fields not given in the file specification.	Allows user-supplied values to be used for fields not given in the file specification.

3.4 Opening a file

Once a JFN has been obtained for a file, the user's program must open the file in order to transfer data. The user's program supplies the JFN of the file to be opened and a word of bits indicating the desired byte size, data mode, and access to the file.

The desired access to the file is specified by a separate bit for each type of access. The file is successfully opened only if the desired access does not conflict with the current access to the file (refer to Section 3.1). For example, if the user requests both read and write access to the file, but write access is not allowed, then the file is not opened for this user. The allowed types of access to a file are:

Read access. The file can be read with byte, string, or random input.
Write access. The file can be written with byte, string, or random output.
Append access. The file can be written only with sequential byte or dump output, and the current byte pointer (refer to Section 3.5.1) cannot be changed. The initial position of the file pointer is at the end of the file.
Frozen access. The file can be concurrently accessed by at most one user writing the file, but by any number of users reading the file. This is the default access to a file.
Thawed access. The file can be accessed even if other users are reading and writing the file.
Restricted access. The file cannot be accessed if another user already has opened the file.
Unrestricted read access. The file can be read regardless of what other users might be doing with the file.

3.4.1 OPENF% Monitor Call

The OPENF% (Open File) monitor call opens a specified file. It requires the following two words of arguments.

              0                        17 18                       35
             !=======================================================!
      AC1    !             0             ! JFN of file to be opened  !
             !=======================================================!


             0       5 6   9             18               30 31   35
             !=======================================================!
      AC2    !  byte   !data !     0     !    access bits    !   0   !
             !  size   !mode !           !                   !       !
             !=======================================================!

If the left half of AC1 is not 0, the contents of AC1 is interpreted as a pointer to a string, not as a JFN. If the user's program requests bits returned in AC1 from the GTJFN% call, these bits must be cleared before executing the OPENF% call.

The byte size (OF%BSZ) in AC2 specifies the number of bits in each byte of the file and can be between 1 and 36 (decimal). If this field is 0 a byte size of 36 (decimal) is assumed.

The file data mode field (OF%MOD) usually has one of two values:

Value	Meaning
0	Normal data mode of the file (that is, byte I/O). Dump I/O is illegal.
17	Dump mode (that is, unbuffered word I/O). Byte I/O is illegal and the byte size is ignored.

The access bits are described in Table 3-5.

Table 3-5: OPENF% Access Bits
Bit	Symbol	Meaning
0-5	OF%BSZ	Byte size (maximum of 36 decimal).
6-9	OF%MOD	Data mode in which to open file.
18	OF%HER	Halt on the occurrence of an I/O device or medium error during subsequent I/O to the file. If this bit is not set, a software interrupt is generated if a device or medium error occurs during subsequent I/O.
19	OF%RD	Allow read access.
20	OF%WR	Allow write access.
21	OF%EX	Allow execute access.
22	OF%APP	Allow append access.
23	OF%RDU	Allow unrestricted read access.
24		Reserved for Digital.
25	OF%THW	Allow thawed access. If this bit is not set, the file is opened for frozen access.
26	OF%AWT	Block (that is, temporarily suspend) the program until access to the file is permitted.
27	OF%PDT	Do not update the access dates of the file.
28	OF%NWT	Return an error if access to the file cannot be permitted.
29	OF%RTD	Allow access to the file to only one process (that is, restricted access).
30	OF%PLN	Do not check for line numbers in the file.
31	OF%DUD	Suppress system updating of modified pages in memory to thawed files on disk unless CLOSF or UFPGS issued.
32	OF%OFL	Open device even if off-line.
33	OF%FDT	Force update of .FBREF (last read) in FDB and increment RH of .FBCNT (number of references).
34	OF%RAR	Wait if file off-line.

If bits OF%AWT and OF%NWT are both off, an error code is returned if access to the file cannot be permitted (that is, the action taken is identical to OF%NWT being on).

If execution of the OPENF% monitor call is successful, the file is opened, and the execution of the program continues at the second instruction after the OPENF% call.

If execution of the OPENF% call is not successful, the file is not opened, and an error code is returned in AC1. The execution of the program continues at the next instruction after the OPENF% call.

Two samples of the OPENF% call follow.

The sequence of instructions below opens a file for input.

        HRRZ AC1,JFNEXT
        MOVX AC2,FLD(44,OF%BSZ)+OF%RD+OF%PLN
        OPENF%

The JFN of the file to be opened is contained in the location indicated by the address in AC1 (JFNEXT). The bits specified for AC2 indicate that the byte size is one word FLD(44,OF%BSZ), that read access is being requested to the file (OP%RD), and that no check will be made for line numbers in the file; that is, the line numbers will not be discarded (OF%PLN). Because bit OF%THW is not set, the file can be accessed for reading by any number of processes.

The following sequence of instructions can be used to open a file for output.

        MOVE AC1,JFN
        MOVX FLD(7,OF%BSZ)+OF%HER+OF%WR+OF%AWT
        OPENF%

The right half of AC1 contains the address that has the JFN of the file to be opened. The bits specified for AC2 indicate that the byte size is 7-bit bytes FLD(7,OF%BSZ), that the program is to be halted when an I/O error occurs in the file (OF%HER), that write access is being requested to the file (OF%WR), and that the program is to be blocked if access cannot be granted (OF%AWT). Because bit OF%THW is not set, if another user has been granted write access to the file, this user's program will be blocked until access can be granted.

3.5 Transferring data

Data transfers of sequential bytes are the most common form of transfer and can be used with any file. For disk files, nonsequential bytes and entire pages can also be transferred.

3.5.1 File Pointer

Every open file is associated with a pointer that indicates the last byte read from or written to the file. When the file is initially opened, this pointer is normally positioned before the beginning of the file so that the first data operation will reference the first byte in the file. The pointer is then advanced through the file as data is transferred. However, if the file is opened for append-only access (bit OF%APP set in the OPENF% call), the pointer is positioned after the last byte of the file. This allows the first write operation to append data to the end of the file.

For disk files, the pointer may be repositioned arbitrarily throughout the file, such as in the case of nonsequential data transfers. When the pointer is positioned beyond the end of the file, an end-of-file indication is returned when the program attempts a read operation using byte input. When the program performs a write operation beyond the end of the file using byte output, the end-of-file indicator is updated to point to the end of the new data. However, if the program writes pages beyond the end of the file with the PMAP% monitor call (refer to section 3.5.6), the byte count is not updated. Therefore, it is possible for a file to contain pages of data beyond the end-of-file indicator. To allow sequential I/O to be performed later to the file, the program should update the byte count before closing the file. (Refer to the CHFDB% monitor call description in the TOPS-20 Monitor Calls Reference Manual.)

3.5.2 Source and Destination Designators

Because I/O operations occur by moving data from one location to another, the user's program must supply a source and a destination for any I/O operation. The most commonly-used source and destination designators are the following:

A JFN associated with a particular file. The JFN must be previously obtained with the GTJFN% or GNJFN% monitor call before it can be used.
The primary input and output designators .PRIIN and .PRIOU, respectively (refer to Section 2.2). These designators should be used when referring to the terminal.
A byte pointer to the beginning of the string of bytes in the program's address space that is being read or written. The byte pointer can take one of two forms:
- A word with a -1 in the left half and an address in the right half. This form is used to designate a 7-bit ASCIZ string starting in the left-most byte of the specified address. A word in this form is functionally equivalent to a word assembled by the POINT 7,ADR pseudo-op.
- A full word byte pointer with a byte size of 7 bits.

Most monitor calls dealing with strings deal specifically with ASCII strings. Normally, ASCII strings are assumed to terminate with a byte of 0 (that is, are assumed to be ASCIZ strings). However some calls optionally accept an explicit byte count and/or terminating byte. These calls are generally ones that handle non-ASCII strings and byte sizes other than 7 bits.

3.5.3 Transferring Sequential Bytes

The BIN% (Byte Input) and BOUT% (Byte Output) monitor calls are used for sequential byte transfers. The BIN% call takes the next byte from the given source and places it in AC2. The BOUT% call takes the byte from AC2 and writes it to the given destination. The size of the byte is that given in the OPENF% call for the file.

The BIN% monitor call accepts a source designator in AC1, and upon successful execution of the call, the byte is right-justified in AC2. If execution of the call is not successful, an illegal instruction trap is generated. Control returns to the user's program at the instruction following the BIN% call. If the end of the file is reached, AC2 contains 0 instead of a byte. The program can process this end-of-file condition if a jump style error return is the next instruction following the BIN% call.

The BOUT% monitor call accepts a destination designator in AC1 and the byte to be output, right-justified in AC2. Upon successful execution of the call, the byte is written to the destination. If execution of the call is not successful, an illegal instruction trap is generated Control returns to the user's program at the instruction following the BOUT% call.

The following sequence shows the transferring of bytes from an input file to an output file. The bytes are read from the file indicated by INJFN and written to the file indicated by OUTJFN.

        LOOP:  MOVE 1,INJFN      ;get source designator from INJFN
               BIN%              ;read a byte from the source
               ERJMP DONE        ;check for end of file, if 0
        LOOP2: MOVE 1,OUTJFN     ;get destination from OUTJFN
               BOUT%             ;write the byte to the destination
               JRST LOOP         ;continue until 0 byte is found
        DONE:  GTSTS%            ;obtain status of source
               TXNN 2,GS%EOF     ;test for end of file
               JRST NOTYET       ;no, test for 0 in input file
               :                 ;yes, process end of file condition
        NOTYET:MOVEI 2,0         ;0 in input file
               JRST LOOP2

3.5.4 Transferring Strings

The SIN% (String Input) and SOUT% (String Output) monitor calls are used for string transfers. These calls transfer either a string of a specified number of bytes or a string terminated with a specific byte.

The SIN% monitor call reads a string from the specified source into the program's address space. The call accepts four words of arguments in AC1 through AC4.

AC1:	source designator
AC2:	pointer to area in program's address space
AC3:	count of number of bytes to read, or 0
AC4:	byte on which to terminate input (optional)

The contents of AC3 are interpreted as the number of characters to read.

If AC3 is 0, then reading continues until a 0 byte is found in the input.
If AC3 is positive, then reading continues until either the specified number of bytes is read, or a byte equal to that given in AC4 is found in the input, whichever occurs first.
If AC3 is negative, then reading continues until minus the specified number of bytes is read.

The contents of AC4 needs to be specified only if the contents of AC3 is a positive number. The byte in AC4 is right-justified.

The input is terminated when one of the following occurs:

The byte count becomes zero.
The specified terminating byte is reached.
The end of the file is reached.
An error occurs during the transfer (for example, a data error occurs).

Control returns to the user's program at the instruction following the SIN% call. If an error occurs (including the end of the file is reached), an illegal instruction trap is generated. In addition, several locations are updated:

The position of the file's pointer is updated for subsequent I/O to the file.
The pointer to the string in AC2 is updated to reflect the last byte read or, if AC3 contained 0, the last nonzero byte read.
The count in AC3 is updated, if pertinent, by subtracting the number of bytes actually read from the number of bytes requested to be read (that is, the count is updated toward zero). From this count, the user's program can determine the number of bytes actually transferred.

The SOUT% monitor call writes a string from the program's address space to the specified destination. Like the SIN% call, this call accepts four words of arguments in AC1 through AC4.

AC1:	destination designator
AC2:	pointer to string to be written
AC3:	count of the number of bytes to write, or 0
AC4:	byte on which to terminate output (optional)

The contents of AC3 and AC4 are interpreted in the same manner as they are in the SIN% monitor call.

The transfer is terminated when one of the following occurs.

The byte count becomes zero.
The specified terminating byte is reached. This terminating byte is written to the destination.
An error occurs during the transfer.

Control returns to the user's program at the instruction following the SOUT% call. If an error occurs, an illegal instruction trap is generated. In addition, the position of the file's pointer, the pointer to the string in AC2, and the count in AC3, if pertinent, are also updated in the same manner as in the SIN% monitor call.

The following code sequence shows transferring a string from an input file to an output file. The procedure is the same as at the end of Section 3.5.3, using SIN% and SOUT% calls instead of BIN% and BOUT%.

        LOOP:  MOVE 1,INJFN      ;get source from INJFN
               HRROI 2,BUF128    ;pointer to string to read into (128 
                                 ;word buffer)
               MOVNI 3,^D128*5   ;input a maximum of 640 bytes
               SIN%              ;transfer until end of buffer or end of 
                                 ;file
                ERCAL EOFQ       ;error occurred
                   
               ADDI 3,^D128*5    ;determine negative number of 
                                 ;bytes transferred
               MOVN 3,3          ;convert to positive
               MOVE 1,OUTJFN     ;get destination from OUTJFN
               HRROI 2,BUF128    ;pointer to string to write from
               SOUT%             ;transfer as many bytes as read
        EOFQ:  MOVE 1,INJFN
               GTSTS%            ;obtain status of source
               TXNN 2,GS%EOF     ;test for end of file
               RET               ;no, continue copying

3.5.5 Transferring Nonsequential Bytes

As discussed in Section 3.5.3, the BIN% and BOUT% calls transfer bytes sequentially, starting at the current position of the file's pointer. The RIN% (Random Input) and ROUT% (Random Output) monitor calls allow the user's program to specify where the transfer will begin by accepting a byte number within the file. The size of the byte is the size given in the OPENF% call for the file. The RIN% and ROUT% calls can only be used when transferring data to or from disk files.

The RIN% monitor call takes a byte from the specified location in the file and places it into the accumulator. The call accepts the JFN of the file in AC1 and the byte number within the file in AC3. Upon successful completion of the call, the byte is right-justified in AC2, and the file's pointer is updated to point to the byte following the one just read. If an error occurs, an illegal instruction trap is generated. Control returns to the user's program at the instruction following the RIN% call.

The ROUT% monitor call takes a byte from the accumulator and writes it into the specified location in the file. The call accepts the JFN of the file in AC1, the byte to write right-justified in AC2, and the byte number within the file in AC3. Upon successful completion of the call, the byte is written into the specified byte in the file, and the file's pointer is updated to point to the byte following the one just written. If an error occurs, an illegal instruction trap is generated. Control returns to the user's program at the instruction following the ROUT% call.

3.5.6 Mapping Pages

Up to this point, monitor calls have been presented for transferring bytes and strings of data. The next call to be discussed is used to transfer entire pages of data between a file and a process.

Both files and process address spaces are divided into pages of 512(decimal) words. A page within a file can be identified by one word, where the JFN of the file is in the left half and the page number within the file is in the right half. A page within a process address space can also be identified by one word, where the identifier of the process (refer to Section 5.3) is in the left half and the page number within the process' address space is in the right half. Each one-word identifier for the pages in the process address space is placed in what is called the process page map. When identifiers for file pages are placed in the process page map, references to the process page actually refer to the file page. The following diagram illustrates a process map that has identifiers for pages from two files.

                                                File 1
                                                __________
                                               |          |
                  Process Map                  |          |
                  _____________                |          |
                 |             |               |          |
                 |             |               |          |
                 |-------------|               |----------|
                 |JFN1  |Page 1|-------------->| Page 1   |
                 |-------------|               |----------|
                 |             |               |          |
                 |             |               |          |
                 |-------------|               |__________|
                 |             |
                 |             |
                 |             |                File 2
                 |             |                __________
                 |             |               |          |
                 |             |               |          |
                 |-------------|               |----------|
                 |JFN2  |Page 2|-------------->| Page 2   |
                 |-------------|               |----------|
                 |             |               |          |
                 |             |               |          |
                 |_____________|               |          |
                                               |          |
                                               |          |
                                               |__________|

The PMAP% (Page Mapping) monitor call is used to map one or more entire pages from a file to a process (for input), from a process to a file (for output), or from one process to another process. In general, this call changes the entries in the process map by accepting file page identifiers and process page identifiers as arguments. Mapping pages between a file and a process is described below; mapping pages between two processes is described in Chapter 5.

3.5.6.1 Mapping File Pages to a Process

This use of the PMAP% call changes the map of the process so that references to pages in the process reference pages in a file. This does not actually cause data to be transferred; it simply changes the contents of the map. Later when changes are made to the actual page in the process, the changes will also be made to the page in the file, if write access has been specified for the file.

Note that you cannot map file pages to pages in a process section that does not exist in the the process map. If you use PMAP% to input file pages to pages in a nonexistent section of a process, the monitor generates an illegal instruction trap.

In addition, you can map one or more file sections (of 512 pages each) into a process. See Section 8.3.1 for details.

The PMAP% call accepts three words of arguments in AC1 through AC3.

AC1:	JFN of the file in the left half, and the page number in the file in the right half
AC2:	process identifier (refer to Section 5.3) in the left half, and page number in the process in the right half
AC3:	repetition count and access

The repetition count and access bits that can be specified in AC3 are described in Table 3-6.

Table 3-6: PMAP% Access Bits
Bit	Symbol	Meaning
0	PM%CNT	Repeat the mapping operation the number of times specified by the right half of AC3. The file page number and the process page number are incremented by 1 each time the operation is performed.
2	PM%RD	Allow read access to the page.
3	PM%WR	Allow write access to the page.
4	PM%EX	Reserved. The symbol PM%RWX can be used to set B2-4.
5	PM%PLD	Preload page being mapped (move the page immediately instead of waiting until it is referenced).
9	PM%CPY	Create a private copy of the page if the process writes into the page. This is called copy-on-write and causes the map to be changed so that it identifies the copy instead of the original. Write access is allowed to the copy even if it was not allowed to the original. This allows a process to change a page of data without changing the data for other processes that have also mapped the page.
10	PM%EPN	Bits 18-35 of AC2 contain extended (18-bit) process page number. If the section containing the page does not exist, a private section is created.
11	PM%ABT	Unmap page and discard (abort) changed contents.
18-35	PM%RPT	The number of times to repeat the mapping operation if bit 0(PM%CNT) is set.

With this use of the PMAP% call, the present contents of the page in the process are removed. If the page in the file is currently nonexistent, it will be created when it is written.

This use of the PMAP% call is valid only if the file is opened for at least read access. If write access is requested in the PMAP% call, it is not granted unless it was also specified in the OPENF% call when the file was opened.

A file cannot be closed while any of its pages are mapped into any process. Thus, before a file is closed, its pages must be unmapped (refer to Section 3.5.6.3).

After execution of the PMAP% call, control returns to the user's program at the instruction following the call. If an error occurs, an illegal instruction trap is generated.

3.5.6.2 Mapping Process Pages to a File

This use of the PMAP% call actually transfers data by moving the specified page in the process to the specified page in the file. The process map for the page is now empty. Both the page in the process and the page in the file must be private; that is, no other process can have the page mapped into its address space. The ownership of the process page is transferred to the file page. The previous contents of the page in the file are deleted.

The three words of arguments are as follows:

AC1:	process identifier (refer to Section 5.3) in the left half, and page number in the process in the right half
AC2:	JFN of the file in the left half, and the page number in the file in the right half
AC3:	repetition count and access (refer to Section 3.5.6.1)

The access requested in the PMAP% call is granted only if it does not conflict with the access specified in the OPENF% call when the file was opened.

This use of the PMAP% call does not automatically update the files byte count and the byte size. To allow the file to be read later with sequential I/O monitor calls, the program should update the file's byte count and the byte size. (Refer to the CHFDB% monitor call in the TOPS-20 Monitor Calls Reference Manual).

3.5.6.3 Unmapping Pages in a Process

As stated previously, a file cannot be closed if any of its pages are mapped in any process. To unmap a file's pages from a process, the program must execute the SMAP% call, or the following form of the PMAP% call:

AC1:	-1
AC2:	process identifier in the left half, and page number in the process in the right half.
AC3:	the repeat count for the number of pages to remove from the process (refer to Section 3.5.6.1).

3.5.7 Mapping File Sections to a Process

A section of memory is a unit of 512 pages of process address space. File sections also contain 512 pages. The first page of each file section has a page number that is an integral multiple of 512. Like memory pages, sections can be mapped from one process to another, from a process to itself, or from a file to a process. Chapter 8 describes the SMAP% call completely.

The SMAP% (Section Mapping) monitor call is similar to the PMAP% call. The SMAP% call maps one or more sections from a file to a process (for input), or from one process to another process. To map a process section to a file, you must use the PMAP% call as described in Chapter 5 to map each page.

Mapping a file section to a process section with SMAP% does not cause data to move from the disk to memory. Instead, SMAP% changes the contents of the process memory map so that the process section pointer points to a file section. The monitor transfers data only when your program references a memory page to which a file page is mapped.

To map a file section to a process section, SMAP% requires three arguments:

AC1:	source identifier: a JFN in the left half, and a file section number in the right half. If several contiguous sections are to be mapped, the number in the right half is that of the first section in the group of contiguous sections.
AC2:	destination identifier: process identifier in the left half, and a process section number in the right half. If several contiguous sections are to be mapped, the number in the right half is the number of the first section into which SMAP% maps a file section.
AC3:	flags that control access to the process section in the left half, and, in the right half, the number of sections to map into the process. The number of sections to map cannot be less than 1 nor more than 32 (decimal).

The flags in the left half of AC3 are described in Table 3-7.

Table 3-7: SMAP% Access Bits
Bit	Symbol	Meaning
2	SM%RD	Allow read access.
3	SM%WR	Allow write access.
4	SM%EX	Allow execute access.
6	SM%IND	Map the destination section using an indirect section pointer.

3.6 Closing a file

Once data has been transferred to or from a file, the user's program must close the file. When a file is closed, the system automatically performs the following:

Updates the directory information for the file. For example, for a file to which sequential bytes had been written, the byte size and byte count are updated when the file is closed.
Releases the JFN associated with the file. However, the user's program can request to close the file, but retain the JFN assignment. This is useful if the program plans to reopen the same file later, but does not want to execute another GTJFN% call.

3.6.1 CLOSF% Monitor Call

The CLOSF% (Close File) monitor call closes either the specified file or all files that are opened for the process executing the call. The CLOSF% call accepts one word of arguments in AC1 - flag bits in the left half and the JFN of the file to be closed in the right half. The flag bits are described in Table 3-8.

Table 3-8: CLOSF% Flag Bits
Bit	Symbol	Meaning
0	CO%NRJ	Do not release the JFN from the file.
6	CZ%ABT	Abort any output operations currently being done. That is, close the file but do not perform normal cleanup operations (for example, do not output any data remaining in the buffers). If output to a new disk file that has not been closed is aborted, the file is closed and then deleted.
7	CS%NUD	Do not update the copy of the directory on the disk (refer to the CHFDB% description in the TOPS-20 Monitor Calls Reference Manual for more information).

If the contents of AC1 is -1, all files that are opened for this process are closed.

If the execution of the CLOSF% call is successful, the specified file is closed, and the JFN associated with the file is released if CO%NRJ was not set in the call. The execution of the user's program continues at the second location after the CLOSF% call.

If the execution of the CLOSF% call is not successful, the file is not closed and an error code is returned in the right half of AC1. The execution of the user's program continues at the instruction following the CLOSF% call.

The following sequence illustrates the closing of two files.

        CLOSIF:  HRRZ 1,INJFN    ;obtain input JFN
                 CLOSF%          ;close input file
                  ERJMP FATAL    ;if error, print message and stop
        CLOSOF:  HRRZ 1,OUTJFN   ;obtain output JFN
                 CLOSF%          ;close output file
                  ERJMP FATAL    ;if error, print message and stop

3.7 Additional file I/O monitor calls

3.7.1 GTSTS% Monitor Call

The GTSTS% (Get Status) monitor call obtains the status of a file. This call accepts one argument word - the JFN of the file in the right half of the AC1. The left half of AC1 is zero.

Control always returns to the user's program at the instruction following the GTSTS% call. Upon return, appropriate bits reflecting the status of the specified JFN are set in AC2. These bits, and their meanings, are described in Table 3-9. Note that if the JFN is illegal or unassigned, bit 10 (GS%NAM) will not be set.

Table 3-9: Bits Returned on GTSTS% Call

Bit

Symbol

Meaning

GS%OPN

The file is open. If this bit is not set, the file is not open.

GS%RDF

If the file is open (for example, GS%OPN is set), it is open for read access.

GS%WRF

If the file is open, it is open for write access.

GS%XCF

File is open for execute access.

GS%RND

If the file is open, it is open for non-append access (that is, its pointer can be reset).

5-6

Reserved for Digital.

GS%LNG

File has pages in existence beyond page number 511.

GS%EOF

The last read operation to the file was at the end of the file.

GS%ERR

The file may be in error (for example, the bytes read may be erroneous).

GS%NAM

A file specification is associated with this JFN. This bit will not be set if the JFN is in any way illegal.

GS%AST

One or more fields of the file specification associated with this JFN contain a wildcard character.

GS%ASG

The JFN is currently being assigned (that is, a process other than the one executing the GTSTS call is assigning this JFN).

GS%HLT

An I/O error is considered to be a terminating condition for this JFN. That is, the OPENF% call for this JFN had bit OF%HER set.

14-16

Reserved for Digital.

GS%FRK

Access to the file is restricted to only one process.

GS%PLN

If on, file line numbers are passed during input; if zero, line numbers are stripped before input.

19-31

Reserved for Digital.

32-35

GS%MOD

The data mode of the file (refer to the OPENF% call).

Value	Symbol	Meaning
0	.GSNRM	Normal (sequential) I/O
1	.GSSMB	Small buffer mode
10	.GSIMG	Image (binary) I/O
17	.GSDMP	Dump I/O

An example of the GTSTS% call is shown in the first program in Section 3.9.

3.7.2 JFNS% Monitor Call

The JFNS% (JFN to String) monitor call returns the file specification currently associated with the specified JFN. The call accepts three words of arguments in AC1 through AC3.

AC1:	destination designator where the file specification associated with the JFN is to be written. This specification is an ASCIZ string.
AC2:	JFN or pointer to string (see below)
AC3:	format to be used when returning the specification (see below)

The contents of AC1 can be any valid destination designator (refer to Section 3.5.2).

The contents of AC2 can be one of two formats. The first format is a word with either flag bits or 0 in the left half and the JFN in the right half. The bits that can be given in the left half of AC2 are the ones returned from the GTJFN% call (refer to Table 3-3). When the left half of AC2 is nonzero (that is, contains the bits returned from the GTJFN% call), the string returned will contain wildcard characters for appropriate fields and 0, -1, or -2 as a generation number if the corresponding bit is on in the JFNS% call. When the left half of AC2 is 0, the string returned is the exact specification for the file (for example, wildcard characters are not returned for any fields). If the JFN is associated only with a file specification and not with an actual file (that is, bit GJ%OFG was set in the GTJFN% call), the string returned will contain null fields for unspecified fields and the actual values for specified fields. The second format allowed for AC2 is a pointer to the string in the program's address space that is to be returned upon execution of the call. Refer to the TOPS-20 Monitor Calls Reference Manual for the explanation of this format.

The contents of AC3 specify the format in which the specification is written to the destination. Bits 0 through 20 are divided into 3-bit bytes, each byte representing a field in the file specification. The value of the byte indicates the format for that field. The possible values are:

Value	Symbol	Meaning
0	.JSNOF	Do not return this field when returning the file specification.
1	.JSAOF	Always return this field when returning the file specification.
2	.JSSSD	Suppress this field if it is the standard system value for this field (refer to Table 3-1).

If the contents of AC3 is zero, the file specification is written in the format

        dev:<directory>name.typ.gen;T

with fields the same as the standard system value (see Table 3-1) not returned and protection and account fields returned only if bit 9 and bit 10 in AC2 are on, respectively. The temporary attribute (;T) is returned only if the file is temporary.

Table 3-10 describes the bits that can be set in AC3.

Table 3-10: JFNS% Format Options
Bit	Symbol	Meaning
0	JS%NOD	Print node name if node name is present.
1-2	JS%DEV	Format for device field.
3-5	JS%DIR	Format for directory field.
6-8	JS%NAM	Format for filename field. A value of 2 (that is, bit 7 set) for this field is illegal.
9-11	JS%TYP	Format for file type field. A value of 2 (that is, bit 10 set) for this field is illegal.
12-14	JS%GEN	Format for generation number field.
0-14	JS%SPC	Output for all file specification fields named above. This field should have the same bits set as would be set in the fields above. (See B35 (JS%PAF) below.)
15-17	JS%PRO	Format for protection field.
18-20	JS%ACT	Format for account field.
21	JS%TMP	Return temporary file indication ;T if the file specification is for a temporary file.
22	JS%SIZ	Return size of file in pages (see below).
23	JS%CDR	Return creation date of file (see below).
24	JS%LWR	Return date of last write operation to file (see below).
25	JS%LRD	Return date of last read operation from file (see below).
26	JS%PTR	AC2 contains a pointer to the string containing the field to be returned (refer to the TOPS-20 Monitor Calls Reference Manual for a description of this use of the JFNS% call).
27	JS%ATR	Return file specification attributes if appropriate.
28	JS%AT1	Return specification attribute referenced in AC4.
29	JS%OFL	Return the "OFF-LINE" attribute.
30-31		Reserved for Digital.
32	JS%PSD	Punctuate the size and date fields (see below) in the file specification returned.
33	JS%TBR	Place a tab before all fields returned (that is, fields whose value is given as 1 in the 3-bit field) in the file specification, except for the first field.
34	JS%TBP	Place a tab before all fields that may be returned (that is, fields whose value is given as 1 or 2 in the 3-bit field) in the file specification, except for the first field.
35	JS%PAF	Punctuate all fields (see below) returned in the file specification from the device field through the ;T field. If bits 32 through 35 are not set, no punctuation is used between the fields.

The punctuation used on each field is shown below.

        dev:<directory>name.typ.gen;A(account);P(protection);T(temporary),size,creation date,write date,read date

Refer to Section 1.2.2 for information on error returns.

3.7.3 GNJFN% Monitor Call

Occasionally a program may be written to perform similar operations on a group of files instead of only on one file. However, the program should not require the user to give a file specification for each file. Because the GTJFN% call associates a JFN with only one file at a time, the program needs a method of assigning a JFN to all the files in the group. By using the GTJFN% call to initially obtain the JFN and the GNJFN% call to assign the same JFN to each subsequent file in the group, a program can accept a specification for a group of files and process each file in the group individually. After the user gives the initial file specification, the program requires no additional input.

Before an example showing the interaction of these two calls is given, a description of the GNJFN% (Get Next JFN) monitor call is appropriate.

The GNJFN% monitor call assigns a JFN to the next file in a group of files that have been specified with wildcard characters. The next file is determined by searching the directory in the order described in Section 3.3.1.1 using the current file as the first item. This call accepts one argument word in AC1 - the flags returned from the GTJFN% call in the left half and the JFN of the current file in the right half. In other words, the information returned in AC1 from the GTJFN% call is given as an argument to the GNJFN% call. Therefore, the program must save this information for use with the GNJFN% call.

If execution of the GNJFN% call is successful, the same JFN is assigned to the next file in the group. The left half of AC1 contains various flags and the right half contains the JFN. The execution of the program continues at the second instruction after the GNJFN% call.

Table 3-11 describes the bits that can be returned in AC1 on a successful GNJFN% call.

Table 3-11: GNJFN% Return Bits
Bit	Symbol	Meaning
13	GN%STR	A change in structure occurred between the previous file and this file.
14	GN%DIR	A change in directory occurred between the previous file and this file.
15	GN%NAM	A change in filename occurred between the previous file and this file.
16	GN%EXT	A change in file type occurred between the previous file and this file. If GN%NAM is on, this bit will also be on because the system considers two files with different filenames but with the same file type as a change in both the name and type.

If execution of the GNJFN% call is not successful, an error code is returned in the right half of AC1. Conditions that can cause an error return are:

The file currently associated with the JFN must be closed, and it is not. This means that the program must execute a CLOSF% call (with CO%NRJ set to retain the JFN) before executing a GNJFN% call.
There are no more files in this group. This return occurs on the first GNJFN% call after all files in the group have been stepped through. The JFN is released when there are no more files. (Note: This error may occur if the file currently associated with the JFN is deleted or renamed.)

The execution of the program continues at the next instruction after the GNJFN% call.

Consider the following situation. The user wants to write a program that will accept from his terminal a specification for a group of files and then perform an operation on each file individually without requiring additional input. Assume the user's directory <TRAIN> contains the following files:

        FIRST.MAC.1
        FIRST.REL.1
        SECOND.REL.1
        THIRD.EXE.1

As discussed in Section 3.3.1.1, a group of files can be given to the GTJFN call by supplying a specification that contains wildcard characters in one or more of its fields. Thus, the specification

        <TRAIN>*.*

would refer to all four files in the user's directory <TRAIN>.

In his program, the user includes a GTJFN% call that will accept the above specification.

The call is

        MOVX AC1,GJ%OLD+GJ%IFG+GJ%FLG+GJ%FNS+GJ%SHT
        MOVE AC2,[.PRIIN,,.PRIOU]
        GTJFN%

and indicates that

The file specification given must refer to an existing file (GJ%OLD).
The file specification given is allowed to contain wildcard characters (GJ%IFG).
Flags will be returned in AC1 on a successful call (GJ%FLG). The flags must be returned because they will be given to the GNJFN% call as arguments.
The contents of AC2 will be interpreted as containing an input and output JFN (GJ%FNS).
The short form of the GTJFN% call is being used (GJ%SHT).
The file specification is to be read from the user's terminal (.PRIIN,,.PRIOU).

When the user types the specification <TRAIN>*.* as input, the system associates the JFN with one file only. This file is the first one found when searching the directory in the order specified in Section 3.3.1.1. Thus the JFN returned is associated with the file FIRST.MAC.1.

After the GTJFN% call is successfully executed, AC1 contains appropriate flags in the left half and the JFN assigned in the right half. The flags that will be returned in this particular situation are:

GJ%NAM (bit 3)	A wildcard character appeared in the name field of the file specification given.
GJ%EXT (bit 4)	A wildcard character appeared in the type field of the file specification given.
GJ%GND (bit 12)	Any files marked for deletion will not be considered.

These flags inform the program of the fields that contained wildcard characters. The user's program must now save the contents of AC1 because this word will be used as the argument to the GNJFN% call. The program then performs its desired operation on the first file. Once its processing is completed, the program is ready for the specification of the next file. But instead of requesting the specification from the user, the program executes the GNJFN% call to obtain it. The argument to the GNJFN% call is the contents of AC1 returned from the previous GTJFN% call. Thus, the call in this case is equivalent to:

        MOVE AC1,[GJ%NAM+GJ%EXT+GJ%GND,,JFN]
        GNJFN%

Upon successful execution of the GNJFN% call, the JFN is now associated with the next file in the group (that is, FIRST.REL.1). AC1 contains appropriate flags in the left half and the same JFN in the right half. In this example, the flag returned is GN%EXT (bit 16) to indicate that the file type changed between the two files.

After processing the second file, the user's program executes another GNJFN% call using the original contents of AC1 returned from the GTJFN% call. The original contents must be used because this word indicates the fields containing wildcard characters. If the current contents of AC1 (that is, the flags returned from the GNJFN% call) are used, a subsequent GNJFN% call would fail because there are no flags set indicating fields containing wildcard characters. This second GNJFN% call associates the JFN with the file SECOND.REL.1. The flags returned in AC1 are GN%NAM (bit 15) and GN%EXT (bit 16) indicating that the filename and file type changed between the two files. (Remember that a change in filename implies a change in file type even if the two file types are the same.)

After processing this third file, the user's program executes another GNJFN% call using the original contents of AC1. Upon execution of the call, the JFN is now associated with THIRD.EXE.1, and the flags returned are GN%NAM and GN%EXT, indicating a change in the filename and file type.

After processing the file THIRD.EXE.1, the user's program executes a final GNJFN% call. Since there are no more files in the group, the call returns an error code and releases the JFN. Execution of the user's program continues at the instruction following the GNJFN% call.

3.8 SUMMARY

To read from or write to a file, the user's program must:

Obtain a JFN on the file with the GTJFN% monitor call (refer to Section 3.3.1).
Open the file with the OPENF% monitor call (refer to Section 3.4.1).
Transfer the data with byte, string, or page I/O monitor calls (refer to Section 3.5).
Close the file with the CLOSF% monitor call (refer to Section 3.6.1).

3.9 FILE EXAMPLES

Example 1

This program assigns JFNs, opens an input file and an output file, and copies data from the input file to the output file. Data is copied until the end of the input file is reached. Refer to the TOPS-20 Monitor Calls Reference Manual for explanation of the ERSTR% monitor call.

   ;*** PROGRAM TO COPY INPUT FILE TO OUTPUT FILE. ***
   ;       (USING BIN%/BOUT% AND IGNORING NULLS)

           TITLE FILEIO            ;TITLE OF PROGRAM
           SEARCH MONSYM           ;SEARCH SYSTEM JSYS-SYMBOL LIBRARY
           SEARCH MACSYM
           .REQUIRE SYS:MACREL

   ;*** IMPURE DATA STORAGE AND DEFINITIONS ***


   INJFN:  BLOCK 1                 ;STORAGE FOR INPUT JFN
   OUTJFN: BLOCK 1                 ;STORAGE FOR OUTPUT JFN
           PDLEN=3                 ;STACK HAS LENGTH 3
   PDLST:  BLOCK PDLEN             ;SET ASIDE STORAGE FOR STACK

           STDAC.                  ;DEFINE STANDARD ACs. SEE MACSYM.

   ;*** PROGRAM INITILIZATION ***

   START:  RESET%                  ;CLOSE FILES, ETC.
           MOVE P,[IOWD PDLEN,PDLST] ;ESTABLISH STACK

   ;***  GET INPUT FILE ***

   INFIL:                          ;PROMPT FOR INPUT FILE
           TMSG <
   INPUT FILE: >                   ;ON CONTROLLING TERMINAL
           MOVX T1,GJ%OLD+GJ%FNS+GJ%SHT ;SEARCH MODES FOR GTJFN
                                   ;EXISTING FILE ONLY, FILE-NRs IN B
                                   ;SHORT CALL
           MOVE T2,[.PRIIN,,.PRIOU] ;GTJFN'S I/O WITH CONTROLLING TERM
           GTJFN%                  ;GET JOB FILE NUMBER (JFN)
            ERJMPS [ PUSHJ P,WARN  ;IF ERROR, GIVE WARNING
                     JRST INFIL]   ;AND LET HIM TRY AGAIN
           MOVEM T1,INJFN          ;SUCCESS, SAVE THE JFN

   ;*** GET OUTPUT FILE ***

   OUTFIL:                         ;PRINT PROMPT FOR
           TMSG <
   OUTPUT FILE: >                  ;OUTPUT FILE
           MOVX T1,GJ%FOU+GJ%MSG+GJ%CFM+GJ%FNS+GJ%SHT ;GTJFN SEARCH MODES
                                   ;[DEFAULT TO NEW GENERATION, PRINT
                                   ; MESSAGE, REQUIRE CONFIRMATION
                                   ; FILE-NR'S IN T2, SHORT CALL ]
           MOVE T2,[.PRIIN,,.PRIOU] ;I/O WITH CONTROLLING TERMINAL
           GTJFN%                  ;GET JOB FILE NUMBER
            ERJMPS [ PUSHJ P,WARN  ;IF ERROR, GIVE WARNING
                    JRST OUTFIL]   ;AND LET HIM TRY AGAIN
           MOVEM T1,OUTJFN         ;SAVE THE JFN

   ;NOW, OPEN THE FILES WE JUST GOT

   ;   INPUT

           MOVE T1,INJFN           ;RETRIEVE THE INPUT JFN
           MOVX T2,FLD(7,OF%BSZ)+OF%RD ;MODES FOR OPENF 
                                   ;[7-BIT BYTES + INPUT]
           OPENF%                  ;OPEN THE FILE
            ERJMPS FATAL           ;IF ERROR, GIVE MESSAGE AND STOP

   ;   OUTPUT

           MOVE T1,OUTJFN          ;GET THE OUTPUT JFN
           MOVX T2,FLD(7,OF%BSZ)+OF%WR ;MODES FOR OPENF 
                                   ;[7-BIT BYTES + OUTPUT]
           OPENF%                  ;OPEN THE FILE
            ERJMPS FATAL           ;IF ERROR, GIVE MESSAGE AND STOP


   ;*** MAIN LOOP: COPY BYTES FROM INPUT TO OUTPUT ***

   LOOP:   MOVE T1,INJFN           ;GET THE INPUT JFN
           BIN%                    ;TAKE A BYTE FROM THE SOURCE
           JUMPE T2,DONE           ;IF 0, CHECK FOR END OF FILE
           MOVE T1,OUTJFN          ;GET THE OUTPUT JFN
           BOUT                    ;OUTPUT THE BYTE TO DESTINATION
            ERCALS ERROR
           JRST LOOP               ;LOOP, STOP ONLY ON A 0 BYTE
                                   ;(FOUND AT LOOP+2)


   ;*** TEST FOR END OF FILE, ON SUCCESS FINISH UP ***

   DONE:   GTSTS%                  ;GET THE STATUS OF INPUT FILE
           TXNN T2,GS%EOF          ;AT END OF FILE?
           JRST LOOP               ;NO, FLUSH NULL AND CONTINUE COPY

   CLOSIF: MOVE T1,INJFN           ;YES, RETRIEVE INPUT JFN
           CLOSF%                  ;CLOSE INPUT FILE
            ERJMPS FATAL           ;IF ERROR, GIVE MESSAGE AND STOP

   CLOSOF: MOVE T1,OUTJFN          ;RETRIEVE OUTPUT JFN
           CLOSF%                  ;CLOSE OUTPUT FILE
            ERJMPS FATAL           ;IF ERROR, GIVE MESSAGE AND STOP
           TMSG <
   [DONE]>                         ;SUCCESSFULLY DONE
           JRST ZAP                ;STOP

   ;*** ERROR HANDLING ***

   FATAL:  TMSG <
   ?>                              ;FATAL ERRORS PRINT ? FIRST
           PUSHJ P,ERROR           ;THEN PRINT ERROR MESSAGE
           JRST ZAP                ;AND STOP

   WARN:   TMSG <
   %>                              ;WARNINGS PRINT % FIRST
                                   ;AND FALL THRU 'ERROR' 
                                   ;BACK TO CALLER

   ERROR:  MOVEI T1,.PRIOU         ;DECLARE PRINCIPAL OUTPUT DEVICE
                                   ;FOR ERROR MESSAGE
           MOVE T2,[.FHSLF,,-1]    ;CURRENT FORK,, LAST ERROR
           SETZ T3,                ;NO LIMIT,, FULL MESSAGE
           ERSTR%                  ;PRINT THE MESSAGE
            JFCL                   ;IGNORE UNDEFINED ERROR NUMBER
            JFCL                   ;IGNORE ERROR DURING EXE OF ERSTR
           POPJ P,                 ;RETURN TO CALLER

   ZAP:    HALTF%                  ;STOP
           JRST START              ;WE ARE RESTARTABLE
           END START               ;TELL LINKING LOADER START ADDRESS

Example 2

This program accepts input from a user at the terminal and then outputs the data to the line printer. Refer to Section 2.9 for explanation of the RDTTY% call.

           TITLE LPTPNT            ;PROGRAM TO PRINT TERMINAL INPUT 
                                   ;ON PRINTER
           SEARCH MONSYM           ;SEARCH SYSTEM JSYS-SYMBOL LIBRARY
           SEARCH MACSYM
           .REQUIRE SYS:MACREL

           STDAC.                  ;DEFINE STANDARD ACs

   BUFSIZ==200
   PDLEN==50

   COUNT:  BLOCK 1
   LPTJFN: BLOCK 1
   BUFFER: BLOCK BUFSIZ
   PDL:    BLOCK PDLEN

   START:  RESET%                  ;RESET I/O, ETC.
           MOVE P,[IOWD PDLEN,PDL] ;SET UP STACK
           TMSG <ENTER TEXT TO BE PRINTED (END WITH ^Z):
   >                               ;OUTPUT PROMPTING TEXT
           HRROI T1,BUFFER         ;GET POINTER TO BUFFER
           MOVE T2,[RD%BRK+BUFSIZ*5] ;GET FLAG AND MAX # OF CHARS TO READ
           SETZM T3                ;NO RE-TYPE BUFFER
           RDTTY%                  ;INPUT TEXT FROM TERMINAL
            EJSHLT                 ;ERROR, STOP
           HRRZS T2                ;GET CHARS REMAINING IN BUFFER
           MOVEI T1,BUFSIZ*5       ;COMPUTE NUMBER OF CHARS READ = 
           SUB T1,T2               ;BUFFERSIZE MINUS CHARS REMAINING
           SOS T1                  ;DON'T INCLUDE ^Z
           MOVEM T1,COUNT          ;SAVE # OF CHARS INPUT
   ;GET A JFN FOR THE PRINTER AND OPEN THE PRINTER

           MOVX T1,GJ%SHT!GJ%FOU   ;OUTPUT FILE, SHORT CALL
           HRROI T2,[ASCIZ /LPT:/] ;GET POINTER TO NAME OF FILE
           GTJFN%                  ;GET A JFN FOR THE PRINTER
            ERJMPS JFNERR          ;ERROR, PRINT ERROR MESSAGE
           MOVEM T1,LPTJFN         ;REMEMBER PRINTER JFN
           MOVX T2,FLD(7,OF%BSZ)+OF%WR ;7-BIT BYTES, 
                                   ;WRITE ACCESS WANTED
           OPENF%                  ;OPEN THE PRINTER FOR OUTPUT
            ERJMPS OPNERR          ;ERROR, PRINT ERROR MESSAGE

   ;NOW OUTPUT THE TEXT THAT WAS INPUT FROM THE TERMINAL
           
           HRROI T2,BUFFER         ;GET POINTER TO TEXT 
                                   ;(PRINTER JFN STILL IN T1)
           MOVN T3,COUNT           ;GET NUMBER OF CHARS TO OUTPUT
           SOUT%                   ;OUTPUT STRING OF CHARS TO 
                                   ;THE PRINTER
            ERJMPS DATERR          ;ERROR, PRINT ERROR MESSAGE
           TMSG <
   OUTPUT HAS BEEN SENT TO THE PRINTER...
   >                               ;OUTPUT CONFIRMATION MESSAGE
           MOVE T1,LPTJFN          ;GET PRINTER JFN
           CLOSF%                  ;CLOSE IT
            ERJMPS DATERR          ;UNEXPECTED ERROR, PRINT ERROR MESSAGE
           HALTF%                  ;FINISHED
           JRST START              ;IF CONTINUED, GO BACK TO START

   ;ERROR ROUTINES

   JFNERR: TMSG<
   ? COULD NOT GET A JFN FOR THE PRINTER
   >
           HALTF%
           JRST START              ;IF CONTINUED, GO BACK TO START

   OPNERR: TMSG<
   ? COULD NOT OPEN THE PRINTER FOR OUTPUT
   >
           HALTF%
           JRST START              ;IF CONTINUED, GO BACK TO START

   DATERR: TMSG<
   ? DATA ERROR DURING OUTPUT TO PRINTER
   >
           HALTF%
           JRST START              ;IF CONTINUED, GO BACK TO START

           END START

Navigation

Topics

TOPS-20 Monitor Calls User's Guide

Chapter 3 Using files

3.1 Overview

3.2 Job File Number

3.3 Associating a file with a JFN

3.3.1 GTJFN% Monitor Call

3.3.1.1 Short Form of GTJFN%

3.3.1.2 Long Form of GTJFN%

3.3.1.3 Summary of GTJFN%

3.4 Opening a file

3.4.1 OPENF% Monitor Call

3.5 Transferring data

3.5.1 File Pointer

3.5.2 Source and Destination Designators

3.5.3 Transferring Sequential Bytes

3.5.4 Transferring Strings

3.5.5 Transferring Nonsequential Bytes

3.5.6 Mapping Pages

3.5.6.1 Mapping File Pages to a Process

3.5.6.2 Mapping Process Pages to a File

3.5.6.3 Unmapping Pages in a Process

3.5.7 Mapping File Sections to a Process

3.6 Closing a file

3.6.1 CLOSF% Monitor Call

3.7 Additional file I/O monitor calls

3.7.1 GTSTS% Monitor Call

3.7.2 JFNS% Monitor Call

3.7.3 GNJFN% Monitor Call

3.8 SUMMARY

3.9 FILE EXAMPLES

Example 1

Example 2