McIDAS Programmer's Manual

Chapter 1 - Introduction

This chapter provides an overview of McIDAS-X and explains the use and function of this manual. You'll learn about:

the current McIDAS suite
your responsibilities as a McIDAS-X programmer
this manual's organization, and its symbol, text and screen conventions
the McIDAS Help Desk
where to find more information about McIDAS-X

This chapter is organized into these sections:

Overview of McIDAS

McIDAS (Man computer Interactive Data Access System) is a general-purpose collection of tools for acquiring, analyzing and displaying meteorological data. SSEC's McIDAS is a distributed system consisting of Unix workstations that run the ADDE (Abstract Data Distribution Environment) software to receive and process data.

McIDAS is an environment in which data is received, processed, and stored, and then distributed among multiple workstations. For example, users may be working at a McIDAS-X workstation, yet the data they are using may reside on other workstations. When users request data from a data storage machine, the request is processed and the data is sent to the user. In the McIDAS distributed system, data can also be received and processed on the same machines that store and serve it.

The McIDAS suite includes the following packages:

user tools--McIDAS-X
satellite data ingest--SDI
conventional data collection--McIDAS-XCD

McIDAS-X

McIDAS-X can run as stand-alone packages using real-time data from one or more remote sites or from local sources. The ADDE (Abstract Data Distribution Environment) software is part of the core McIDAS-X package and provides a comprehensive set of application tools for managing, processing, intercomparing and merging data.

Users access and integrate various types of data by displaying images and graphics separately or combined. They can also animate current, past and forecast data displays to monitor evolving weather systems.

SDI

The SSEC Desktop Ingestor (SDI) is a hardware and software package that receives and processes satellite data on a PC workstation running a Unix operating system. Currently, SDI receives and processes data from POES, GVAR, Meteosat, DMSP and GMS satellites, and the NOAAPORT satellite broadcast.

SDI saves satellite data in a format that the McIDAS-X ADDE servers can access and subsect. Any McIDAS-X function can be applied to the data, for example: enhancements, looping, overlaying other data, brightness stretching, and remapping to other projections.

McIDAS-XCD

The McIDAS-X Conventional Data (XCD) software package on Unix-based workstations receives and processes data from the National Weather Service Telecommunications Gateway. The data includes conventional observations, model gridded forecasts, weather summaries, international data, and local data sources.

The data arrives via satellite broadcast. This transmitted data is converted to McIDAS-X formatted files. McIDAS-X users can employ a wide array of McIDAS-X applications to interpret, change, search, and display this data.

McIDAS-X programming philosophy

The McIDAS-X software package includes source code that allows users to tailor applications to fit their needs and to develop new applications. Normally, the SSEC staff undertakes development efforts that impact the basic system, such as file structure changes, new data sources, and new communications methods. New software capabilities developed at SSEC as a result of SSEC's or another McIDAS-X site's efforts, are made available to the entire user community.

This section dicusses the following topics:

Your responsibilities

McIDAS-X continually evolves, due to the needs of scientists, researchers, forecasters, and programmers. Most new applications programs and functions are built on existing programs and functions. As a McIDAS-X programmer, you must maintain system integrity by developing programs and functions that not only satisfy an immediate need, but also promote long-term software development for future programmers and users.

It is also your responsibility to create applications and utility functions that can be used on all McIDAS-supported platforms. This requires attention to language standards and avoiding hardware and operating system specific interfaces. It is also important that you program in abstract ways, eliminating references to specific hardware characteristics whenever possible.

Chapter 2, Learning the Basics contains the standards that SSEC programmers use when writing code.

Planning for McIDAS-X upgrades

System enhancements made by SSEC or external users are distributed to all McIDAS-X users via upgrades. Below are some helpful hints for maintaining your locally developed code after a McIDAS-X upgrade.

McIDAS-X upgrades contain all the code needed for an initial installation of McIDAS-X, as well as aperiodic updates for enhancements or fixes. Thus, you should keep all locally developed code in separate directories and libraries.
Beware of using McIDAS-X library functions beginning with m0 (Fortran) or M0 (C). These functions are considered private to the McIDAS-X core code. The use, capability, and life of these functions are not guaranteed.
Recompile and relink your local applications after each upgrade is installed. Otherwise, changes in McIDAS-X may result in your code not working. Each upgrade package contains a list of changes for that upgrade.
As new library functions replace existing ones, old functions will move to a compatibility library. Functions in this library are no longer referenced by McIDAS-X applications and are not tested for upgrades. If you still use these functions, you must treat them as locally developed code.

Using this manual

The McIDAS-X Programmer's Manual is designed to be an instructional guide for new McIDAS-X programmers and a reference for experienced McIDAS-X programmers. It assumes that you know the Fortran and C programming languages, and have a basic knowledge of McIDAS-X and your operating system.

This manual provides the information that you need to:

write McIDAS-X applications on Unix-based systems
understand the McIDAS-X data file formats
program at the API (Application Program Interface) level, using the detailed API descriptions from the information provided in the API man pages.

This section discusses the following topics:

How this manual is organized

The McIDAS-X Programmer's Manual is divided into seven chapters plus appendices, a glossary and an index. Use the table below as a general guide to help you find the information you need.

If you're interested in	Turn to
A brief history of McIDAS	Preface
Knowing what's in this manual and who it's written for, how to get help, and other McIDAS-X documentation that you can reference	Chapter 1, Introduction
The basics about developing applications programs in McIDAS-X, including the types of data available in McIDAS-X and the formats and conventions to use when writing online helps	Chapter 2, Learning the Basics
Setting up the McIDAS-X environment, and compiling, testing and debugging your McIDAS-X code	Chapter 3, Getting Started in McIDAS-X
A description of the McIDAS-X library functions that you'll use to write your applications programs	Chapter 4, McIDAS-X Utilities
Learning how to use McIDAS-X library functions to access data files	Chapter 5, Accessing Data
The file formats for the data files developed for applications running under McIDAS-X	Chapter 6, Format of the Data Files
Writing and maintaining locally developed servers for ADDE	Chapter 7, Writing ADDE Servers
SSEC's guidelines for writing online helps, and information about satellites and data parameters	Appendices
Definitions of some terms used in this manual	Glossary
The detailed descriptions for each API function that you need to build applications	Online man pages

Conventions used in this manual

Becoming familiar with the symbol, text and screen conventions in this manual will make the text easier for you to read and understand.

The conventions described below are:

Symbol conventions

1., 2., 3., ...	Numbered items indicate a task with two or more sequential steps.
	This symbol indicates a list of items that are not sequential.
	This symbol indicates a reference to other parts of this manual or to companion documentation for additional information.

Text conventions

The term function is used throughout this manual to describe C procedures and functions, and Fortran functions and subroutines. Function names are bolded; for example, Mccmd and mcgget .
File names, paths, environment variables and script names are in courier bold .
McIDAS-X commands are uppercase and unbolded.
Actual keyboard entries that you will type appear in bold. For example:
cd $HOME/mcidas/help

You will type keyboard entries exactly as they appear, leaving a space between each term or number in the command line. Always press Enter after typing a keyboard entry.

When you see an Alt entry, it means you will press two keys simultaneously. For example, Alt G means you should hold down the Alt key and press the G key.

Screen conventions

System prompts and responses, and code examples look like this:

c --- set up the ADDE transaction
      ...

100   continue
c --- read the data block
    status = mcalin(handle, data_buffer)
    if( status.lt.0 ) then
       call edest('Data Read failed',0)
       return

c --- got a line of data
      else if( status.eq.0 ) then

c --- read the line prefix
       status = mcapfx(handle, prefix_buffer)
       if( status.lt.0 ) then
          call edest('Prefix Read failed',0)
          goto 100
         endif

c --- process the data
         ...
         goto 100

      endif
      ...

Code samples longer than one page are not boxed.

An ellipsis ( ... ) in a code sample means one of the following:

lines of code were omitted to condense the sample
you will write lines of code to replace the ellipsis

Getting help

The McIDAS Users' Group (MUG) provides a McIDAS community mechanism for maintaining and upgrading McIDAS software and documentation, and other activities appropriate to a users group. The MUG provides SSEC with the financial support necessary to furnish these services to the users of McIDAS packages. Through its Help Desk, the MUG offers support to members on user, operations, and programming topics. In addition, SSEC can provide contract programming to develop or assist you with developing certain applications.

Use the table below to determine your best method of getting help.

If you want	Contact
clarification of any information contained in this manual to report an error in the manual to make a constructive suggestion for improving the manual	the Help Desk at (608) 262-2455, or send email to the Help Desk.
information about software maintenance and upgrades	the Help Desk at (608) 262-2455 or the MUG Web page at http://www.ssec.wisc.edu/mcidas.html
help writing specific software or debugging your software	your SSEC Program Manager

Companion documentation

The following documentation provides additional information about McIDAS-X.

Online man pages

The online man pages provided with the McIDAS-X software contain detailed descriptions of all the API (Application Program Interface) functions that you will need to build applications. The following section provides more information on using the McIDAS-X man pages.

McIDAS User's Guide

This manual provides users with the installation instructions, general information and commands needed to run McIDAS-X. Each command includes a description of its usage, definitions for all positional parameters and keywords, remarks and examples. The manual also describes the F Key Menu System and ADDE.

McIDAS-X Learning Guide

This manual is a tutorial that guides users through the basics of McIDAS-X using a dataset supplied by SSEC. Each section introduces a new topic, including an introduction and practice session with step-by-step instructions. It contains these eleven lessons: Getting Started, ADDE, Loop Control System, Satellite Imagery, Graphics and the Cursor, Enhancements, MD Files, Grids and Grid Files, String Tables, Real-time Data Access, and the GUI.

Using the online man pages

The online man pages provided with the McIDAS-X software contain detailed descriptions of all the API (Application Program Interface) functions that you will need to build McIDAS-X applications.

The McIDAS-X man pages differ from Unix man pages in two ways.

The McIDAS-X man pages are written for for McIDAS-X software only and tell programmers how to use a particular piece of McIDAS-X software in their programs.
The McIDAS-X man pages are references and are not as complete as Unix man pages. For a complete description of each utility, see Chapter 4, McIDAS-X Utilities.

In this section, you'll find the following information about using the man pages.

Setting the Environment

You must modify the MANPATH environment variable in your .profile (ksh) or .cshrc (csh) files before you can view the man pages.

Login to your account and open the .profile or .cshrc file.
Add ~mcidas/man to the MANPATH environment variable.
Logout and login again for the change to take effect.

Viewing man pages

To display the man page for an API function, enter the command below from the Unix prompt.

Type: man APIfunction

For example, if you wanted to display the man page for the API function sdest , you would enter the command below.

Type: man sdest

The man page is displayed as shown below.

Name:
   sdest    - Puts a string to standard I/O device or file.

Interface:
   subroutine
   sdest (character*(*) charstring, integer n)

Input
   charstring  - Character string to be output.
   n           - An integer that will be output after the string.

Input and Output:
   none

Output:
   none

Return Values:
   none

Remarks
   If 'n' is zero it is not printed.

Categories
   text

Filename
   spout_.c

If you don't know the name of the API function, or want to search for all the API functions related to a particular topic, you can use the xrefit command using the formats below.

xrefit matchword
xrefit -c matchword

The xrefit command searches the name and category fields for matchword . In the sample sdest man page, the Name field contains the description puts a string to a standard I/O device or file and the Categories field contains the word text .

Use the xrefit matchword option to list all the APIs that contain the specified matchword in the name or categories fields. For example, to list all the API functions that contain the word convert, you would enter the command xrefit convert . A subset of the output is shown below.

graphic        McTSTimeToXAxis   Converts a time object to a TV element
graphic        McTSValueToYAxis  Converts a value to a TV line number
converter      Mcargparse        Parses text into arg-fetching structure
day/time       Mccydtodmy        Converts ccyyddd to day/month/year
sys_config     Mcdev2uc          Converts keyword DEV= character value
user_interface Mcstrtodbl        Converts token to type double format
text           cfe               Converts a real character*12

The first column lists the category, the second column lists the API function, and the third column provides a one-line description of the API.

To further define your search, use the -c flag, which lists the APIs whose categories match the specified entry. For example, to list all the API functions with the category converter , you would enter the command xrefit -c converter . A subset of the output is shown below.

converter      mcargparse        Parse text into arg-fetching structure
converter      mchmstostr        Converts a time to a character string
converter      mcinsort          Performs an insertion sort on a list
converter      mcpcal            Parses a list of comment cards
converter      mcstrtodbl        Converts token to type double format
converter      mcucvtd           Converts an array of double precision

Directory location of the man page files

The McIDAS-X man files have names such as sdest.3, Mcgettime.4, and mcgetimageframenumber.3. The extension refers to the subdirectory containing the man files. The xref.tab file is a cross-reference file containing a one-line description of all the API functions. The xrefit function searches this file, as described in the previous section.

The McIDAS-X man page files and tools are placed in the ~/mcidas/man directory, except for the search function xrefit which is stored in ~mcidas/bin . All man files have the .3 extension and reside in the man3 subdirectory, as shown in the table below.

Directory	Contents
~mcidas/bin	xrefit
~mcidas/man	xref.tab xreftawk
~mcidas/man/man3	sdest.3 Mcgettime.3 all other man page files