OPEN-FILE BLOCKS

subroutines openf,  open_term  and  open_ins

iuins=4
iuterm=10
call open_ins (iuins,'default.ins')
call open_term (iuterm)
call openf (iuins)


Of these,  openf  processes open-file blocks

Run-time method to connect files to units utilized by Fortran programs.
This page: |  RulesOptions  |  File namesComments  |

Rules:

An open-file instruction consists of
logical unit number, option, string

Fixed format for an instruction is

IU O file_name     [comment]      File unit, Option, name [and comment]
  | |
nn|c|ccccccccc       ccccccc       symbols: number, character, blank  [optional]... repeat
..b.b.........b[b...]........
    |<-max64->
    |<--------max 128-------->

 (Fortran:  I2,1X,A1,1X,A)

String (max 128 characters) is split into filename (max 64 characters) and comment
at the first nonblank after the first blank after the file name.
String may incorporate environment parameters in the usual forms: $var or ${var}.
 

One block of instructions is processed per call of the OPENF subroutine (/home/hgs/util/p/openfs.f)
Provided the file unit numbers a different, up to 99 files could be opened. However, it will
depend on the program which of these files are read and written to.

Every program manual (comment part) ought to instruct the user which file units are expected to
become opened at run-time, along with the necessary information as to whether these are binary
or ASCII files, whether they are read only or new etc.

If two unit numbers occur twice in the same scope of the program, the previous file will
disconnected.

If a unit is not connected to a file, the Fortran rule takes over; i.e. file will be created named
ftnnn  if possible, else program will abort.

If a file is connected for binary I/O and a formatted read or write command acts on it and vice versa,
the program will abort.

In dialog mode, if errors occur, the program may ask the user. for instance if the user tried to open
a nonexisting file with options O, #, R or ^, the system will tell that the file is not there and present
alternatives, prompt again to correct a misspelling, to ignore the entry or to stop the program.

There are several features that permit to arrive at the same open-file situation along different routes.
They involve shorthand notations, user interaction, and environment parameters.


Example of an instruction file in a csh-script. Note especially the first two unsetenv's and the TER:
unsetenv tty
unsetenv term
set date = 2011,3,20
# et cetera
mainpgm <<ENDINS
TER:
13 R $ttab
31 B $outf
   Q
 &param
 date=$date, hms=$hms
 dt=$dt, tscale=$tscale
 iun=31
 nout=$nout
 &end
ENDINS


 Options:

ASCII Binary File opening options
B < Read/write, status UNKNOWN
O # Read, status OLD                                   )
R ^ Read, status READ ONLY                     )
N + Write, status NEW
A > Write, append, status UNKNOWN
E U Write, append, status OLD                     )

%
Read, status OLD, BIG_ENDIAN
 ) File must exist, else failure.
 

End of  open-file block
Q quit open block (synonymous: @ - _ / % .
] Stop program (only in prompt mode)
} Stop program

A unit number less than 0 terminates block. 

In dialogue mode, an empty line terminates block.



Commentary options
* don't do anything. Serves as a comment in the open-file block.
L don't do anything. The string can be used by
    QLoc_In_File (.,.,'O') 
C Print string as a comment.



Directory option
D "Change directory" to the specified name; subsequent file names will be prepended by this namestring. Automatic right-completion with "/" if necessary. 
Code ". " for namestring to reset directory string to empty. 
Code "?"  for namestring to inquire the current directory. 
See paragraph on "File names" below.



Prompting options
P Prompt user with message string to specify a file name to be  connected with the specified unit number.  Expect next open-file instruction to be entered at the keyboard. I/O uses units 5 and 6    *)
T Prompt user like P, using unit IUTERM for the dialog, however.   **)



Special
S Send string as a UNIX command to the system. 
If a current DIR is defined (D-option), the sequence 
    'cd DIR; '//string   is submitted.                                        #)
? Only in dialogue mode, i.e. if the OPENF routine was called to process the open-file block through the stdin-unit (IUN=5): 
Inquire the file by name or  by logical unit number.                         +)
*)   Example
31 P Binary output file - specify name:
   Q

**) This feature must be activated by the calling program as follows:
        IUTERM=10
        CALL OPEN_TERM (IUTERM)
    This call requires that the environment variables $term and $tty
    have been set. C.f. /home/hgs/util/p/openins.f

#)   Note that you cannot change a directory beyond the scope of the
      system call. Looks like a rather useless feature.

+)  Useful together with dialog. Example
      31 ?
     will cause OPENF to issue an  INQUIRE by unit number. If the unit is
     connected to a file, its name will be printed.
      00 ? /vlbi/hgs/Oload/csrM2.dat
     will cause OPENF to issue a INQUIRE by file name. A message will
     be printed as to whether the file exists.

Hidden option in column 5:
A `. character in column 5 will indicate binary records as blocked. Default is not blocked.
In the Fortran OPEN statement, this corresponds with BLOCK=-1 (not blocked, default) or, respectively, BLOCK=1.


File names

We distinguish between short file names and completed file names.
Completion implies
  1. left-adding the directory string if defined,
  2. resolving of environment variables
  3. replacing  ? with keyboard entry
at run-time.

If a file name does contain a $ sign it must be coded $$ in order to prevent
environment variable spawning, which would probably lead to failure.

If a directory string is defined (D-option) it will be added unless ...
the file name starts with
/   - it will be treated as a complete path and file name
      starting at the root of the file system;
~   -  '/home/' is substituted;
~/  - the user's $HOME environment parameter is substituted;
./  - the file is supposed to be located relative to the directory
              from which the main program was launched;
&/  - ... relative the directory of the file containing the instruction block.

Hence, if the current directory is /home/user/OTEQ and the instruction file
for program  cream  is reached with  MODEL/cream.ins,
31 B &/FLZU.DAT
appearing in an open-file block inside cream.ins will open the file  MODEL/FLZU.DAT

If the directory string is empty, file locations will be relative the
directory from which the program was launched.

The symbolic path symbols  ~ ~/ and &/ also work with the directory option (D).

Example:
Assume the following block occurs in an instruction file residing
in directory /home/office/arrange

   D /home/guest/travel
20 O take_the_?.train
21 O arrival.dat
22 O goodbye.dat
31 N arrange_${GUEST_PREF}.dat
32 A ~/hotel/myrecords
   D &/SUB
33 N sleep.well
   Q

The first four files are found in directory /home/guest/travel, the last one
in /home/office/arrange/SUB
The file on unit 32 (opened for Append) is located in /home/office/hotel/myrecords

Before running the program that reads this open-file block, the environment variable
GUEST_PREF must be set with a permissible value. Suppose we have three files,
arrange_simple.dat arrange_standard.dat and  arrange_luxory.dat
Then we can use e.g.
setenv GUEST_PREF luxory
to connect the third of the arrange-files.

At run-time the program will prompt
<OPENF->?> Enter replacement for ? in "take_the_?.train" :
You may enter A if file take_the_A.train exists,
else the program aborts since the opening option was O (=old; with B the file would have been created (empty)).


Comments:

The short, symbolic file name is printed on the protocol; if more information
is desired, code a ! or ? mark in the comment part of the record..

Example:
41 B &/olsha.rsl-tmp !


Special instruction:

iu P string
nn T string

Prompt user with  string   as the prompting message.
User support will be provided  if open on next file fails.
Under option T  the terminal unit will be used for the dialog  (declared by  CALL OPEN_TERM (IUTERM) )
Under option  P  units 5 (input) and 6 (output) will be used for the dialog.

Example (MS-DOS PC):
   P
31 B A:\FLMHU.DAT      Flag array

... useful if e.g. the user might insert the wrong diskette.

| Back to HOW_TO  |  Back to General Information  |

.bye