OPENING INSTRUCTION FILES FOR RUNNING PROGRAMS

Open_Ins  Fortran subroutine, file is  /home/hgs/util/p/openins.f

Synopsis of user responsesRequirements for useOpen_Ins for Fortran programmers  |  The Label mechanism  |

Purpose:
Instruction files contain program directives which are subject to change
(frequent to infrequent), directives that can be anticipated as opposed to
direct user interaction. This applies to many FORTRAN programs
in the catalogues under .../hgs/...

This document instructs how to attach (a section of ) an instruction file.

Conventions for this document:
User entries at the keyboard are written            in this style.
System responses are shown                               in this style.
File contents are shown                             in this style.
Variables to be replaced by values are shown  in this style.

Program prompter and responses:
Typically, a prompter will appear soon after starting a program. Example

$ pwd
/home/hgs/Oload
$ olmpp
 <OpenIn>>> Your terminal: /dev/pty/ttyq3 (I suppose)
 <OpenIn>>> Open Terminal = /dev/pty/ttyq3, unit was   2
 > *.ins file (olmpp.ins)>

The simplest response to this is to hit Return.
By that you confirm the suggestion to use ./olmpp.ins as the current instruction file
and ask the program to start processing at the top. You can enter the name of
a directory (keep a trailing slash) to read from olmpp.ins from a different catalog.
If you want to process an instruction file with a different name you specify that
name; if the name contains no dot, the extension .ins will be added automatically

An alternative is to start the program with the response to the prompting line
anticipated on the call line. Suppose the instruction file you want to use is called
lepr/olmpp-special.ins
Then you start the program as follows:
$ olmpp lepr/olmpp-special
 <OpenIn>>> Your terminal: /dev/pty/ttyq3 (I suppose)
 <OpenIn>>> Open Terminal = /dev/pty/ttyq3, unit was   2
 > *.ins file (olmpp.ins)> $

The Dollar response tells the program not to use the default but rather the first
argument of the call line.

To avoid the prompt altogether, enter
$ olmpp '!lepr/olmpp-special'
The first character ! determines that.
A recent alternative is `@ for `!

A collection of responses is given below.

The label mechanism.
Ideally, one instruction file per program could suffice
The program is supposed to read lines from the instruction file
while it executes
There is a label mechanism which can be employed to identify
a specific section of instruction code to the main program for
a particular run.

Suppose file lepr/olmpp-special.ins contains


code
...
code


default section
SEG1>
code
...
code

segment 1
...

...
SEGn>
code
...
code

segment n

To process with the instructions after SEG1> start the program by either

$ olmpp
 <OpenIn>>> Your terminal: /dev/pty/ttyq3 (I suppose)
 <OpenIn>>> Open Terminal = /dev/pty/ttyq3, unit was   2
 > *.ins file (olmpp.ins)> lepr/olmpp-special >SEG1>

or

$ olmpp lepr/olmpp-special '>SEG1>'
 <OpenIn>>> Your terminal: /dev/pty/ttyq3 (I suppose)
 <OpenIn>>> Open Terminal = /dev/pty/ttyq3, unit was   2
 > *.ins file (olmpp.ins)> $
1)

If, however, the default file name is alright,
$ olmpp '>SEG1>'
1)

will do. If no label is given, the default section will be processed.

1) Note the quotes, which are needed to prevent the shell from handling the > character.

Quick and easy, recently introduced, avoiding the quotes:
$ olmpp @lepr/olmpp-special :SEG1
to start without prompting.

Back to top

Requirements for use:
The program environment must contain nonempty definitions of

   tty
   term

A value for tty can be taken prom the TTY-column of the unix command ps (no options).
A value for term can be taken from the TERM environment variable. If it happens to be unset, a string
like XTERM will most likely fulfill the requirement. Thus,

$ echo $TERM
xterm
$ setenv term xterm
$ ps
   PID TTY       TIME COMMAND
  4781 ttyq3     0:00 sh
 20548 ttyq3     0:00 ps
$ setenv tty ttyq3
 

In the tcsh-enviroment, you can add to your .login or .(t)cshrc file
setenv term $TERM
setenv tty `ps | tail -1 |  cut -f2 -d' '`

Back to top

Subroutine Open_Ins
Guidelines for Fortran programmers

      IUTERM=nt
      IUINS=ni
      SUGGESTED_FILENAME=string
      CALL OPEN_TERM (IUTERM)
      CALL OPEN_INS  (IUINS, SUGGESTED_FILENAME)
 

      CALL REWIND_INS (IUINS, &statement_number)

The purpose of IUTERM is to keep a stream-file unit open to the terminal window while the standard output is redirected to a file.  Associated with IUTERM are the  tty-device file name. It must be defined in the environment variable tty. Also, the terminal type (xterm, hpterm, dtterm ...) must be defined through environment variable term (although at present there is no application that adapts to different terminal types).

Open_Ins will return the value associated with IUTERM through variable IUINS , if the user has entered TER: at the prompter.
Open_Ins will return the value 5 through variable IUINS , if the user has entered TER: at the prompter and the term and tty environment variables are undefined. This is a method to continue reading from the input stream. In shell scripts, for instance,

#!/bin/csh
unsetenv term tty

...

main << END
TER:
instructions      (possibly merged with other input that
               is eventually expected on stdin. Careful!)
...
END

will not bother the user at run-time.

A rewind on IUINS will be possible unless the user has entered TER: at the prompter. In order to assist with the proper location of a labelled section the REWIND_INS (IUN,*sml) utility can be called (included in ~hgs/util/p/openins.f). The alternate exit is used if the file cannot be rewound.

Back to top

Synopsis of responses.

$ program word1 word2

example
$ olfg '!rray/' '>NORMAL>'

You can enter the response to the prompter alternatively on the program call line. In that case the prompter must be satisfied with a Dollor character.  Note that the shell may interfer with your intentions. Most importantly, the > character on the call line must be quoted, otherwise the shell takes it as an output redirection operator.

Response can be one or two words.
Word 1 concerns the file name and location.
Word 2 concerns a labelled section inside the file;
it is signified with a leading '>', which will be stripped off before the label is processed.

Word 1 - a default value is shown as part of the prompt message:   default.ins

!word1 - avoid the prompting

[none]             - defaults to   default.ins
filename.extension - expands to  ./filename.extension
filename           - expands to  ./filename.ins
path/              - expands to  path/default.ins
path/filename      - expands to  path/filename.ins
path/filename.ext  - no further expansion
TER:               - the instructions will be read from stdin. Synonyms are TRM: and CON:

Word 2 - optional. If present, must be signified with a  >  chacter, no blank after.
>LABEL>

Back to top

.bye