% @(#)host+m.alq	19.1 (ESO-IPG) 02/25/03 14:03:24 

Contents:
(1)    MIDAS <-> Host system
(2)    Host commands with Midas names
(3)    Output Redirection in Midas
(4)    Input Redirection in Midas
(5)    Pipes in Midas
(6)    Executing Midas commands from Host command line
(7)    Accessing Midas images from outside




(1) MIDAS <-> Host system
    ---------------------

MIDAS and the Host Operating System (DCL for VMS and Bourne shell for Unix) 
co-exist smoothly and complement each other.
Migration from one environment to the other is simple:
 
If you are in the Midas environment, type BYE to exit and return to the Host 
System.
If you have returned to the host environment from a MIDAS session,
type `gomidas' to continue your Midas session at the point you quit before.
The status of the keywords and the command history buffer of the stopped Midas 
session are preserved - if you want to start afresh, use `inmidas' again. 

You can also use and communicate with host commands inside MIDAS
by preceding them with `$'. For instance,
Midas 027> $DIR       (in VMS)         
or 
Midas 027> $ls        (in Unix) 
will display the contents of the current directory.

Please, note, that this mode of operation will only invoke Bourne shell 
commands in Unix, not C-shell or Kornshell commands.
To execute C-shell (or any other Shell) commands you have to insert them
in a Bourne shell script which has as the first line:  
#!~/bin/csh, or: #!~/bin/ksh, etc.

The adavantage of using Host commands directly in Midas is that you can
use the Midas substitution mechanism, e.g. if keyword IN_A contains the
string `myfile' then
Midas > $ more {in_a} 
will show the contents of file `myfile'.
Furthermore all the editing facilities of Midas also apply then to the Host
commands.

However, there's a caveat:

In VMS the version number of files may be specified using a semicolon, e.g.  
$ RENAME file.typ;7 lola.bdf. 
Typing such a command inside MIDAS will not work, since the monitor will 
interpret this input as two Midas commands.
Instead, use a dot to separate the version number, e.g. 
Midas > $ RENAME file.typ.7 lola.bdf.

In Unix the repetition of tokens may cause trouble. Consider the following: 
Midas 123> load/ima vaca  
Midas 124> $cp /elsewhere/toro.bdf .   
The intention was to simply copy the file `toro.bdf' from somewhere else to
the current directory. But instead of `toro.bdf' you will find a
strange file named ? in your directory... 
In the line `123' only two tokens are entered, so all other 8 tokens are
set to the default value `?'. In line `124' the third token will be set
to the third token in the line above, so it changes to:
Midas 124> $cp /elsewhere/toro.bdf ?   
Instead, specify also the result frame completely, e.g. 
Midas > $cp /elsewhere/toro.bdf toro.bdf

Preceding a host command by $$ will avoid the interpretation of specific
symbols by MIDAS, thus 
Midas 124> $$cp /elsewhere/toro.bdf .   
will actually do the expected copy.

If you don't want to have to type the `$' each time you want to use a Host
command, you can change your Midas environment via
Midas > set/midas environment=midhost

The prompt in Midas will change from e.g. Midas 123> to Midas 123: and
all commands not recognized by Midas will be passed automatically to the
underlying Host system, e.g. Unix.
Thus,
Midas 124> set/midas environment=midhost
Midas 125: ls

will be o.k. But 
Midas 126: echo $DISPLAY
will not do what you expect because there's a Midas command ECHO ...

Here's a set of Midas commands (to be put in $HOME/midwork/login.prg) to set 
up smooth integration into e.g. Unix for all your Midas sessions:

create/comm cd change/direc
create/com zedit $vi		!there is VIEW/IMAGE
create/com zecho $echo		!there is ECHO/ON
set/midas env=midhost           !first Midas, then try in Host mode


Note also, that we have to point `cd' to the Midas command `change/directory' 
and cannot use the Unix `cd' directly.
For, Midas executes its applications (which includes Host commands) in a child 
process (subshell) which leaves no traces after termination, so you cannot 
simply use the host command "cd" to change the working directory once you are 
in a Midas session.

If you want to move completely to the Host environment, change your Midas 
environment via
Midas > set/midas environment=host

The prompt in Midas will change from e.g. Midas 123> to Midas 123$ and
all commands will be passed to the underlying Host system, e.g. Unix. However,
the commands are still executed in a child process (subshell), so you still
would end up in the same directory if you do
Midas 127$ cd ..
Midas 128$ pwd  

The command 
Midas 129$ set/midas
brings you back to the Midas environment.

The return status from a Host system command is saved in keyword AUX_MODE(17)
and can be tested later on in Midas, e.g. in Unix

Midas 124> $ls non_existing_file
non_existing_file: No such file or directory
Midas 125> write/out {aux_mode(17)}
0004

Alternatively, the function M$SYSTEM(op1) of the COMPUTE/KEYWORD command
executes the command contained in `op1' in the host system and returns the
host return status (see the help of COMPUTE/KEYW for details).



(2) Host commands with Midas names
    ------------------------------

The Midas keyword AUX_MODE(1) holds the flag indicating in which Host system
Midas is currently running.
AUX_MODE(1) = 1 -> Portable MIDAS under VMS (OpenVMS)
            = 2 -> Portable MIDAS under UNIX.
To find out which specific Unix system is in use, look iat the keyword MID$SYS.

Thus, you can check in a Midas procedure which Host system is running and
depending on that use the correct Host command for a given task.
 
For some frequently used Host commands there exist also Midas names common to
both Unix and VMS, so you don't have to check AUX_MODE(2).
All these commands begin with a `-' and are:
-dir		list contents of a directory
-copy		copy files
-@		execute a DCL (VMS) or Bourne shell (Unix) script
-delcnf		delete a file with confirmation
-delete		delete a file without asking for confirmation (i.e. always)
-rename		rename a file
-type		display complete contents of file in one go
-more		display contents of file page by page
-purge		purge a file (only for VMS)

Like all Midas commands these commands are case insensitive.

The arguments for these commands must follow the syntax of the underlying
Host system. E.g. on a VAX/VMS system
Midas 234> -delete kb*.*.*
is the correct command, whereas on a Unix system
Midas 234> -delete kb*
would be correct.



(3) Output Redirection in Midas
    ---------------------------

Different ways exist to save the output of a MIDAS command in an ASCII file
besides just using the logfile.
There is a set of PRINT/... commands to print out the contents of the
different MIDAS data objects, e.g. PRINT/TABLE. By default the output
from these commands is sent to a printer but this can be changed to a file
via the ASSIGN/PRINT command.
So, if you want an ASCII copy of a MIDAS table, you do:
Midas 088> ASSIGN/PRINT file mytable.dat
Midas 089> PRINT/TABLE mytable

Another possibility which is applicable to all MIDAS commands, not just the
PRINT commands, is to specify the output file directly in the command.
Thus, 
Midas 089> WRITE/TABLE mytable >mytable.dat
is equivalent to the two commands above. 
The file `mytable.dat' is created in the current directory. 

If you want to append the data to an existing file, use
Midas 089> WRITE/TABLE mytable >>mytable.dat

In case, the output should go to a file and also be displayed in the
MIDAS command window, use
Midas 089> WRITE/TABLE mytable >mytable.dat+terminal

Midas 090> WRITE/TABLE mytable >terminal
only produces output on the terminal, i.e. it's the same as 
Midas 091> WRITE/TABLE mytable 
This is e.g. useful if you want to provide optional file output in a procedure.
For if you have, say, a char. keyword `mykey' containing ">outfile" or " "
depending upon if you want output to a file or not,
WRITE/TABLE mytab {mykey}
will NOT work, because the check for the output redirection is done at the
very first parsing of the command line before symbols are replaced...
Instead, `mykey' containing "outfile" or "terminal" and
WRITE/TABLE mytab >{mykey}
will do the intended switching of output to a file or terminal.

If you use the special filename `Null' as output file, no file `Null' is 
created just the output is suppressed. E.g.

Midas 092> statistics/image lola >Null
will produce no output and just fill all relevant keywords.

This output redirection scheme has been modeled after the way it is
done in Unix but it also works on VMS systems.
But, please, note that there shout be NO space between the `>' and the 
filename, e.g.: 
WRITE/TABLE mytable > mytable.dat                      will not work!
 


(4) Input Redirection in Midas
    ---------------------------

Similar to Unix it is also possible to specify an input file for a Midas
command directly on the command line.
E.g. the two commands: 
Midas 089> $ls a*.bdf >mydata.dat
Midas 089> READ/DESCR  <mydata.dat
will display the standard descriptors of all images in the current directory
beginning with the character `a'.

Midas 091> WRITE/KEYWORD inputc <mydata.dat
will fill the keyword `inputc' from the contents of a single line ASCII file
`mydata.dat' (or the contents of the last line of a multi-line file, each line 
overwrites the previous one, for WRITE/KEYWORD expects only a single line as
input...).

Again, please, note that there shout be NO space between the `<' and the 
filename, e.g.: 
WRITE/KEYWORD inputc < mydata.dat                      will not work!



(5) Pipes in Midas
    --------------

If you work on a Unix system, you can also pipe the output of Midas/Host 
commands directly into Host/Midas commands by using the pipe symbol `\|'.

Midas 123> read/descr lola \| $grep CUNIT
will just display the contents of the descriptor CUNIT of image `lola.bdf'.

Midas 124> $pwd \| write/keyw inputc
will store the current directory in char. keyword `inputc'.

Please, note, that if you use pipes between different Unix commands you
should NOT precede all Unix commands with a `$' only the first one, because 
the whole string (until a pipe followed by a Midas command) is passed to a
subshell for execution. E.g.:
Midas 125> $ls \| $grep it

will not work, instead do:

Midas 125> $ls \| grep it

So, the `$' is only needed in front of the first Host command, i.e. at the
beginning of the line or after a Midas command and a pipe.



(6) Executing Midas commands from Host command line
    -----------------------------------------------

To execute a Midas command directly from the Host command line (currently
only implemented for Unix), use the command `drs' which is installed
during the Midas installation.

after (in e.g. Solaris)
$ alias drs "sh /midas/`Midas_version'/system/unix/drs.sh"
the following commands are possible:

$ drs any_Midas_command			# execute a Midas command from Unix
$ drs -h				# get help about the drs command


Please, note, that no display- or graphics- related commands can be executed
directly from Unix.



(7) Accessing Midas images from outside
    -----------------------------------

The standard format for images in Midas is the BDF (Bulk Data Frame) format.
Generally, you should always use the Midas standard interfaces to access
the images. This ensures a clean interface and robustness of code if the
internal data format changes (which it does at times...).
However, there are occasions when you need to access Midas images from
other applications without having to use the Midas interfaces.
For these cases we give here a short overview of the internal format of Midas 
images with the following caveat:

WE RESERVE THE RIGHT TO CHANGE THE INTERNAL FORMAT AT ANY TIME!

That means, that from one Midas version to the next your code may not work
anymore and you have to adapt your software.

Midas images consist of 512 bytes blocks.
The first block is the file control block (FCB) containing all the information
needed if you just want to manipulate the data.
It follows a number of blocks used for the storage of the Midas descriptors,
the descriptor directory being the first such descriptor.
After that we have the no. of blocks needed for the image data. Note, that this 
has a fixed size, depending on the no. and format of the image pixels as
determined at image creation. 
That means, you cannot extend a Midas image in size.
After the fixed no. of data blocks there may be any no. of blocks used again
for descriptor storage. That means you can add descriptors any time after
image creation.

The FCB holds in fixed positions an integer array (5 elements) with the 
following information:

datinfo[0] = no. of axes of image
datinfo[1] = no. of pixels in 1. axis
datinfo[2] = no. of pixels in 2. axis
datinfo[3] = no. of pixels in 3. axis    so only useful if dim < 4 !!
datinfo[4] = format of pixels:
        D_I1_FORMAT     1     byte
        D_I2_FORMAT     2     short integer
        D_UI2_FORMAT  102     unsigned short integer
        D_I4_FORMAT     4     integer
        D_R4_FORMAT    10     real
        D_R8_FORMAT    18     double
datinfo[5] = byte no. of first pixel of image (counting begins at 0, like in C)

In the directory $MIDASHOME/$MIDVERS/prim/general/src you find a file
`readima.c' which accesses this information which you should use as a 
template. This module is not automatically compiled and linked in the Midas
installation. To execute it, do:

$ cp $MIDASHOME/$MIDVERS/prim/general/src/readima.c .
$ cc readima.c
$ a.out myimage.bdf

Reading the code of `readima.c' should give you all the information needed
to access the data (pixels) of a Midas image.

Due to the fact, that Midas descriptors may be extended during the lifetime
of an image, descriptors are stored in a much more complex way and accessing 
them from code outside Midas is a very bad idea, and we don't explain that 
here.
