OPEN-FILE BLOCKS

subroutines openf,  open_term  and  open_ins

Rules:

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

Example:

31 B /vlbi/hgs/Otide/csrtM2.dat   Tide array
   Q                              End block, quit

This block opens a file named  /vlbi/hgs/Otide/csrtM2.dat on unit 31 for ASCII read/write.
Comment 'Tide array' will be written to protocol file and saved internally.
The Q record terminates the block.

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 with environment variables:
31 < $MYTMP/Otide/csrtM2.dat
32 B /geo/hgs/gps/${SITA}${SITB}_baseline.dat
   Q

Unix command (csh/tcsh)
setenv MYTMP /vlbi/hgs
will assign a proper value to MYTMP.

Examples with user interaction:
   D $MYTMP/Otide
31 P Specify binary input file relative path above :
   Q

31 < $MYTMP/Otide/csrt?.dat
   Q

---

 Options:

**) 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

1. left-adding the directory string if defined,
2. resolving of environment variables
3. replacing  ? with keyboard entry

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:

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

Special instruction:

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