% @(#)host+m.alq 17.1.1.1 (ESO-IPG) 01/25/02 17:43:39 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 WRITE/KEYWORD inputc 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.