GATS Software Documentation GATS-1993-03

Scientific Software System ( S^{3} )

Version: 2.0 Reference Manual

John Burton Larry Gordley

September 29, 2005

GATS, Inc. 11864 Canon Blvd. Suite 101 Newport News, VA. 23606

(757) 873-5920

Scientific Software System ( S^{3} ) Reference Manual

\begin{matrix}c \\ ◯ \end{matrix} Copyright 1992-2005 by G & A Technical Software, Inc., 11864 Canon Blvd., Suite 101, Newport News Virginia, 23606.

All Rights Reserved. No part of this publication or software may be reproduced, stored

in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without prior written permission of

G & A Technical Software, Inc.

Version 2.0  i  GATS, Inc.

Scientific Software System ( S^{3} ) Reference Manual

Contents

List of Figures iv List of Tables v 1 EMT File Syntax 1 2 PDT File Syntax 1

2.1 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2.2 Datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2.3 Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.4 Dataset Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.5 Static Datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3 PCT File Syntax 4 4 PCP Syntax 8 5 S^{3} Based Implementation 8

5.1 Initial Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5.2 Creating S^{3} Application Programs . . . . . . . . . . . . . . . . . . . . . . . . . . 10 5.3 Adding User Defined Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 5.4 Running S^{3} Application Programs . . . . . . . . . . . . . . . . . . . . . . . . . . 12

6 S^{3} Shell 12 A S^{3} Example 13

Version 2.0  ii  GATS, Inc.

Scientific Software System ( S^{3} ) Reference Manual

A.1 Example PDT configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 A.2 Example PCT configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

B S^{3} Utility Routines 21 B.1 get eol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 B.2 get eoi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 B.3 set eol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 B.4 set eoi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 B.5 incr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 B.6 decr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 B.7 resize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 B.8 ise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 B.9 dsz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 B.10 if then else . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 B.11 call sys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 B.12 copyf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Version 2.0  iii  GATS, Inc.

Scientific Software System ( S^{3} ) Reference Manual

List of Figures

1 Example of a simple EMT file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2 Creation of an S^{3} Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3 Executing an S^{3} Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4 PCT Structure for S^{3} Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 5 Constant, String, and Double segment of PDT for S^{3} Example - safire.pdt …. 15 6 Real segment of PDT for S^{3} Example - safire.pdt . . . . . . . . . . . . . . . . . . 16 7 Integer segment of PDT for S^{3} Example - safire.pdt . . . . . . . . . . . . . . . . 17 8 Primary PCT for S^{3} Example - safire.pct . . . . . . . . . . . . . . . . . . . . . . 18 9 Forward Radiance Calculation for S^{3} Example - forward.pct . . . . . . . . . . . . 19 10 Apodization Calculation for S^{3} Example - apodize.pct . . . . . . . . . . . . . . . 19 11 Interpolation Calculation for S^{3} Example - interpolate.pct . . . . . . . . . . . . . 20 12 Interferogram Calculation for S^{3} Example - interferogrm.pct . . . . . . . . . . . . 20

Version 2.0  iv  GATS, Inc.

Scientific Software System ( S^{3} ) Reference Manual

List of Tables

1 Correspondence of Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2 Correspondence of Dimensioning Constructs . . . . . . . . . . . . . . . . . . . . . 3

Version 2.0  v  GATS, Inc.

EMT File Syntax  Scientific Software System ( S^{3} )  Reference Manual

1 EMT File Syntax

The EMT file defines the executable modules that will be used by the system, including type of routine and the name of the object file.The EMT file contains the names of all the functions and subroutines (and associated filenames) that are called directly from the PCT level of an S^{3} program. Also included in the EMT are the names of any library and object files that support those functions and subroutines. All the exectuable modules listed in the EMT file are collected into a shared library whose members are dynamically loaded as needed during program execution. An example of an EMT file is included below in figure 1.

!
! FORTRAN Subroutines used
!
proc:fs: fillarray   : fillarray.o;
proc:fs: fprintarray : fprintarray.o;
!
! C Subroutines used
!
proc:cs: cprintarray : ./csubs/cprintarray.o;
proc:cs: dump        : ./csubs/dump.o;
!
! Support Libraries used
!
libs: libsupport.a;

Figure 1: Example of a simple EMT file

2 PDT File Syntax

There are three basic quantities defined in the PDT configuration file, constants, datasets, and groups, all of which must be defined prior to use.

2.1 Constants

A constant is specified using the syntax

CONST: < name >=< ivalue >; [< comment >]

PDT File Syntax  Scientific Software System ( S^{3} )  Reference Manual

where:

< name > ≡ the name of the constant
< ivalue > ≡ the integer value expression to be assigned to < name >
< comment > ≡ anything between the semi–colon and the end of the line.

Anything enclosed in square brackets [ ] is considered optional, and the user need not include it in the PDT or PCT file. < ivalue > is an expression that evaluates to an integer value, and can include the following arithmetic operations:

+ ≡ integer addition
- ≡ integer subtraction
* ≡ integer multiplication
/ ≡ integer division
% ≡ integer modulus
** ≡ integer exponentiation

2.2 Datasets

The definition of a dataset is accomplished via

< type >: < namelist > [ : < dimlist >] [ = < ivalue >] ; [ < comment >]

where:

< type > ≡ the data type contained by the dataset(s) in < namelist >
< namelist > ≡ the list of one or more dataset names
< dimlist > ≡ list of zero or more values indicating the size of each dimension
< ivalue > ≡ the initial value(s) of the dataset
< comment > ≡ anything between the semi-colon and the end of the line.

The < type > of the dataset can be one of BYTE, STRING, INT, REAL, DREAL, COMP, and DCOMP. The correspondence of these type to the data types found in FORTRAN and C are given in table 1

Each dataset can have multiple dimensions, the size of each dimension is defined by the corresponding < dim >, which can be either the name of a previously defined constant or an integer value. The correspondence of the dimensioning of S^{3} datasets to FORTRAN and C is given in table 2 for example datasets ARR1, ARR2, and ARR3, which are real arrays of 1, 2, and 3 dimensions respectively.

S^{3} PCT FORTRAN  C
BYTE INTEGER*1 unsigned char
STRING CHARACTER*(*) char *
INT  INTEGER*4  int
REAL  REAL*4  float
DREAL REAL*8  double
COMP COMPLEX*8  struct{ float imag, real }
DCOMP COMPLEX*16  struct{ double imag, real }

Table 1: Correspondence of Data Types

S^{3} PCT  FORTRAN  C
REAL:ARR1:6  REAL ARR1(6)  float arr1[6]
REAL:ARR2:6,4 REAL ARR2(6,4) float arr2[4][6]
REAL:ARR3:6,4,3 REAL ARR3(6,4,3) float arr3[3][4][6]

Table 2: Correspondence of Dimensioning Constructs

2.3 Groups

Often in a large software package, many executable modules operate on the same sets of information. If the information set consists of several datasets and constants, it can be tedious to write the executable entries for these modules in the PCTs. One method to make this process faster and more comprehensible is through the use of groups. Basically a group is defined by associating a name with an group of datasets and / or constants as shown below. When used in the parameter list of an executable entry in a PCT, the group is expanded to the list of datasets / constants in the order defined. A group is specified using the syntax

GROUP: < name >:< namelist >; [< comment >]

where:

< name > ≡ the name to be associated with the group of datasets.
< namelist > ≡ the list of one or more previously defined dataset names
< comment > ≡ anything between the semi–colon and the end of the line.

PCT File Syntax  Scientific Software System ( S^{3} )  Reference Manual

2.4 Dataset Initialization

Initialization of a dataset is accomplished using the < ivalue > construct, where

< ivalue >≡ { < value list > }

and

< value list >≡< value1 >, < value2 >, …, < valueM >,

for datasets of any types or

< ivalue >≡ “character string ”

for datasets of type STRING. < valueM > is either a single character / numeric value, or a single character / numeric value with a repeat factor as shown in the following example:

REAL : ARR1 : 20 = {14 ∗ 27.59, 12.3, 5 ∗ 1.223};

The PDT configuration file given in Appendix A shows clearly how datasets can be initialized.

2.5 Static Datasets

By default a dataset will reside on the heap, the portion of memory that is used by C when dynamically allocating memory to a routine. This provides the ability to tailor, at runtime, the amount of memory used by an application. The drawback to this scheme is that it does require a small amount of overhead to initially allocate the dataset memory. Normally this overhead is not noticeable but in certain instances, such as attempting to allocate individual datasets that approach the size of primary memory, this overhead can become substantial. In these instances it is generally more efficient to statically allocate the dataset, which places it on the runtime stack. This will reduce the startup time at the expense of not being able to modify the size of the dataset during program execution. Statically allocating a dataset is accomplished using the following construct.

STATIC : < name1 >, < name2 >, ⋯, < nameN >;

where < name1 >, ⋯, < nameN > are the name of datasets that have been previously defined.

3 PCT File Syntax

The PCT configuration file establishes which routines will be used, the order in which they will be used, and the parameters that are to be passed to each. The syntax of the PCT file is as follows:

EOL =< EOL >; [ < comment >]
EOI =< EOI >; [ < comment >]
< Entry >  ;  [ < comment >]
⋮  ⋮
< Entry >  ;  [ < comment >]

where:

< T itle > ≡ Title of this PCT
< comment > ≡ anything between the semi–colon and the end of the line.
< EOL > ≡ Execution Order List
< EOI > ≡ Execution Order Index

When parsing the PCT file, the PCP assumes that the first line of the PCT file is the title, the second line is the execution order list, the third line is the execution order index, and the remaining lines are the entries.

< Entry >=< key >: < type >: < name >: < param list >; [ < comment >]

where:

< key > ≡ Unique character identifier for EOL
< type > ≡ One of : PN, CF, CS, FF, FS, DF, DS
PN ≡ Process Configuration Table (PCT)
CF ≡ “C” Function
CS ≡ “C” Subroutine
FF ≡ “FORTRAN” Function
FS ≡ “FORTRAN” Subroutine
DF ≡ “DataSet” Function
DS ≡ “DataSet” Subroutine
< name > ≡ Name of the executable module or PCT
< param list > ≡ < parameter > | < parameter > , < param list > | < fname >
< parameter > ≡ | < identifier > | < ivalue > | < string >

< identifier > ≡ Name of a dataset or constant defined in the PDT
< ivalue > ≡ Integer value to be passed to < name >
< string > ≡ Quote enclosed character string to be passed to < name >
< fname > ≡ Name of PCT file defining PCT < name >

The use of the vertical bar (|) indicates “or”, i.e.

< parameter >≡ | < identifier > | < ivalue > | < string >

means that < parameter > is equal to (can be replaced by) an < identifier > or an < ivalue > or a < string >.

An entry can be one of two major types, a PCT (which is a recursive definition: a PCT can contain a PCT , which can contain a PCT ...), or an Executable. A PCT is identified by < type >= PN. It also has only one “parameter” in its parameter list, which is the name of the file containing the configuration information for that PCT node. An Executable node can be classified as one of several types depending on the way parameters are to be passed, via C language passing mechanism (“C”), via FORTRAN language passing mechanism (“F”), or the routine expects the dataset data structure to be passed (“D”), and if it returns a value (function “F”) or not (subroutine “S”).

The C language parameter passing mechanism implies that the routine is written in C according to the following conventions:

• Parameters are passed by reference, not by value, so the C routine should expect a pointer to the data object, not the data object itself.

• Each additional dimension, after the first, on a multidimensional array requires an additional level of indirection. i.e. if the dataset to be passed to a C routine has been declared REAL: arr3: m1,m2,m3 then within the C routine it should be declared as float ***arr3;. Subsequent manipulation can be accomplished as though the declaration had been float arr3[m3][m2][m1]. Note the reversed dimension declarations. This is necessary because C uses row–major ordering for multi-dimensional arrays, where FORTRAN uses column–major ordering. The array declaration syntax for the PDT file was designed to be consistent with the FORTRAN convention, column–major ordering.

• Strings are NULL terminated, BLANK filled character arrays whose length is specified in the PDT file.

The parameter passing mechanism for S^{3} attempts to make interfacing FORTRAN routines as simple and straight forward as possible. For the most part a standard FORTRAN approach with some minor restrictions was used to handle parameter passing. Specifically the FORTRAN routine should:

• Declare strings passed as parameters to have “previously defined limits”, i.e. the size of the string was declared in the calling program. This declaration is accomplished via

     CHARACTER*(*) string.

• Declare arrays as predefined (similar to the string declaration) or explicitly include the array’s dimensioning information in the parameter list. Dimensioning arrays within a routine to a different size (particularly a larger size) than was declared in the PDT file will lead to unpredictable results. (Note: there is a run time option that will perform runtime bounds checking upon exit from each routine call from a PCT)

Each dataset that is declared in the PDT and subsequently used in a PCT has associated with it some bookkeeping information that is maintained by the S^{3} program. This includes such information as the name of the dataset, the type of the data, the number of dimensions, the size of each dimension, and a pointer (memory address) to the beginning of the data. Most of the time the user does not need to access this information and will simply want the data (or rather a pointer to the data - FORTRAN passes parameters by reference to the data by default), which is what a routine declared as “C” or “F” will have passed to it. On the other hand, a routine declared as “D” will have the entire dataset data structure passed to it. Such a routine can then modify any of the bookkeeping information about the dataset. Care should be taken when modifying dataset information in this way, since such modifications could have unpredictable results.

In general, routines written in FORTRAN will be either “FF” or “FS”, routines written in C will be either “CF” or “CS”. The “DF” and “DS” types are used only when it is necessary to manipulate the entire dataset data structure instead of just the data.

An executable classified as a function (“F”) is expected to return an integer value. This value is in turn used to modify how the system is functioning. A return value of zero (0) indicates that the PCT should continue executing according to the Execution Order List and Execution Order Index. A return value of one (1) indicates that the PCT should halt at this point and return control to the calling or parent PCT node. The next time the child PCT node is called, it will pick up where it left off by starting to execute at the next routine indicated in the Execution Order List. A return value of greater than one (1) specifies how many levels of PCTs to ascend. (A return value of 2 would mean to halt this PCT and the parent PCT, 3 would mean to halt this PCT, the parent PCT, and the grandparent PCT, etc.)

PCP Syntax  Scientific Software System ( S^{3} )  Reference Manual

4 PCP Syntax

The Process Control Program performs two major functions. First it creates and initializes the S^{3} runtime environment, and then it calls (executes) the appropriate routines as specified by the PCT files. The PCP has several command line options that affect overall execution. The user can specify an alternate base name for the primary PCT and PDT files, i.e. if the user specifies a base name of foo then the PCP will look for the two files foo.pdt and foo.pct. Otherwise the PCP will look for the two files program.pdt andprogram.pct. Execution of the PCP will then continue based on the files specified. The user has a choice of several operating modes;

• Normal mode (default) displays no information about the execution progress.

• Bounds check mode (-b command line option) checks for dataset bounds violations (modifying memory beyond the limits of a dataset) after each routine called at the PCT level.

• Profile mode (-p command line option) displays cumulative execution statistics concerning how many times each routine was called and the total time spent in each routine.

• Verbose mode (-v command line option) displays information concerning which routine is currently executing and how much time was required for that routine to execute.

Extensions to the capabilities of the PCP are primarily added via the S^{3} utilities library. The current utilities library provides PCT looping constructs DSZ (decrement and skip if zero) and ISE (increment and skip if equal), conditional branching (if then else), file copying, and creation of child processes via a system call. These routines are discussed in greater detail in the Appendices.

5 S^{3} Based Implementation

S^{3} Based Implementation  Scientific Software System ( S^{3} )  Reference Manual

To create an S^{3} based program the user needs to determine which routines will be called, what order they will be called in, and the type, size and dimensionality of each parameter required by the particular routine. The user then creates PDT and PCT files based on this information. The PDT file is used to define the size, type, and dimensionality of each variable that will be passed to the various routines. The PCT files are used to define which routines are called, what order they are called in, and which parameters are passed to them. As a starting point, in addition to the S^{3} library and PCP main routine, the S^{3} package includes a basic set of routines for analyzing data generated by the SAFIRE instrument. These routines are supplied in two libraries, the GATS LINECAL library of limb line-by-line radiance profile routines, and the SDAS library of data analysis routines specifically tailored for the SAFIRE instrument data.

In many situations the S^{3} library (and PCP main routine) combined with the SDAS data analysis routines will satisfy the researcher’s processing and analysis needs. In other situations the researcher will want to include their own routines in the S^{3} hierarchy for a particular aspect of processing. Both situations are discussed in greater detail below.

5.1 Initial Installation

Before an S^{3} program can be created, the S^{3} package must be installed. The S^{3} software package is currently supported only on AIX 3.1.5 (IBM’s version of UNIX) running on the IBM RS/6000 architecture. Work is in progress to port S^{3} to Sun OS 4.1.1 running on the Sun Sparc architecture. To be installed on a particular system, the S^{3} package requires the system to have both a FORTRAN 77 compiler and a C compiler (preferably ANSI C compliant). The S^{3} software package is supplied in UNIX tar file format. To install S^{3} on a UNIX system simply follow the steps given below.

1. Create a temporary directory for use during the installation process. Although the directory can have any legal name, for purposes of these instructions it will be called TEMP.

2. Place the S3.tar file in TEMP.

  3. Type tar -xvf S3.tar >& tar.log

4. After the tar command finishes, the following files should be in TEMP:

      (a) Makefile
     (b) Manifest
      (c) README
     (d) Version
      (e) tar.log

and the following subdirectories:

      (a) Linecal

(b) S3

      (c) SDAS

5. Compare Manifest to tar.log. They should contain the same filenames. If not, you should contact G & A Technical Software.

6. Decide where various files needed by the S^{3} package will be located:

(a) Set the environmental variable S3SRCDIR to the directory that will contain the

    S^{3} PCP source file (s3main.c) (for example setenv S3SRCDIR /usr/local/src ).

(b) Set the environmental variable S3INCDIR to the directory that will contain the S^{3} include (header) files (for example setenv S3INCDIR /usr/local/include ).

(c) Set the environmental variable S3LIBDIR to the directory that will contain the S^{3} , SDAS, and LINECAL libraries (for example setenv S3LIBDIR /usr/local/lib ).

(d) Set the environmental variable S3BINDIR to the directory that will contain the

    S^{3} setup utility program (for example setenv S3BINDIR /usr/local/bin ).

The particular directories specified above are examples for installing the S^{3} package on a system where multiple users will be using the package and would probably require help from the Systems Administrator (the installation process needs write access to the specified directories). For a single user, simply set the environmental variables to specify directories within the users directory structure. The environmental variables specified will be used both during the installation process and every time the S^{3} based program is reconfigured, so it is advisable to make them a permanent part of the environment (i.e. have them set during the login process via either the .cshrc or .login files for the csh or tcsh user shell, or the .profile file for the sh or ksh user shell.

7. Once the environmental variables have been set, make sure you are in the TEMP directory and type make >& make.log. This process compiles and creates the libraries that are used by the S^{3} system and will take several minutes to complete.

8. Once the make process has been successfully completed (check make.log for any error messages), now type make install >& install.log. The install process will copy the appropriate files to the directories specified by S3SRCDIR, S3INCDIR, S3LIBDIR, and S3BINDIR (requires write access to these directories).

The initial installation is now complete.

5.2 Creating S^{3} Application Programs

Once the S^{3} package has been installed, the user can begin to create application programs. As a first step copy the file Makefile.s3 from the S3SRCDIR and rename it Makefile(i.e. cp S3SRCDIR/Makefile.s3 Makefile). As mentioned previously, the S^{3} package provides the appropriate routines to perform basic limb profile retrievals. To create an S^{3} program example2 that will only use routines in the SDAS or LINECAL libraries, the user will need to create a PDT example2.pdt file defining the required parameters and a primary PCT file example2.pct defining the routines used, the parameters to be passed to them, the order in which they are called, and any secondary PCT files that are to be used. The user must also create any secondary PCT files required. Modify the the line in Makefile that reads NAME = safire to read NAME = example2. Now simply type make and if no errors are encountered, an executable program file named example2 will be created in the current directory. This process of S^{3} program creation is shown diagrammatically in figure 2, where the make process is represented by the thick lined box.

Figure 2: Creation of an S^{3} Program

Since for this example, all the executable routines are provided with the S^{3} package, once the program has been created, the only time that it would be necessary to do a make is when:

1. Adding a new routine to a PCT file (i.e. adding a routine that is not in one of the PCT files).

2. Changing the name, size, type or dimensionality of a dataset that is declared STATIC in the PDT file.

Adding routines that are not provided with the S^{3} package, i.e. user defined routines, is covered in the reference section 5.3.

S^{3} Shell  Scientific Software System ( S^{3} )  Reference Manual

5.3 Adding User Defined Routines

Adding a user defined / created routine to an S^{3} based program is accomplished by:

1. Specifying the user routine in the appropriate PCT file(s).

2. Defining the required datasets in the PDT file.

3. Specifying the location of the user routine in Makefile.

4. Typing make

The Makefile assumes that the user routine will be available in one of two forms, source code (FORTRAN or C) in a file in the current directory, or in a previously compiled library (see figure 2) To include a routine that is in a source file, simply modify the USROBJS = line in the Makefile to include the name of the source file with a .o extension (i.e. if the source code is in a file named routine.f, modify the USROBJS = line to read USROBJS = routine.o). This will cause make to compile the source file and link it to the S^{3} program. Anytime the source file is modified, a make should be performed. To include a routine that is in a precompiled library, simply modify the USRLIBS = line in the Makefile to include the pathname of the library (i.e.

if the library is /u/jcburt/lib/libjunk.a, modify the USRLIBS = line to read USRLIBS =

/u/jcburt/lib/libjunk.a). In this case, the user is responsible for ensuring that the specified library is current, make will not be able to determine if the library is up-to-date.

5.4 Running S^{3} Application Programs

To run an S^{3} based program, simply type in its name followed by any command line switches. If we wanted a verbose execution of example with a execution profile displayed at the end,

simply type example -v -p. example will then read the files example.pdt and example.pct,

and then perform the operations specified in the PCT file(s) (see figure 3). If a new routine was added with out subsequently performing a make the S^{3} program will halt with an error message indicating that it can’t find the routine. If this occurs, simply run make which should correct the problem.

6 S^{3} Shell

S^{3} Example  Scientific Software System ( S^{3} )  Reference Manual

Figure 3: Executing an S^{3} Program

A S^{3} Example

Figure 4: PCT Structure for S^{3} Example

A.1 Example PDT configuration file

;
; Constants used by the Safire system
;
CONST:  nl     =    9000;
CONST:  mir    =      10;
CONST:  ml     =      32;
CONST:  mr     =      64;
CONST:  mgg    =      20;
CONST:  mgs    =       4;
CONST:  mpts   =  200000;
CONST:  msiz   = 6000000;
CONST:  mqmix  =     128;   (ml * mgs)
CONST:  mpmass =    8192;   (ml * ml * mgs * 2)
CONST:  mtbs   =    2048;   (ml * ml * 2)
CONST:  natmos =       8;
;
; Definition of the datasets used by the Safire system
;
;
; Datasets of type STRING
;
STRING: control  : 64 = "consaf.dat" ;
STRING: atmos    : natmos ;
STRING: nam      : mgg,8;
STRING: name     : mgs,8;
STRING: filen    : ml,32;
;
; Datasets of type DOUBLE (DREAL)
;
DREAL:  vs1      ;
DREAL:  vs2      ;

Figure 5: Constant, String, and Double segment of PDT for S^{3} Example - safire.pdt

;
; Datasets of type REAL
;
REAL:   dvel     := {0.0};
REAL:   hires    : mpts;
REAL:   temp     := {0.0};
REAL:   za       : ml ;
REAL:   re       ;
REAL:   xlat     ;
REAL:   qg       : 2,mqmix;
REAL:   zt       : ml;
REAL:   pt       : ml;
REAL:   tt       : ml;
REAL:   qmix     : mqmix;
REAL:   wnmax    := {20.0};
REAL:   zr       : mr;
REAL:   pr       : mr;
REAL:   tr       : mr;
REAL:   tgr      : 2,mr;
REAL:   gr       : 2,mr;
REAL:   q        : mr,mgg;
REAL:   qgr      : 2,mr,mgg;
REAL:   odmin    := {0.1E-09};
REAL:   resmax   := {0.0};
REAL:   resfc    := {0.3};
REAL:   pmw      : ml;
REAL:   tmw      : ml;
REAL:   tbs      : mtbs;
REAL:   pb       : ml;
REAL:   gasb     : mqmix;
REAL:   pmass    : mpmass;
REAL:   fact     :1 = {0.0};

Figure 6: Real segment of PDT for S^{3} Example - safire.pdt

;
; Datasets of type INTEGER
;
INT:    iblk     ;
INT:    iblko    :={0};
INT:    icnt     :={1};
INT:    icwrt    :={0};
INT:    iwrt     ;
INT:    ifrst    ;
INT:    iunit    : ml;
INT:    istatus  ;
INT:    idg      : mgs;
INT:    isc      := {1};
INT:    isco     := {0};
INT:    iopt     := {1};
INT:    icalc    := {2};
INT:    ioptt    := {1};
INT:    ir       : mir ;
INT:    iri      ;
INT:    irf      := {1};
INT:    imr      := {2};
INT:    iflag    := {2};
INT:    iopto    : ml;
INT:    igas     : mgs;
INT:    igs      : mgs;
INT:    igm      : mgs;
INT:    jtype    := {1};
INT:    nir      := mir;
INT:    ncel     ;
INT:    ngas     ;
INT:    npts     :=mpts;
INT:    nr       ;
INT:    nrun     ;
INT:    nsr      :={1};
INT:    nmr      :={60};
INT:    ngg      ;

Figure 7: Integer segment of PDT for S^{3} Example - safire.pdt

A.2 Example PCT configuration files

EOL=a,b,c,d,e,f,g,h,i,j,k,l,m,p,o,a,n,z;       ! Execution Order List (EOL)
EOI=0;                                         ! Execution Order Index (EOI)
a:OPENFILES    :"consaf.dat",iflag,lcon,lpr,lout,lafg,lbug,\
                 lapd,lntrp,lifg;
b:READCON      :iblk,vs1,vs2,ncel,za,temp,ngas,idg,ir,nir;
c:READDATA     :atmos,re,xlat,mr,nr,ngg,nam,igs,zr,\
                pr,tr,tgr,q,qgr,temp;
d:SETOPT1      :ngg,ngas,igm,nam,name,idg,igs,igas;
e:GET_ELEMENT1 :iri,ir,icnt;
f:FORWARD      :forward.pct;
g:SET_EOI      :"FORWARD",3;
h:APODIZE      :apodize.pct;
i:SET_EOI      :"APODIZE",0;
j:INTERPOLATE  :interpolate.pct;
k:SET_EOI      :"INTERPOLATE",0;
l:INTERFEROGRM :interferogrm.pct;
m:SET_EOI      :"INTERFEROGRM",0;
n:ISE          :icnt,nir,4;
o:CLOSEFILES   :;
p:CALL_SYS     :"xterm -e idl";

Figure 8: Primary PCT for S^{3} Example - safire.pct

EOL=a,b,c,d,e,f,z;
EOI=0;
a:AFGLSET      :jtype,idg,ngas,vs1,vs2,wnmax;
b:MASS         :ncel,nr,irf,imr,nsr,ncel,igm,ngas,isc,re,\
                za,zr,pr,tr,tgr,q,qgr,zt,pt,tt,gr,qmix,qg,\
                pmw,tmw,tbs,pb,gasb,pmass,fact;
c:CROSS        :nrun,iopt,icalc,ncel,ncel,idg,ngas,vs1,vs2,\
                wnmax,resfc,resmax,odmin,nsr,ncel,zt,pb,tmw,\
                gasb,pmass,icwrt,iwrt,ifrst,iunit,istatus,filen;
d:INGRATE      :icalc,iopt,iopto,iwrt,iunit,ncel,ncel,igas,\
                ngas,vs1,vs2,dvel,iri,iri,tbs,pmass;
e:GETHIRES     :npts,bpwn,epwn,resmin,hires;
f:SPECWRITE    :lout,iflag,iri,npts,bpwn,epwn,resmin,hires,zt;

Figure 9: Forward Radiance Calculation for S^{3} Example - forward.pct

EOL=a,b,c,d,e,f,g,h,i,j,k,l,m,z ;
EOI=0 ;
a:GETSPC        :nrd2,npts,hires,rad,crad,k3;
b:ARRAY         :rad,radd,nrd2,nrd1,1;
c:FOUR1         :radd,nrd2,1;
d:CALC_NPSF_RES :npsf,res,flaser,ssp,lm;
e:CALC_J1_J2_NP :j1,j2,np,npts,resmin,res,nrd2;
f:CMPX          :crad,radd,nrd2,nrd1,1;
g:CUT           :crad,j1,j2,nrd2;
!g:FS:CUT           :crad,0,131072,nrd2;
h:CMPX          :crad,radd,nrd2,nrd1,-1;
i:FOUR1         :radd,nrd2,-1;
j:NORM2         :radd,nrd1;
k:ARRAY         :rad,radd,nrd2,nrd1,-1;
l:RADPF         :rad,rad1,nrd2,npts,k3;
m:SPECWRITE     :lapd,iflag,iri,npts,bpwn,epwn,resmin,rad1,zt;

Figure 10: Apodization Calculation for S^{3} Example - apodize.pct

!"Generate the Interpolated (low resolution) Spectra" ;
EOL=a,b,c,z;
EOI=0;
a:CALC_R0    :r0,rad;
b:SSINTERP   :np,npts,res,resmin,rad1,a,r0,r0;
c:SPECWRITE  :lntrp,iflag,iri,np,bpwn,epwn,res,a,zt;

Figure 11: Interpolation Calculation for S^{3} Example - interpolate.pct

!"Generate the Simulated Interferogram" ;
EOL=a,b,c,d,e,z ;
EOI=0 ;
a:MIRROR     :radfull,a,npsf,np,res;
b:COSFT      :radfull,npsf,-1;
c:NORM2      :radfull,npsf;
d:INTF       :radfull,r,npsf,nnk;
e:SPECWRITE  :lifg,iflag,iri,nnk,bpwn,epwn,res,r,zt;

Figure 12: Interferogram Calculation for S^{3} Example - interferogrm.pct

S^{3} Utility Routines  Scientific Software System ( S^{3} )  Reference Manual

B S^{3} Utility Routines

The following pages contain descriptions of the S^{3} utility routines. The primary purpose of these routines is to provide the user access to the Execution Order Control information stored in the Process Control Table(s), and to perform some simple operations on datasets.

get eol  Scientific Software System ( S^{3} )  Reference Manual

Purpose Gets the current Execution Order List (EOL) for the specified Process Control Table (PCT).

C Syntax #include "defs.h" #include "safire.h"

char *get eol ( char *PCTname )

FORTRAN Syntax

CHARACTER*64 FGET EOL(PCTNAME) CHARACTER PCTNAME*32

PDT Entry STRING : PCTname : 32 ; STRING : EOL : 64 ;

PCT Entry a : DS : GET EOL : PCTname, EOL ;

Remarks get eol gets the current Execution Order List (EOL)for the PCT specified by PCTname. The returned value is a NULL terminated character string. If PCTname is not a valid PCT name, get eol aborts the program and returns an error message.

See Also set eol, get eoi, set eoi

Author John Burton, G & A Technical Software Inc. 07/08/91

get eoi  Scientific Software System ( S^{3} )  Reference Manual

Purpose Gets the current Execution Order Index (EOI) for the specified Process Control Table (PCT).

C Syntax #include "defs.h" #include "safire.h"

int get eoi ( char *PCTname )

FORTRAN Syntax

INTEGER*4 FGET EOI(PCTNAME) CHARACTER*(*) PCTNAME

PDT Entry STRING : PCTname : N ; INT : EOI ;

PCT Entry a : DS : GET EOI : PCTname , EOI ;

Remarks get eoi gets the current Execution Order Index (EOI) for the PCT specified by PCTname. The returned integer value is an index into EOL for PCTname indicating the next entry in the PCT PCTname to be executed. If PCTname is not a valid PCT name, get eoi aborts the program and returns an error message. NOTE: EOL is a array of characters with array locations starting at 0 in accordance with C syntax (as opposed to FOR-TRAN syntax where character arrays start at location 1). This means that values returned by get eoi start at 0 for the 1st location, 1 for the second location, etc.

See Also set eoi, get eol, set eol

Author John Burton, G & A Technical Software Inc. 07/08/91

set eol  Scientific Software System ( S^{3} )  Reference Manual

Purpose Sets the current Execution Order List (EOL) for the specified Process Con-

trol Table (PCT).

C Syntax #include "defs.h" #include "safire.h" void set eol ( char *PCTname, char *EOL )

FORTRAN Syntax

CHARACTER PCTname*32, EOL*64 FSET EOL(PCTname, EOL)

PDT Entry STRING : PCTname : 32 ;

STRING : EOL : 64 ;

PCT Entry a : DS : SET EOL : PCTname, EOL ; Remarks set eol sets the current Execution Order List (EOL) for the PCT specified

by PCTname to the string specified by EOL. If PCTname is not a valid PCT name, set eol aborts the program and returns an error message.

See Also get eol, get eoi, set eoi Author John Burton, G & A Technical Software Inc. 07/08/91

set eoi  Scientific Software System ( S^{3} )  Reference Manual

Purpose Sets the current Execution Order Index (EOI) for the specified Process Control Table (PCT).

C Syntax #include "defs.h" #include "safire.h"

void set eoi ( char *PCTname, int EOI )

FORTRAN Syntax

CHARACTER PCTNAME*32 INTEGER*4 EOI FSET EOI(PCTNAME, EOI)

PDT Entry STRING : PCTname : 32 ; INT : EOI ;

PCT Entry a : DS : SET EOI : PCTname, EOI ;

Remarks set eoi sets the current Execution Order Index (EOI) for the PCT specified by PCTname to the value specified by EOI. If PCTname is not a valid PCT name, set eol aborts the program and returns an error message.

See Also get eoi, get eol, set eol

Author John Burton, G & A Technical Software Inc. 07/08/91

incr  Scientific Software System ( S^{3} )  Reference Manual

Purpose Increments the value contained in dataset DSname by amount INCby. This

routine is to be used as a PCT entry only.

PDT Entry INT : DSname ;

INT : INCby = {10} ;

PCT Entry a : DS : INCR : DSname, INCby ; Remarks DSname must be a zero dimensional integer dataset (i.e. a simple variable).

INCby can be a zero dimensional integer dataset, a constant (as declared in the PDT configuration file) or an integer numeric value.

See Also decr Author John Burton, G & A Technical Software Inc. 07/08/91

decr  Scientific Software System ( S^{3} )  Reference Manual

Purpose Decrementss the value contained in dataset DSname by amount DECby.

This routine is to be used as a PCT entry only.

PDT Entry INT : DSname ;

INT : DECby = {10} ;

PCT Entry a : DS : DECR : DSname, DECby ; Remarks DSname must be a zero dimensional integer dataset (i.e. a simple variable).

DECby can be a zero dimensional integer dataset, a constant (as declared in the PDT configuration file) or an integer numeric value.

See Also incr Author John Burton, G & A Technical Software Inc. 07/08/91

resize  Scientific Software System ( S^{3} )  Reference Manual

Purpose Alters the size of a multi-dimensional (i.e. 1 or more dimensions) dataset by modifying the value of the declared dimension size(s).

PDT Entry DREAL : DSname : oldsize1, oldsize2 ;

PCT Entry a : DS : RESIZE : DSname : newsize1, newsize2 ;

Remarks Currently RESIZE only modifies the value of the dimension size(s), no new space is allocated (perhaps in version 2.0 ?). What this means is that newsize ≤ oldsize, otherwise a memory (segmentation) fault will occur when trying to access the “additional” memory.

Author John Burton, G & A Technical Software Inc. 07/08/91

ise  Scientific Software System ( S^{3} )  Reference Manual

Purpose Provides a looping construct within a PCT node via Increment and Skip when Equal.

PDT Entry INT : Count; INT : End ; INT : Index;

PCT Entry a : DS : ISE : Count, End, Index ;

Remarks ise compares the value of Count to End. If Count is less than End then ise sets the EOI for the current PCT to Index and increments Count by one. If em Count is greater than or equal to End then ise simply returns.

See Also dsz

Author John Burton, G & A Technical Software Inc. 10/09/91

dsz  Scientific Software System ( S^{3} )  Reference Manual

Purpose Provides a looping construct within a PCT node via Decrement and Skip

when Zero.

PDT Entry INT : Count; INT : End ; INT : Index;

PCT Entry a : DS : DSZ : Count, Index ; Remarks dsz decrements the value of Count by one. If Count is equal to zero then

dsz sets the EOI for the current PCT to Index.

See Also ise Author John Burton, G & A Technical Software Inc. 10/09/91

if then else  Scientific Software System ( S^{3} )  Reference Manual

Purpose Provides a conditional branching construct within a PCT via If-Then-Else. PDT Entry INT : Test ;

INT : Tindex; INT : Findex;

PCT Entry a : DS : IF THEN ELSE : Test, Tindex, Findex ; Remarks if then else conditionally branches based on the value of Test. If (Test !=

0) then set the EOI for the current PCT to Tindex. If (Test == 0) then set the EOI for the current PCT to Findex.

Author John Burton, G & A Technical Software Inc. 10/09/91

call sys  Scientific Software System ( S^{3} )  Reference Manual

Purpose Provides access to operating system commands and programs external to

the S^{3} program.

PDT Entry STRING : command : 32; PCT Entry a : DS : CALL SYS : command ; Remarks call sys causes a process to be spawned by the S^{3} program. The child

process can either block or not block the parent S^{3} program. The spawned process will execute the program or command command.

Author John Burton, G & A Technical Software Inc. 10/09/91

copyf  Scientific Software System ( S^{3} )  Reference Manual

Purpose Copies a file from pathname file1 to pathname file2 using the UNIX cp command.

PDT Entry STRING : file1 : N; STRING : file2 : N;

PCT Entry a : DF : COPYF : file1, file2 ;

Remarks copyf copies the source file or source directory named by the file1 parameter to the target file or target directory named by the file2 parameter. file1 and file2 can be either a full pathname or a relative pathname. file1 may contain wildcard characters, em file2 should not contain wildcard characters.

Author John Burton, G & A Technical Software Inc. 10/09/91