Data flow in ADDE

When a user enters an ADDE request, the McIDAS-X software performs the steps below to determine the source of the data.

1. The application extracts the group name from the request.
2. The group name is compared to the entries in the client routing table to determine if the requested group is defined in the user's account or on a remote server.
3. If the requested group exists locally, a server is started under that user's account. The server tries to resolve the dataset name. If the dataset name is resolved, the server mapping table provides the server with information about the type of data being served and where it can find the data. When the data is found, it is sent back to the application for processing.
4. If the requested group exists on a remote workstation, a connection is made between the client and the remote workstation and a server is started on that workstation. The remote server tries to resolve the dataset name stored in the server mapping table. The server mapping table provides information to the server about the type of data being served and where it can find the data. When the data is found, it is sent back to the application for processing.
5. When all the data is returned, the connection between the client and server is dropped.Once the client routing table and server mapping tables are configured, the application won't know or care if the data arrives remotely or locally.

File redirection

File redirection lets a user identify the location of individual files on the system. The default configuration of a McIDAS-X session is to search for local files in the following directories.

• $HOME/mcidas/data
• ~mcidas/data

Local files may exist anywhere on the workstation, as long as an application knows where to look for them.

Entries in the file redirection table are made with the McIDAS-X REDIRECT command. For example, a user who has a McIDAS-X application that requires the file MYFILE in the directory /home/fred/data, would enter this REDIRECT command:

REDIRECT ADD MYFILE "/home/fred/data

All subsequent commands that access MYFILE would assume it is in /home/fred/data.

MCPATH

McIDAS-X also contains the environment variable, MCPATH , which defines directories for McIDAS-X commands to search when looking for data and help files. Commands requiring these types of files search each directory in the order listed in MCPATH .

If a user lets McIDAS-X set MCPATH , it will contain the directories shown below. Other directories can be added to MCPATH using the colon (:) character to separate the directory names.

$HOME/mcidas/data:$HOME/mcidas/help:~mcidas/data:~mcidas/help

If a file exists in more that one directory in MCPATH , McIDAS-X will use the first one that it finds. If you write data to a new file, MCPATH will place that file in the first writable directory in the MCPATH list.

McIDAS-X Text and Command Window

The McIDAS-X Text and Command Window is used for:

• entering McIDAS-X commands
• displaying command output
• showing workstation status information

When a session is started, McIDAS-X can display output on 10 different text frames in this window. You can switch between these text frames using the numeric keypad on the keyboard. Figure 2-4 shows a sample McIDAS-X Text and Command Window.

Figure 2-4 . The McIDAS-X Text and Command Window displays text messages.

Users enter two kinds of McIDAS-X commands on this window:

• single-letter commands, which can be either system defined or user defined
• multiple-letter commands containing positional parameters, keywords and quoted text

Single-letter commands

Many system defined single-letter commands toggle the McIDAS-X session between different modes. Others run commands to provide information. These system defined commands are run by simultaneously pressing the Alt key and the letter key, or by typing the letter and pressing Enter from the Text and Command Window.

The table below lists the system defined single-letter commands currently provided in McIDAS-X.

User defined single-letter commands are run by simultaneously pressing the Ctrl key and the letter key. This causes the contents of the McIDAS-X string corresponding to this letter to be run.

Multiple-letter commands

Multiple-letter commands, which are the most common interface for manipulating a McIDAS-X session, have four components:

• command name
• command positional parameters
• keywords with positional parameters
• quoted text

A sample McIDAS-X command line is shown below.

Each command line component and value is separated by one or more blank spaces. An individual parameter requiring a space must be surrounded with single quotes (` ') so it is treated as one parameter.

Each part of the McIDAS-X command line is described below.

Command positional parameters

Command positional parameters provide input to a command and must be entered in the exact order specified. Use them in commands that have options which the user must always enter. One advantage of positional parameters is minimizing the number of keystrokes a user types. Be careful not to negate this advantage by using so many positional parameters that the user can't remember them all.

Keywords

Like command positional parameters, keywords are used for entering command input. Unlike command positional parameters, they are optional for most McIDAS-X commands and can be entered in any order as long as they follow command positional parameters and precede quoted text.

Keyword parameters are often used to clarify commands with many complicated options. Although keywords can occur in any order, their positional parameters must be entered in the order indicated. Since users don't always specify all keyword positional parameters in a command, be sure to assign them reasonable defaults.

In addition to the keywords that an application has built into it, McIDAS-X has six global keywords, which are common to all McIDAS-X commands:

• DEV= specifies the destination device of the text output generated by a command.
• FONT= specifies the font for drawing text on the McIDAS-X Image Window.
• TCOL= specifies the color for command text output in the text window.
• TWIN= specifies the destination text window to route the command output.
• VIRT= specifies a virtual graphics number to write graphical output.
• PAN.EL= specifies a frame's panel number.

You can retrieve the parameters for these global keywords in your applications, as long as you don't change their functionality.

Quoted text

Quoted text input is most often used when a single string entered by a user may require extra spaces. Each application can contain only one quote string and it must be the last part of the command the user enters. Using quote fields in McIDAS commands is relatively easy from the McIDAS Text and Command Window; running McIDAS commands with quote strings from Unix shell prompts is more difficult. For this reason, the preferred method for entering strings with spaces in them from the command line is to use a positional or keyword parameter and surround the string with single quotes.

Text output

Text output generated by commands occurs in three different forms.

• Standard text messages are sent to stdout (standard output) and are used to display normal text output, such as listings or user instructions.
• Error text messages are sent to stderr (standard error) and describe the failure of an application to perform a specific task. These messages are automatically prefixed with the program name followed by a colon. Error messages typically occur when a command is entered incorrectly or data requested is not available.
• Debug messages are sent to stderr (standard error) and contain details about the internal state of an application at runtime. Although debug messages aren't normally of interest to a user, they can identify why an application fails to perform a task. Debug messages are prefixed with the program name followed by an asterisk.

The default mode for text output is to display standard and error text messages on the Text and Command Window, and to suppress debug messages. Use the DEV global keyword to specify the destination device of the text output generated by a McIDAS command.

Online helps

Online helps list the syntax of each McIDAS-X command including the parameters, keywords and remarks. To access the online help, type HELP in the McIDAS-X Text and Command Window followed by the command that you want information for. To get the online help for the DSINFO command, for example, you would type: HELP DSINFO .

Alternatively, you can invoke the HELP command while entering a command from the keyboard by typing the command name, then pressing Alt ?. An abbreviated help is displayed on the current text frame.

McIDAS-X Image Window

The McIDAS-X Image Window displays frames containing McIDAS-X generated images and graphics, and can optionally be surrounded by the McIDAS-X GUI, as shown in Figure 2-5 below.

Figure 2-5. The McIDAS-X Image Window displays images and graphics.

The manner in which images and graphics are displayed on the Image Window is determined by several factors:

• the number of gray shades and graphical colors defined by the user
• the red, green and blue color values assigned by the user
• the number of frames in the window and their size
• the frame looping sequence
• the coordinate system used to define the location of data points in an image

These factors are described below.

Image and graphics levels

The McIDAS-X Image Window displays satellite and radar data in shades of gray. Alphanumeric data and scientific diagrams are displayed with colored graphical lines and symbols independent of the grayshaded data. Users define the number of gray shades and graphical colors in the .mcidasrc file. The default configuration is 128 gray shades and 16 graphics levels with a maximum of 254 total levels for the image and graphics levels.

Color enhancements

When McIDAS-X displays images and graphics on the Image Window, it stores each pixel value in a frame object. The user can map these pixel values to specific red, green and blue color values. The McIDAS-X EU and EB commands modify the color combinations for image data; the GU command modifies the colors of graphics levels.

Frame size

Via the .mcidasrc file, users can also define the number and size of frames in the McIDAS-X Image Window. The default is to start the session with four frames that are 480 lines (vertical) by 640 elements (horizontal).

Loop control

McIDAS-X can display an automatically repeating sequence of frames much like a movie loop. The McIDAS-X commands LS and LB define the sequence of frames. The DR command modifies the speed of the loop. The Alt A and Alt B commands step through the individual frames in the loop. Alt L starts and stops the loop.

Coordinate systems

McIDAS-X uses four different, yet interconnected coordinate systems to define the location of data points within an image:

• image coordinates
• file coordinates
• earth coordinates
• frame coordinates

These coordinate systems are used to reference image data on disk and depict it on the McIDAS-X Image Window. McIDAS-X graphics also use a world coordinate system, which is described in the section titled Advanced McIDAS-X graphics techniques in Chapter 4, McIDAS-X Utilities .

File coordinates

In McIDAS-X, images and image sectors are stored in files called areas . File coordinates are based on the physical size of the image sector. They are zero-based and represent the location of a data point in an area file referenced sequentially by lines and elements. In Figure 2-6, the first data point in the image sector has file coordinates (0,0). The bottom-right data point has file coordinates (number of lines minus 1, number of elements minus 1).

Figure 2-6. Image and file coordinates are shown for a full image and image sector..

Frame coordinates

The pixels on McIDAS-X frames are arranged by lines and elements. A frame contains a representation of an image sector displayed on the McIDAS-X Image Window. The image sector shown in Figure 2-7 is an enlarged view of the image sector shown in Figure 2-6. The mcimage program, which is discussed later, takes the image data in the frame and maps it to the McIDAS-X Image Window. The Window Manager then displays the McIDAS-X Image Window on the workstation monitor.

The pixel in the upper-left corner of the frame has the frame coordinates (1,1) which means (line 1, element 1). The total number of lines and elements on the frame is determined by the frame size. The lower-right corner of the default-sized frame is (480,640).

For information about converting coordinate systems from line/element to latitude/longitude and vice versa, see the Image data and McIDAS-X navigation sections in Chapter 5, Accessing Data .

Frames may be subdivided into rectangular regions called panels. Each panel on an image frame has its own relative coordinate system, which defines the upper-left corner as (1,1). For information about panel generation, and interaction, refer to the McIDAS User's Guide.

Figure 2-7. Earth and frame coordinates are shown for the image sector.

User Common

User Common (UC) contains information about the McIDAS-X session, such as the current image frame in view, the maximum number of image frames and the cursor position. UC has two parts:

• positive UC
• negative UC

Positive user common

Positive UC contains the current state of the McIDAS-X session. This information is available as long as the session that created positive UC is active. Values in positive UC may change. For example, if frames are looping or you're moving the cursor on the screen, the values in positive UC related to the current frame number or cursor position will change.

Negative user common

Negative UC is not part of the shared memory block created when the McIDAS-X session is started. It is created by mmap when a McIDAS-X command is started, and is initialized with the values in positive UC at the time the command is entered. The file descriptor key associated with negative UC is then placed in the environment variable MCENV_NEGUC.

Negative UC values are not changed by other activities in the McIDAS-X session, such as frame looping or cursor motion. When a command finishes running, its copy of negative UC is deleted if it was not inherited from a parent process.

Visibility and inheritance

As a McIDAS-X programmer, you need to understand the concepts of visibility and inheritance when accessing positive and negative UC.

• Visibility describes the portions of the McIDAS-X session that can access specific UC information.
• Inheritance refers to the origin of the UC that an application receives at initialization.

The User Common policy for visibility and inheritance when running a McIDAS-X command is described below.

Image frame objects

Image frame objects contain information describing the contents and appearance of a frame displayed on the McIDAS-X Image Window. McIDAS-X provides a variety of library functions and commands to manipulate the contents of frame objects. An individual frame object contains not only pixel values to display, but also tables for image color enhancements, graphics color enhancements and stretching tables.

Redirection tables

Redirection tables are stored on disk in the file $HOME/mcidas/data/LWPATH.NAM . When McIDAS-X is started, the contents of the current redirection table are loaded into shared memory. This is where the McIDAS-X disk file system retrieves its redirection information.

mcenv

The mcenv program performs the following procedures to start a McIDAS-X session:

• creates the shared memory segment that will contain positive UC, the frame objects and the redirection table
• assigns the shared memory key ID to the environment variable MCENV_POSUC
• creates a temporary directory in $HOME/.mctmp with the same name as the shared memory key
• starts a command, if one is specified; note that when the mcidas script starts mcenv, it specifies that mctext should be started

The temporary directory created by mcenv stores session-dependent files such as frame directories, string tables and frame enhancement tables.

mctext

The mctext program performs the tasks below, as shown in Figure 2-8:

• maintains the Text and Command Window for McIDAS-X
• allocates enough memory to contain the command line and alphanumeric text components needed for the session
• monitors keyboard entry and the placement of the alphanumeric output generated by the commands

Figure 2-8. The mctext program controls command line input from the keyboard and displays text output on the Text and Command Window, while mcimage controls the McIDAS-X Image Window for displaying images and graphics.

The command line arguments for mctext can alter the number of text lines in the window buffer and recall the number of previously run commands. mctext can also start several other commands once it initializes its window environment.

When the mcidas script starts a session, one of the command arguments passed to mctext is mcimage .

mcimage

As shown in Figure 2-8, the mcimage program does the following:

• translates the contents of the frame objects into display characteristics for the workstation windowing system
• combines the brightness values, color enhancement information and stretching tables into pixel values that are displayed on the McIDAS-X Image Window
• controls the display of the McIDAS-X cursor

Fortran programs

When you write a Fortran program for McIDAS-X, you can't write it as a Fortran MAIN program. Instead, you must place it in the McIDAS-X environment as a subroutine named MAIN0, which is linked with a command jacket called main .

The command jacket main initializes the run-time environment for the command, including:

• parsing the command line
• initializing User Common

The first executable line of any McIDAS-X application written in Fortran must be the statement subroutine main0. The code fragment below is a sample command to print the phrase Hello World to the McIDAS-X Text and Command Window.

subroutine main0 
call sdest ('Hello World',0)
call mccodeset (0)
return
end

C programs

When writing a C program for McIDAS-X, the main is provided directly in the C code. The first thing you will do when writing a McIDAS-X application in C is to initialize the McIDAS-X environment with a call to the function Mcinit . This function performs the same command environment initialization performed by the Fortran command jacket main . To write McIDAS-X applications in C, your source code should also contain a reference to the McIDAS-X include file mcidas.h .

The code fragment below demonstrates how the same McIDAS-X command to print Hello World is written as a C application.

#include <stdio.h>
#include "mcidas.h"

int main (int argc, char **argv)
{

  /* initialize the McIDAS environment */

  if (Mcinit
 (argc, argv) < 0)
  {
    fprintf  (stderr, "%s\n", Mciniterr ());
    return (1);
  }

  Mcprintf ("Hello World\n");

  Mccodeset (0);
  return (Mccodeget());
}

Include files

McIDAS-X uses include files to hold definitions of constants specific to its software. mcidas.h contains system-wide constants and function prototypes. Equivalanet constants for Fortran applications are found in the *.inc files.

C ? NAME -- Describe the purpose of this command
C ?    NAME FUNCT1 parm1 parm2 <keywords> "quote
C ?    NAME FUNCT2 parm1 <keywords>
C ? Parameters:
C ?    FUNCT1   | describe the purpose of this function option
C ?    FUNCT2   | describe the purpose of this function option
C ?    parm1    | describe this parameter (def=default value)
C ?    parm2    | describe this parameter (def=default value)
C ?    "quote   | describe the contents of the quote string
C ? Keywords:
C ?    KEYNAME= | describe values (def=default values)
C ?    KEY2=YES | describe effect (def=default value)
C ? Remarks:
C ?    Add remarks, from most to least important. Use complete
C ? sentences. Separate multiple remarks with a single blank line, 
C ? as below.
C ?
C ?    Always end the help section with a line of 10 dashes,
C ? as below.
C ? ----------

/*
*?  NAME -- Describe the purpose of this command
*?     NAME FUNCT1 parm1 parm2 <keywords> "quote
*?     NAME FUNCT2 parm1 <keywords>
*?  Parameters:
*?     FUNCT1   | describe the purpose of this function option
*?     FUNCT2   | describe the purpose of this function option
*?     parm1    | describe this parameter (def=default value)
*?     parm2    | describe this parameter (def=default value)
*?     "quote   | describe the contents of the quote string
*?  Keywords:
*?     KEYNAME= | describe values (def=default values)
*?     KEY2=YES | describe effect (def=default value)
*?  Remarks:
*?     Add remarks, from most to least important. Use complete
*?  sentences. Separate multiple remarks with a single blank line, 
*?  as below.
*? 
*?     Always end the help section with a line of 10 dashes,
*?  as below.
*?  ----------
*/

The McIDAS-X library

In the Hello World examples above, several function names are in bold type. These are examples of functions included in the McIDAS-X library. The library contains all the object code for the functions and subroutines that make up the McIDAS-X Application Program Interface (API).

The name of the McIDAS-X library is libmcidas.a .

Name:
    mchmstostr - Converts a time to a character string

Interface:
    integer function
    mchmstostr (integer hms, integer format, character*(*) string)

Input:
    hms - Time in the form hhmmss.
    format  - Output format desired for the string.

Input and Output:
    none

Output:
    string  - Destination character string.

Return values:
     0  - Success.
    -1  - Invalid value for hms.
    -2  - Invalid value for format.
    -4  - Destination string is not big enough.

Remarks:
    If the input value for hms is 23444 then:
        form    string
        1   02:34:44Z
        2   02:34:44
        3   02:34:44UTC
        4   02:34:44 Z
        5   02:34:44 UTC
        6   2:34:44

Categories:
    converter
    day/time

C   THIS IS SSEC PROPRIETARY SOFTWARE - ITS USE IS RESTRICTED.

C *** McIDAS Revision History ***
C *** McIDAS Revision History ***

*$ Name:
*$      mcname - short description of purpose/use/etc
*$
*$ Interface:
*$      subroutine
*$      integer function
*$      double precision function
*$      mcname(integer param1, character*(*) param2, integer param3(64))
*$
*$ Input:
*$      none
*$      param1  - description of it
*$
*$ Input and Output:
*$      none
*$      param2  - description of it
*$
*$ Output:
*$      none
*$      param3  - description of it
*$
*$ Return values:
*$       0      - success
*$
*$ Remarks:
*$      Important use info, algorithm, etc.
*$
*$ Categories: 
*$      grid 
*$      image 
*$      point 
*$      text 
*$      system 
*$      event 
*$      file 
*$      sys_config 
*$      display 
*$      graphic 
*$      utility 
*$      converter 
*$      day/time 
*$      calibration 
*$      navigation  
*$      ingest/decode 
*$      met/science 
*$      user_interface

        INTEGER FUNCTION MCNAME (...)
        IMPLICIT NONE
C --- symbolic constants & shared data
      (...)
C --- external functions
      (...)
C --- local variables
      (...)
C --- initialized variables
      (...)

/* THIS IS SSEC PROPRIETARY SOFTWARE - ITS USE IS RESTRICTED. */

/**** McIDAS Revision History *** */
/**** McIDAS Revision History *** */

#include "mcidas.h"

/*
*$ Name:
*$      Mcname - short description of purpose/use/etc
*$
*$ Interface:
*$      #include "mcidas.h"
*$
*$      int
*$      Mcname(int param1, char *param2, int *param3)
*$
*$ Input:
*$      none
*$      param1  - description of it
*$
*$ Input and Output:
*$      none
*$      param2  - description of it
*$
*$ Output:
*$      none
*$      param3  - description of it
*$
*$ Return values:
*$       0      - success
*$
*$ Remarks:
*$      Important use info, algorithm, etc.
*$
*$ Categories: 
*$      grid 
*$      image 
*$      point 
*$      text 
*$      system 
*$      event 
*$      file 
*$      sys_config 
*$      display 
*$      graphic 
*$      utility 
*$      converter 
*$      day/time 
*$      calibration 
*$      navigation  
*$      ingest/decode 
*$      met/science 
*$      user_interface
*/

int
Mcname(...)

C and Fortran function interfaces

McIDAS-X applications and functions can be written in either Fortran or C. Because McIDAS has its roots in Fortran, not all functions in the McIDAS-X library have both C and Fortran calling interfaces.

While McIDAS-X attempts to accommodate both languages, C language programs will sometimes need to interface with Fortran-coded functions from the McIDAS-X library. When calling Fortran functions from C applications, you must keep in mind these four important differences between the languages.

• In Fortran, parameters are passed into functions by address; in C, they are passed by value.
• In Fortran, character strings are preallocated, blank-padded memory segments. The length of each string is passed into functions as additional hidden arguments. In C, strings are null-terminated memory segments that may be preallocated or dynamically allocated. Because the string is null-terminated, it is not necessary to explicitly pass the string length into the function.
• In Fortran, multi-dimensional arrays are stored in memory in column-major format. In C, they are stored in memory in row-major format.
• In Fortran, functions added to the library are given an underscore character `_' as a suffix. No suffix is appended to C functions when placed in the library.

Below are examples of how these language differences affect a C application calling a Fortran function. Also provided is an example of writing Fortran-callable routines in C and information about writing Dynamic Link Library modules.

integer     tvlin, tvele
integer onscreen
real    lat, lon

tvlin   = 100
tvele   = 200

onscreen    = iyxll(tvlin, tvele, lat, lon)

#include "mcidas.h"

Fint iyxll_ (Fint *, Fint *, Freal *, Freal *); /* function prototype */

Fint    tvlin, tvele;
Freal   lat, lon;
Fint    onscreen;

tvlin   = 100;
tvele   = 200;

onscreen= iyxll_ (& tvlin, & tvele, & lat, & lon);

onscreen    = iyxll_ (tvlin, tvele, lat, lon);

integer mdfile, day
character*4 schema

schema  = 'ISFC'
day = 96017

mdfile = mdsvc(schema, day)

#include "mcidas.h"

Fint mdsvc_ (char *, Fint *, FsLen); /* function prototype */

Fint    mdfile, day;
FsLen   schema_length;
char    *schema;

day           = 96017
schema        = strdup ("ISFC");
schema_length = (FsLen) strlen (schema);

mdfile = mdsvc_ (schema, &day, schema_length);

integer array(2,3)

1,1  2,1  1,2  2,2  1,3  2,3

int array[2][3]

1,1  1,2  1,3  2,1  2,2  2,3

int convert (int, char *, char *, float *);   /* function prototype */

int convert (int input, char *input_units, 
             char *output_units, float *output)
{
  :
  :
}

Fint convert_ (Fint * input,
               char  * input_units,
               char  * output_units,
               Freal * output, 
               FsLen input_len ,
               FsLen output_len)
{
  char    *c_input_units;        /* C string representation
                                  * of input units */
  char    *c_output_units;       /* C string representation
                                  * of output units */
  int      rc;                   /* convert() function return value */

  /* convert the Fortran character strings into C strings */

  c_input_units  = fsalloc (input_units, input_len);
  c_output_units = fsalloc (output_units, output_len);

  /* call the C callable version of convert */

  rc = convert ((int) * input, c_input_units, c_output_units, 
                (float *) output);

  /* free up the memory for the C strings */

  free (c_input_units);
  free (c_output_units);

  /* return from the function */

  return ((Fint) rc);
}

Debugging McIDAS-X applications

It's a fact of life that programs do not always behave as expected. Therefore, you should implement some type of debugging strategy to isolate and repair errors. This section describes the tools available to help you debug applications. McIDAS-X provides two facilities to aid your search for the elusive bug. Additionally, Unix systems provide a variety of symbolic debugging tools, the most common of which is dbx or gdb.