mcidas.h

The include file mcidas.h contains all the function prototypes for C-callable API routines in the McIDAS-X library. It also contains two constant values that are commonly used in McIDAS-X applications.

mcidas.h also includes a group of defined types that you should use to ensure platform independence of data types. Use the defined types below when writing interface routines that will be used between C and Fortran.

To ensure portability of Fortran jackets written in C, the preferred types to use are Fdouble, Fint and Freal, as the INTEGER*2, INTEGER*4, REAL*4 and REAL*8 declarations are not part of the Fortran-77 standard.

Error handling

In both Hello World examples above, calls were made to the functions mccodeset and Mccodeset. These functions set a status code that can be passed from the application to the calling environment. Currently, the acceptable return codes for McIDAS-X commands are as follows:

This information may be very useful to the calling environment, especially when using McIDAS-X commands in scripts designed for batch processing. For example, if you have a script that copies satellite images from several different sources and then creates a mosaic of the images, you may not want the script to generate the mosaic until all of the images are available. The processing script will not be able to verify that all of the data is available until all of the commands necessary to acquire the satellite data have returned a status of 0 indicating success.

If a command returns a status of 1, it typically means the user entered the command incorrectly and it will never run properly. A status of 2 is typically returned when data requested by a user is not yet available.

Setting return statuses for McIDAS-X applications became mandatory, beginning with McIDAS-X version 7.0 released in May 1996. Most McIDAS-X applications written before that upgrade do not yet contain the Mccodeset /mccodeset features.

Online command helps

The McIDAS-X command provides users with a quick way to get a listing of a command's structure and available options. The original text for these helps is stored in the source file for each command. You will use one of two template formats when creating online helps. The format for Fortran commands is shown below.

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 ? ----------

The similar help template for commands written in C is shown below.

/*
*?  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 first line of each help contains the command name followed by two dashes (--). These dashes are used as flags to the system for the Alt ? help option described earlier in this chapter.

API naming conventions

To provide easy recognition of McIDAS-X functions, the names of all new McIDAS-X functions begin with one of the prefixes below.

The McIDAS-X philosophy regarding function prefixes is that once a function is released with an Mc or mc prefix, it is a stable member of the McIDAS-X library and will have neither its functionality nor calling sequence changed. The M0 or m0 prefix is assigned to:

• Functions that will eventually become Mc/mc prefixed, or
• Functions that are never intended to be called by applications

SSEC uses the M0/m0 prefix while testing a routine's functionality and calling sequence. When the function is deemed stable, the prefix is changed to Mc/mc.

SSEC adopted this function prefix naming convention in the spring of 1995. Most of the routines currently found in the McIDAS-X library predate this naming convention. As SSEC modifies existing software, it will make every effort to change the names of older functions where practical.

If new functions are written to replace older, non-prefixed functions, SSEC's policy for removing the old functions from McIDAS-X is as follows:

• All references to the old function will be removed from all applications in the McIDAS-X packages.
• The old function will be moved to a compatibility library.

Interface documentation block

SSEC has also developed a standard interface documentation block template that you should use for all new McIDAS-X library functions. This format is used to generate the online API function documentation distributed with the McIDAS-X software.

The table below lists and defines each field in the documentation block. More information follows along with examples from the mchmstostr function. If a function doesn't require a description for every field, you should still include all fields in the documentation block and fill the unused fields with the word none.

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

Fortran template

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
      (...)

C template

/* 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(...)

Passing parameters into functions

The McIDAS-X Fortran function iyxll converts integer values from frame (tv) line and elements to single precision floating point values for latitude and longitude. The sample Fortran code fragment below calls this function.

integer     tvlin, tvele
integer onscreen
real    lat, lon

tvlin   = 100
tvele   = 200

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

To call the same function from a C application, your code would be similar to this:

#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);

The special type declarations Fint and Freal are Fortran integer and real declarations defined in the include file mcidas.h. They are designed to provide platform-independent interfaces between Fortran and C applications.

Since parameters are passed into functions in C by value, you must reference the variables in the calling sequence with the ampersand (&) symbol. Calling iyxll by value, as shown below, would most likely result in a segmentation violation error.

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

Passing character strings into functions

The McIDAS-X library function mdsvc, which is coded in Fortran, returns the appropriate real-time MD file given a character string schema type and an integer value representing a Julian day. Below is a sample Fortran code fragment to call this function.

integer mdfile, day
character*4 schema

schema  = 'ISFC'
day = 96017

mdfile = mdsvc(schema, day)

To call the same function from a C application, your code would be similar to this:

#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);

Note that the variable schema is passed in with no ampersand character. The function expects the variable to be passed in by address and since schema is already a pointer, no ampersand is required.

Also note that the call to mdsvc_ in C has an additional parameter, schema_length. This argument is passed by value to the Fortran function so the length of the string containing the schema type is known to mdsvc internally.

Storing arrays

The conflict of Fortran column-major arrays and C row-major arrays is difficult to resolve. Arrays are contiguous memory segments, no matter how many dimensions they have. The difference between the languages is in how the individual elements of the arrays are arranged and accessed, as described below.

If you declare a Fortran array like this:

integer array(2,3)

Then to reference the memory segments in increasing order, you will reference them like this:

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

If you declare a C array with the same dimensions:

int array[2][3]

Then to reference the memory segments in increasing order, you will reference them as shown below. They are shown as one-based values for comparison to the Fortran array even though the C language is actually zero-based.

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

When accessing data stored in multi-dimensional arrays, it is difficult to recognize if an array is stored in Fortran or C. Since most McIDAS-X applications were historically written in Fortran, multi-dimensional data is usually stored in column-major format. To address values for column-major data in C, dimension your arrays as one-dimensional and use the conversion equations below to index to the appropriate location.

The indexing equation for a column-major (Fortran) array is as follows, assuming 1-based indexing:

The indexing equation for a row-major (C) array is as follows, assuming 0-based indexing:

Writing Fortran-callable routines in C

Now that you understand how the C and Fortran languages treat different elements of parameter passing into functions, you need to know how to write Fortran-callable functions in the C language. The example below builds the calling sequence for a unit conversion routine that takes an integer value and unit types and returns a floating point number. The function also returns an integer type for a status code.

In C, the prototype and function would look like this:

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

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

The entire source code for the Fortran-callable version of this function would appear as follows. The important concepts are bolded.

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);
}

Note that the Fortran-callable function declaration explicitly includes the underscore character (_). The McIDAS-X library function fsalloc converts Fortran strings to C strings. The function strtofs converts C strings to Fortran if you need to pass character string output back to the Fortran program that called this function jacket. Be sure to call the C function with the appropriate data types.

Writing shell scripts with McIDAS-X commands

A shell script is a program containing a set of executable commands. Shell scripts are useful for running a series of individual McIDAS-X commands outside of McIDAS-X. Generally, you must invoke the McIDAS-X resident program, mcenv, before running a series of McIDAS-X commands.

Print statements

In McIDAS-X, the simplest debugging aide is ddest/Mcdprintf. These functions allow applications to print hidden statements when the third character in the DEV= global keyword is C. Strategically placing debug print statements in your code is an excellent way to identify invalid values or corrupted data in disk files. Use debug messages prudently, however, and avoid putting them inside large loops that may generate thousands of lines of useless messages.

M0ASSERT

Another debug facility provided in McIDAS-X is the C language development tool, M0ASSERT, which is used to trap severe errors in code, such as a memory overlap problem or trying to pass a NULL character pointer into a routine.

M0ASSERT is a macro that takes a boolean expression as input. If the expression resolves to false, a message is printed to stderr similar to this:

Assertion failed: source_file line nnn

where source_file is the name of the file and nnn is the line number in source_file where the failure occurred. After the message is printed, a call to exit(1) is made to end the program.

M0ASSERT can take two different forms based on compile-time options that you specify. The compile-time default for M0ASSERT is the NULL statement, meaning M0ASSERT does nothing. If you add the option -DM0ASSERT_ON to the compile statement, the preprocessor adds the assertion test.

M0ASSERT is not a substitute for standard error handling. Don't assume that capturing assertion failures will be activated as part of the production version of the software. Also, don't use M0ASSERT to test for conditions that, while rare, could indeed happen. The sample code fragment below demonstrates both good and bad uses of M0ASSERT.

int foo (const char *string)

/* if the NULL pointer is passed into foo, you have a big problem.
   This is a good example of M0ASSERT */

M0ASSERT(string != (const char *) NULL);

/* below is a bad use of M0ASSERT because memory allocation 
 * failure is quite possible */

ptr = (char *) malloc (10);
M0ASSERT (ptr != (char *) NULL);

dbx

Most Unix-based systems include the symbolic debugger, dbx. To interactively debug McIDAS-X applications with dbx, you must perform a series of steps, which are necessary for these reasons:

• dbx gets the source file name to include in the debugging session from the executable created when the application is compiled. Because McIDAS-X file extensions are not the standard file extensions for the language, dbx will not recognize the original source file name.
• In general, McIDAS-X expects the data an application will use to be in the directory ~/mcidas/data.
• Because McIDAS-X commands are started with a fork/exec, dbx is unable to directly link to the main of the application.

Perform the steps below to set up your environment for interactive debugging. For this description, assume that the development source code is in ~/mcidas/dev, an application is in the source file foo.pgm, and it calls functions found in suba.c and subb.for.

1. Copy a version of your source files into the ~/mcidas/data directory with the standard file extensions for the language.

   Type:	cp ~/mcidas/dev/foo.pgm ~/mcidas/data/foo.f
   	cp ~/mcidas/dev/suba.c ~/mcidas/data/suba.c
   	cp ~/mcidas/dev/subb.for ~/mcidas/data/subb.f



2. Compile and link your functions and command with the -g option, which produces additional symbol table information necessary for the debugger. The resulting binary will be put in ~/mcidas/bin/foo.k.


3. Change to the ~/mcidas/data directory.

   Type:  cd ~/mcidas/data

4. Verify that your MCPATH environment variable is set up appropriately. At the minimum, MCPATH should contain the directories $HOME/mcidas/data and ~/mcidas/data.


5. Start an environment for McIDAS-X applications to run under.

   Type:  mcenv

6. Start the debugger.

   Type:  dbx ../bin/foo.k

7. From the dbx prompt, activate the source code.

   Type:  list main0

8. Input the McIDAS command parameters as you would running the command from a unix prompt.

Programming do's and don'ts

This section describes some of the common issues that McIDAS-X developers encounter. It will offer suggestions for avoiding platform dependency problems and for planning new software development.

[Search Manual] [Table of Contents] [Go to Previous] [Go to Next]