1. Introduction
1.1 Purpose of Toolkit
The purpose of the SDP Toolkit is primarily (1) to provide an interface to the ECS system, including Planning and Data Production System (PDPS), Communications System Management (CSMS) and Information Management, (2) to allow science software to be portable to different platforms at the DAAC, (3) to reduce redundant coding at the SCF, and (4) to provide value added functionality for science software development. The SDP Toolkit consists of a set of fully tested, fast, efficient and reliable C and FORTRAN language functions, customized for application to ECS.
A brief overview of the operations concept of the Toolkit follows. The Toolkit divides into two groups: Mandatory tools, which the system requires in science software, with checking to occur at DAAC Integration & Test time; and Optional tools, whose primary intention is to save SCF development effort by reducing redundancy.
1.2. Mandatory Tools
The following tools are Mandatory:
At the lowest level are the Error and Status Message (SMF, for Status Message Facility) tools, which provide general error handling, status log messaging, and interface to CSMS services (which are implemented as email and ftp services at the SCF). Essentially all Toolkit functions call the SMF tools for error handling; science software may also use most of the SMF functions. (The Toolkit takes no action itself regarding errors itself; this is left to the science software.)
At the next level are the Process Control (PC) tools, which provide the primary interface to the Planning and Data Production System (PDPS). A major use of these tools is to access physical filenames and file attributes; in addition, they retrieve user-defined parameters. Several Toolkit functions call PC tools.
Generic Input/Output (IO_Gen) tools are at the next level; these tools provide the means to open and close support, temporary and intermediate duration files. Native C and FORTRAN functions perform the actual reads and writes.
Memory allocation (MEM) tools consist of two groups: the first consists of simple wrappers on native C functions, the purpose being to track memory usage in the SDPS; the second consists of "shared memory" tools, which enable the sharing of memory among executables within a PGE.
The rest of the Mandatory tools are higher level, in that they depend on at least some of the lower level tools:
Level 0 access (IO_L0) tools access Level 0 data.
Metadata (MET) access tools allow science software to access, alter, write and append metadata.
Spacecraft ephemeris and attitude access (EPH) tools read ephemeris and attitude data.
Time and Date (TD) tools perform time and date conversions between selected time systems.
1.3 Optional Tools
The remaining tools are Optional:
Ancillary data Access (AA) functions access such data as NMC data and Digital Elevation (DEM) data.
Celestial Body Position (CBP) tools locate the Sun, the Moon and the planets.
Coordinate System Conversion (CSC) tools allow coordinate conversions between celestial reference, spacecraft body referenced, spacecraft orbital referenced, and Earth frames. They also perform related tasks such as locating the sub-satellite point (ground track) and finding the zenith and azimuth of vectors at Earth surface.
Constant and Unit Conversion (CUC) tools allow access to physical constants and unit conversions.
Digital Elevation Model (DEM) tools provide access to HDF-EOS DEM datasets. This will be the primary production DEM data.
The IMSL package provides mathematical and statistical support.
Graphics Support (if any, in the production environment) is TBD.
There are also some Test Tools, which are for use during development at the SCF only. These include an ephemeris and attitude simulator and a Level 0 file simulator.
For the most part the Optional tools are independent of each other, though all depend on the lower level tools, including SMF (all tools), PC, IO_Gen, and TD.
1.4 Toolkit Languages
The Toolkit is written in the C language. A macro package provides bindings to the C code from FORTRAN 77 (with a few exceptions coded directly in F77). These bindings appear to have no effect on processing speed. Where possible, the same Application Program Interface (API), i.e., calling sequence, has been used for both C and FORTRAN. Support of FORTRAN 90 requires no special bindings, since FORTRAN 77 is a subset of FORTRAN 90; testing the Toolkit with an F90 compiler confirms this.
Special note regarding FORTRAN: Programmers are strongly urged to include the IMPLICIT NONE statement at the beginning of every FORTRAN module. This prevents many types of error; in particular, there is less chance you could omit an include file needed for a Toolkit function.
1.5 Purpose of This Document
This document refers to those functions delivered as of the Release B.0 SCF Toolkit (April 1997). Each successive delivery increments the previous delivery with additional functionality, while maintaining a consistent user API. The document will be updated with each successive software delivery.
A user's guide (Release B.0 SCF Toolkit Users Guide, April1997) accompanies the Toolkit delivery. The intent of this guide was to serve as the sole documentation for use of the Toolkit. However, after review, several instrument teams pointed out that it was not useful as a simple introduction to the Toolkit; rather, it resembled the detail and complexity of Unix "man" pages. This document intends to fill that gap.
The purpose of this document is to provide a simple, easy to use guide to Toolkit function usage, through a step-by-step format, including many examples in C and FORTRAN. The intended audience is both science software programmers and their supervisors. After reading it, the user will be able to use the Toolkit API in constructing instrument data production code or incorporating Toolkit calls into heritage code.
This document is necessarily not a comprehensive one; the TK5.2 version of the Users Guide is the definitive source. It contains details such as Toolkit installation instructions, requirements trace, detailed description of inputs and output data and parameters, and so on. For purposes of this document, we assume that the user has a copy of the Toolkit already installed on his/her system, including especially the setting of Toolkit environment variables.
1.6 Document Format
Each of the tool groups delivered to date is listed in its own section. An overview sub-section explains the general usage of the tool group. For each tool, we include: a short explanation of what it's for; step-by-step guide to usage by example, for C and FORTRAN; and a Notes section which includes dependencies on other Toolkit functions, files and environment variables. The examples given are for illustrative purposes only; for compilable examples, please refer to the software test drivers that are part of the Toolkit delivery package.
The Status/Message (SMF), Process Control (PC), and Ancillary Data Access (AA) tool groups are exceptions to the format, in that they need extensive explanation regarding their use as a whole; their "Overview" sections are very long.
Overview
Content Tools