1.1 Introduction

The CDF Primer is designed for scientists, researchers, programmers, and managers who want to learn about CDF without reading through this entire document or the programming reference guides. The primer will address what CDF is and how it can be used for storing and managing different types of data. A brief description of the tools and utilities available with CDF, in addition to program and toolkit examples, will be given. More detailed descriptions of the concepts presented herein are provided in the accompanying chapters of this document and the programming reference guides.

1.2 Why Use CDF?

When people first hear the term CDF they intuitively think of data formats in the traditional sense of the word (i.e., messy/convoluted storage of data on disk or tape). CDF is more than just a format. CDF is a "self-describing" format for managing data. In addition to the actual data being stored, CDF also stores user-supplied descriptions of the data, known as metadata. This self-describing property allows CDF to be a generic, data-independent format that can store data from a wide variety of disciplines.

In addition to being a self-describing data format, CDF is also a software library. The library routines are callable from C and Fortran and allow the user to randomly access and manage data and metadata without regard to their physical storage. This completely relieves the user of low-level I/O operations allowing more time for data analysis. The actual format used to store the data and metadata is completely transparent to the user.

The term "CDF" is also used to refer to the physical files that the CDF library generates. A data set stored using the CDF library is called a "CDF".

1.3 Conceptual Organization

An important feature of CDF is that it can handle data sets that are inherently multidimensional in addition to data sets that are scalar. To do this, CDF groups data by "variables" whose values are conceptually organized into arrays. The dimensionality of these variable arrays depends upon the data and is specified by the user when the CDF or a variable is created. For scalar data, as an example, the array of values would be 0-dimensional (i.e., a single value); whereas for image data the array would be 2-dimensional. Similarly, the array for volume data would be 3-dimensional. CDF allows users to specify arrays of up to ten dimensions. The array for a particular variable is called a "variable record." A collection of arrays, one for each variable, is referred to as a "CDF record." A CDF can, and usually does, contain multiple CDF records. This is useful for data with repeated observations at different times.

Two types of variables may exist in a CDF: rVariables[2] and zVariables.[3] Every rVariable in a CDF must have the same number of dimensions and dimension sizes. In the scalar data example the CDF's rVariables would be 0-dimensional, whereas for the image data example the CDF's rVariables would be 2-dimensional. Figures 1.1 and 1.2 illustrate 0-dimensional and 2-dimensional rVariables, respectively. zVariables may have a different number of dimensions and/or dimension sizes than that of the rVariables in a CDF. Figure 1.3 illustrates several zVariables. Note that a CDF may contain both rVariables and zVariables.[4] The term "variable" is used when describing a property that applies to both rVariables and zVariables.

It is important to note that there is no single "correct" way to store data in a CDF. The user has complete control over how the data values are stored in the CDF (within the confines of the variable array structure) depending on how the user views the data. This is the advantage of CDF. Data values are organized in whatever way makes sense to the user.

1.4 Features of the CDF Library

The CDF library is a flexible and extensible software package that gives the user many options for creating and accessing a CDF.

1.4.1 File Format Options

The CDF library gives the user the option to choose from one of two file formats in which to store the data and metadata. The first option is the traditional CDF multi-file format. This file format is illustrated in Figure 1.4 (assuming a CDF containing four variables). The example.cdf file contains all of the control information and metadata for the CDF. In addition to the .cdf file,[5] a file exists for each variable in the CDF and contains only the data associated with that variable. This is illustrated by the files example.v0 through example.v3. The second option is the single-file format, the default format when a CDF file is created. As illustrated in Figure 1.5, the whole CDF file consists of only a single example.cdf file. This file contains the control information, metadata, and the data values for each of the variables in the CDF. Both formats allow direct access. The advantage of the single-file format is that it minimizes the number of files one has to manage and makes it easier to transport CDFs across a network. The organization of the data within the single file may, however, become somewhat convoluted, slightly increasing the data access time. The multi-file format, on the other hand, clearly delimits the data from the metadata and is organized in a consistent fashion within the files. Updating, appending, and accessing data are also done with optimum efficiency.

For multi-file format CDFs, certain restrictions are applied. They are:[6]

- Compression: Compression is not allowed for the CDF or any of its variables.

- Sparseness: Sparse records or arrays for variables are not allowed.

- Allocation: Pre-allocation of records or blocks of records is not allowed. For each variable, the maximum written record is the last allocated record.

- Deletion: Deletion of a single variable from a CDF is not allowed. Only deleting a whole CDF is possible.

Record rVariable rVariable . . . rVariable

Number 1 2 n

1 o o . . . o

2 o o o

3 o o o

. . . .

n o o o

Figure 1.1 Conceptual View of a CDF, 0-Dimensional rVariable

Record rVariable rVariable . . . rVariable

Number 1 2 n

1 ooooo ooooo ooooo

ooooo ooooo ooooo

ooooo ooooo . . . ooooo

ooooo ooooo ooooo

2 ooooo ooooo ooooo

ooooo ooooo ooooo

ooooo ooooo . . . ooooo

ooooo ooooo ooooo

3 ooooo ooooo ooooo

ooooo ooooo ooooo

ooooo ooooo . . . ooooo

ooooo ooooo ooooo

. . . .

n ooooo ooooo ooooo

ooooo ooooo ooooo

ooooo ooooo . . . ooooo

ooooo ooooo ooooo

Figure 1.2 Conceptual View of a CDF, 2-Dimensional rVariables

Record rVariable rVariable . . . rVariable

Number 1 2 n

1 ooooo o

ooooo ooooo o

ooooo ooooo . . . o

ooooo o

2 ooooo o

ooooo ooooo o

ooooo ooooo . . . o

ooooo o

3 ooooo o

ooooo ooooo o

ooooo ooooo . . . o

ooooo o

. . . .

n ooooo o

ooooo ooooo o

ooooo ooooo . . . o

ooooo o

Figure 1.3 Conceptual View of a CDF, zVariables

example.cdf example.v0 example.v1 example.v2 example.v3

D

A

T

A

D

A

T

A

D

A

T

A

D

A

T

A

M

E

T

A

D

A

T

A

Figure 1.4 Multi-File Format

example.cdf

M
E

T

A

D

A

T

A

&

D

A

T

A

Figure 1.5 Single-File Format

1.4.2 Data Encoding Options

When creating a CDF, a user has the option of using any of the supported encodings: VAX, Sun, SGi Personal Iris and Power Series, DECstation, DEC Alpha/OSF1, DEC Alpha/OpenVMS (D FLOAT, G FLOAT or IEEE FLOAT double-precision flfloating-point), IBM RS6000 series, HP 9000 series, NeXT, PC, Macintosh, or network (XDR - eXternal Data Representation). The created CDF may then be copied to any of the supported computers and read by the CDF library. When a value is read from the CDF, the CDF library may be requested to decode the value into the encoding of the computer being used or any of the other encodings (which may be desirable for various reasons). A CDF with any of the supported encodings may be read from and written to on any supported computer.

1.4.3 Compression

Compression may be specified for a single-file CDF and the CDF library can be instructed to compress a CDF as it is written to disk. This compression occurs transparently to the user. When a compressed CDF is opened, it is automatically decompressed by the CDF library. An application does not have to even know that a CDF is compressed. Any type of access is allowed on a compressed CDF. When a compressed CDF is closed by an application, it is automatically recompressed as it is written back to disk.

The individual variables of a CDF can also be compressed. . The CDF library handles the compression and decompression of the variable values transparently. The application does not have to know that the variable is compressed as it accesses the variable's values.

Several different compression algorithms are supported by the CDF library. When compression is specified for a CDF or one of its variables, the compression algorithm to be used must be selected. There will be trade-offs between the different compression algorithms regarding execution performance and disk space savings.

The nature of the data in a CDF (or variable) will affect the selection of the best compression algorithm to be used.

1.4.4 Sparseness

Two types of sparseness are allowed for CDF variables: sparse records and sparse arrays. Sparse records are available now - sparse arrays won't be available until a future CDF release. When a variable is specified as having sparse records, only those records actually written to that variable will be stored in the CDF. This differs from variables without sparse records in that for those variables every record preceding the maximum record written is stored in the CDF. For example, if only the 1000th record were written to a variable without sparse records, the 999 preceding records would also be written using a pad value. If sparse records had been specified for the variable, only the 1000th record would be stored in the CDF (saving a considerable amount of disk space). Sparse records are ideal for variables containing gaps of missing data.

1.4.5 Variable Data Access Options

A program can access variable data one value at a time or it can access an entire multidimensional array structure or substructure spanning contiguous or non-contiguous record boundaries. The latter feature allows the user to perform aggregate access or uniform subsampling of the data at greatly increased rates over traditional value by value access.

1.5 Organizing Your Data in a CDF

1.5.1 Variables

The first component of a CDF is the actual data, organized into arrays for the individual variables. CDF can accommodate any type of data that can be organized into arrays. Two types of variables are supported: rVariables and zVariables.

rVariables[7]

rVariables all have the same dimensionality (number of dimensions and dimension sizes). An example of the type of data set that may be stored in a CDF's rVariables is shown in Table 1.1. Each record holds one value for each of the four variables: Time, Longitude, Latitude, and Temperature. CDF can store scalar data in a "at" (0-dimensional) representation such as this, but storage in this manner may hide fundamental relationships among the data values. Consistent repetitions found in the data for this example suggest another way to organize the data set. Note that every fourth record is an observation at the same point on Earth at different times. That fact is not immediately clear from this representation of the data. Looking more closely, we note that only two differing values are recorded for Longitude and, similarly, only two differing values are recorded for Latitude. This repetition suggests a 2-dimensional array structure whose dimensions are defined by Longitude and Latitude. For each of the two Longitude values there are two Latitude values. Time repeats for each Longitude/Latitude pair - the observations were taken simultaneously at the longitude/latitude locations. Because of Time's repetition for Longitude/Latitude pairs, the number of Time values specifies the number of records needed in the CDF. Each record conceptually contains a 2-dimensional array per rVariable (Table 1.2). The array structure defines the dimensionality of the rVariables in the CDF. Although there are four rVariables, the array dimensions and the sizes of those dimensions are determined only by Longitude and Latitude. Temperature varies across the entire array while Time tells us how many records to expect. Therefore, the example, when reduced as described, defines a CDF with 2-dimensional rVariables. The number of discrete values for each rVariable that defines a dimension generates the size of that dimension. For example, Longitude has two unique values so the dimension defined by Longitude has a size of two.

Record	rVariables
Number	Time	Longitude	Latitude	Temperature
1	0000	-165	+40	20.0
2	0000	-165	+30	21.7
3	0000	-150	+40	19.2
4	0000	-150	+30	20.7
5	0100	-165	+40	18.2
6	0100	-165	+30	19.3
7	0100	-150	+40	22.0
8	0100	-150	+30	19.2
9	0200	-165	+40	19.9
10	0200	-165	+30	19.3
11	0200	-150	+40	19.6
12	0200	-150	+30	19.0
.
.
.
93	2300	-165	+40	21.0
94	2300	-165	+30	19.5
95	2300	-150	+40	18.4
96	2300	-150	+30	22.0

Table 1.1 Example Data Set - "Flat" Representation (0-Dimensional)

Adding another independent rVariable, for instance Pressure, poses no difficulty for the example. Temperature would then be dependent on a specific Longitude, Latitude, and Pressure - a 3-dimensional array structure. In this 3-dimensional example Longitude, Latitude, and Pressure define the number of dimensions for the rVariables in the CDF, where the size of each dimension is determined by the number of discrete values contained in each of those rVariables. Additional dependent rVariables would be stored in the same way as Temperature.

Although conceptually there is a 2-dimensional array structure for each rVariable in each record of the CDF, this would not be an efficient way to store the data. For instance, the time for each record need only be stored once as opposed to being stored four times as shown in each 2-dimensional array (Table 1.2). This problem is circumvented by specifying "variances." For each rVariable there are variances associated with the array dimensions as well as the records. "Record variance" indicates whether or not an rVariable has unique values from record to record in the CDF. Time changes for each record so the record variance for Time is [TRUE]. One could also say that Time is record-variant. Latitude and Longitude repeat their values from record to record so the record variance for each is [false]. Latitude and Longitude are non-record-variant (NRV). The Temperature values change from record to record so they are record-variant. The record variances for this example are shown in Table 1.3.

Record	rVariables
Number	Time	Longitude	Latitude	Temperature

1	0000 – 0000 \| \| 0000 – 0000	-165 – -150 \| \| -165 – -150	+40 – +40 \| \| +30 – +30	20.0 – 19.2 \| \| 21.7 – 20.7

2	0100 – 0000 \| \| 0000 – 0000	-165 – -150 \| \| -165 – -150	+40 – +40 \| \| +30 – +30	18.2 – 22.0 \| \| 19.3 – 19.2

3	0200 – 0000 \| \| 0000 – 0000	-165 – -150 \| \| -165 – -150	+40 – +40 \| \| +30 – +30	19.9 – 19.6 \| \| 19.3 – 19.0
.
.
.

6	2300 – 0000 \| \| 0000 – 0000	-165 – -150 \| \| -165 – -150	+40 – +40 \| \| +30 – +30	21.0 – 18.4 \| \| 19.5 – 22.0

Table 1.2 Example CDF - 2-Dimensional Representation (Conceptual)

Similarly, the term "dimension variance" indicates whether or not an rVariable changes with respect to the CDF dimensions. In the example above with 2-dimensional rVariables, the Longitude rVariable defines the first dimension of the CDF with its values repeating along the second dimension so its dimension variances would be [TRUE,false]. The Latitude rVariable defines the second dimension of the CDF with its values repeating along the first dimension so its dimension variances would be [false,TRUE]. Because the Temperature values change for each latitude/longitude location, its dimension variances are [TRUE,TRUE]. Time does not change from one latitude/longitude location to another, so its values are the same along both

dimensions. The dimension variances for Time would be [false,false]. The dimension variances for the above example are shown in Table 1.3.

	rVariables
	Time	Longitude	Latitude	Temperature
Record Variance	TRUE	false	false	TRUE
First Dimension Variance	false	TRUE	false	TRUE
Second Dimension Variance	false	false	TRUE	TRUE

Table 1.3 Example CDF - Specification for 2-Dimensional Representation

When the record and dimension variances have been defined correctly, the amount of physical storage needed for the CDF is drastically reduced. In the above example, 2-dimensional arrays are not physically stored

for each rVariable in a CDF record. Instead, the physical storage for each rVariable consists of just one

value for Time in each CDF record, a single 1-dimensional array of values for the Longitude and Latitude rVariables (in only the first CDF record), and a full 2-dimensional array of values for Temperature in each

CDF record. The actual physical storage (physical view) is shown in Table 1.4. The conceptual view of

the CDF, however, is still that of one 2-dimensional array per rVariable in each CDF record as shown in

Table 1.2 (the physically stored values are shown in boldface type).

Record	rVariables
Number	Time	Longitude	Latitude	Temperature

1	0000	-165 – -150	+40 \| +30	20.0 – 19.2 \| \| 21.7 – 20.7

2	0100			18.2 – 22.0 \| \| 19.3 – 19.2

3	0200			19.9 – 19.6 \| \| 19.3 – 19.0
.
.
.

6	2300			21.0 – 18.4 \| \| 19.5 – 22.0

Table 1.4 Example CDF - 2-Dimensional Representation (Physical)

zVariables

zVariables are similar to rVariables in all respects except that each zVariable can have a different dimensionality. This allows any set of variables to be stored in the same CDF without wasting space or creating confusion in how the variables are logically viewed.

Consider a data set that consists of some number of images, each containing 1024 by 1024 pixels. The data set also contains a palette that is used to map pixel values to the actual color/shade to be displayed. Palettes are also referred to as lookup tables or color lookup tables. For this example assume that each image pixel is stored in an 8-bit byte and the palette is a 1-dimensional array of 256 colors/shades. Indexing into the palette array with a pixel value gives the appropriate color/shade to use.

Attempting to store the images and the palette using only rVariables would result in one of two undesirable situations. If the CDF's rVariables had a dimensionality of 2:[1024,1024][8] (to store the images), the palette would have to be stored in a 1024 by 1024 array that does not make sense logically and would waste disk space regardless of how the dimension variances are set. If the CDF's rVariables had a dimensionality of 3:[1024,1024,256], the images could be stored in an rVariable having dimension variances T/TTF[9] and the palette could be stored in an rVariable having dimension variances F/FFT. This would not waste any disk space but is not the intuitive way to store the data - nothing in the data set is 3-dimensional.

Using zVariables to store the images and palette would solve both problems. The images would be stored in a zVariable with dimensionality 2:[1024,1024] (and variances of T/TT) and the palette would be stored in a zVariable with a dimensionality of 1:[256] (and variances of F/T). This would waste no disk space and logically makes sense.

The use of zVariables is recommended because of this added flexibility. Note that zVariables can always be used instead of rVariables. In the rVariable example where temperature values were being stored, zVariables could also have been used. Each zVariable would have the same dimensionality and their dimension variances would be used in the same way as they were used for the rVariables.

An even better example of how zVariables are preferred over rVariables in certain situations involves the storage of 1-dimensional arrays (vectors). Assume that five 1-dimensional arrays are being stored with dimension sizes of 2, 3, 5, 7, and 25. Using rVariables with a dimensionality of 1:[25] would waste considerable space while using rVariables with a dimensionality of 5:[2,3,5,7,25] and dimension variances of T/TFFFF, T/FTFFF, T/FFTFF, T/FFFTF, and T/FFFFT would be quite confusing to deal with zVariables with dimensionalities of 1:[2], 1:[3], 1:[5], 1:[7], and 1:[25] would be straight forward and efficient.

1.6 Attributes

The second component of a CDF is the metadata. Metadata values consist of user-supplied descriptive information about the CDF and the variables in the CDF by way of attributes and attribute entries. Attributes can be divided into two categories: attributes of global scope (gAttributes) and attributes of variable scope (vAttributes). gAttributes describe the CDF as a whole while vAttributes describe some property of each variable (rVariables and zVariables) in the CDF. Any number of attributes may be stored in a single CDF. The term "attribute" is used when describing a property that applies to both gAttributes and vAttributes.

gAttributes can include any information regarding the CDF and all of its variables collectively. Such descriptions could include a title for the CDF, data set documentation, or a CDF modification history. A gAttribute may contain multiple entries (called gEntries). An example of this would be a modification history kept in the optional gAttribute, MODS. This attribute could be specified at CDF creation time and a gEntry made regarding creation date. Any subsequent changes made to the CDF, including additional variables, changes in min/max values, or modifications to variable values could be documented by writing additional gEntries to MODS.

vAttributes further describe the individual variables and their values. Examples of vAttributes would include such things as a field name for the variable, the valid minimum and maximum, the units in which the variable data values are stored, the format in which the data values are to be displayed, a fill value for errant or missing data, and a description of the expected order of data values: increasing or decreasing (monotonicity). The entries of a vAttribute correspond to the variables in the CDF. Each rEntry corresponds to an rVariable and each zEntry corresponds to a zVariable. Sample vAttribute rEntries for the Temperature rVariable from the example above are shown in Table 1.5.

The term "entry" is used when describing a property that applies to gEntries, rEntries, and zEntries.

vAttribute	rEntry value

FIELDNAM	“Recorded temperature”
VALIDMIN	-40.0
VALIDMAX	50.0
SCALEMIN	17.0
SCALEMAX	24.0
UNITS	“deg C”
FORMATS	“F4.1”
MONOTON	“Increasing”
FILLVAL	-999.9

Table 1.5 vAttribute eEntries for the Temperature rVariable

1.7 CDF Toolkit

A set of utility programs are provided with the CDF distribution which allow a user to perform a variety of operations on CDFs without having to write an application program. Each toolkit program is described in detail in Chapter 3.

The available toolkit programs are as follows:

CDFedit[10]

Allows the display, creation, and modification of attribute and variable data in a CDF.

CDFexport[11]

Allows the contents of a CDF to be exported to the terminal screen, a text file, or another CDF. The CDF may be filtered in order to export a subset of its contents.

CDFconvert

Allows the format, encoding, majority, compression, and sparseness of a CDF to be changed. It also can reorganize a fragmented CDF file to make the file access more efficiently. In all cases a new CDF is created. The original CDF is not modified.

SkeletonCDF[12]

Reads a specially formatted text file (called a skeleton table) and creates a skeleton CDF. A skeleton CDF is complete except for record-variant data.

SkeletonTable

Reads a CDF and produces a specially formatted text file called a skeleton table. The skeleton table may be modified and then input to SkeletonCDF to create a skeleton CDF.

CDFinquire

Displays the version of your CDF distribution, many of the configurable parameters, and the default CDF toolkit qualifiers.

CDFstats

Produces a report containing various statistics about the variables in a CDF.

CDFcompare

Reports the differences between two CDFs.

CDFdir

Produces a directory listing of a CDF's files. For a multi-file CDF the variable files are listed in ascending numerical order.

1.8 Library Interface Routines

The core CDF library supports two programming interfaces, the Standard Interface and the Internal Interface. The Standard Interface is similar to the interface provided with Version 1 of CDF with several additions for new features. The Internal Interface is provided to allow additional functionality to be added to the CDF library without the need to modify the Standard Interface. Those features, not available from the Standard Interface, are made available using the Internal Interface (e.g., access to zVariables). The Internal Interface makes CDF extendable. The Standard and Internal interfaces are callable from both C, Fortran, and Perl.

The C and the Fortran interfaces (APIs) are desibed in the CDF C Reference manual and the CDF Fortran reference manual, respectively. The Perl interfaces are described in the Perl to CDF Interfaces document that is included in the CDF Perl distribution package. The C, Fortran, and Java APIs are part of the standard CDF distribution package, but the Perl APIs are available as an optional package. The Java APIs for the Unix[13] and Linux platforms are also available as an optional package. As of this writing, the Java APIs are not available for the VMS operating system.

1.8.1 Standard Interface

The Standard Interface consists of three categories of software functions that are utilized to manipulate the components that make up a CDF: general CDF functions, rVariable functions, and attribute functions.

The general CDF functions are as follows:

Callable from C	Callable from Fortran	Purpose
CDFCreate()	CDF_create()	Creates a new CDF.
CDFopen()	CDF_open()	Opens an existing CDF.
CDFdoc()	CDF_doc()	Inquires version/release and copyright notice.
CDFinquire()	CDF_inquire()	Inquires rVariable dimensionality, etc.
CDFclose()	CDF_close()	Closes a CDF.
CDFdelete()	CDF_delete()	Deletes a CDF.
CDFerror()	CDF_error()	Inquires error (status) code meaning.

The rVariable functions are as follows:

Callable from C	Callable from Fortran	Purpose
CDFvarCreate()	CDF_var_create()	Creates a rVariable.
CDFvarNum()	CDF_var_num()	Determines a rVariable number.
CDFvarRename()	CDF_var_rename()	Renames a rVariable.
CDFvarInquire()	CDF_var_inquire()	Inquires about a rVariable.
CDFvarPut()	CDF_var_put()	Writes a rVariable value.
CDFvarGet()	CDF_var_get()	Reads a rVariable value.
CDFvarHyperPut()	CDF_var_hyper put()	Writes one or more rVariable values.
CDFvarHyperGet()	CDF_var_hyper get()	Reads one or more rVariable values.
CDFvarClose()	CDF_var_close()	Closes a rVariable.
CDFgetrVarsRecordData()	CDF_getrVarsRecordData()	Reads one full record for a group of rVariables.
CDFputrVarsRecordData()	CDF_putrVarsRecordData()	Writes one full record for a group of rVariables

The attribute functions are as follows:

Callable from C	Callable from Fortran	Purpose
CDFattrCreate()	CDF_attr_create()	Creates an attribute.
CDFattrNum()	CDF_attr_num()	Determines an attribute number.
CDFattrRename()	CDF_attr_rename()	Renames an attribute.
CDFattrInquire()	CDF_attr_inquire()	Inquires about an attribute.
CDFattrEntryInquire()	CDF_attr_entry_inquire()	Inquires about an attribute rEntry.
CDFattrPut()	CDF_attr_put()	Writes an attribute rEntry.
CDFattrGet()	CDF_attr_get()	Reads an attribute rEntry.

The Standard Interface may be used to access only rVariables and the vAttribute rEntries for rVariables.

1.8.2 Internal Interface

The Internal Interface consists of one routine: CDFlib when called from C and CDF lib when called from Fortran. The Internal Interface is used to perform all CDF operations. (In reality the Standard Interface is implemented via the Internal Interface.) The Internal Interface is used to add new CDF features (e.g., zVariables) without having to change the Standard Interface.

The Internal Interface must be used to access zVariables and the vAttribute zEntries for zVariables, and it can be used to access rVariables and their attributes. zVariable is a superset of rVariable and the use of zVariable over rVariable is highly recommended.

1.9 CDF Java Interface

The CDF Java Application Programming Interfaces (APIs) are based on the core CDF library's Internal Interface., and they support a near complete set of the Internal Interface functions. The Java APIs only support zVariables and treats rVariables as zVariables. This is not a problem since zVariable is a superset of rVariable. In another words, with zVariables, you can do everything with rVariables and more, but not vice versa.

For a complete description of the Java APIs, please refer to http://nssdc.gsfc.nasa.gov/cdf/cdfjava doc/index.html.

1.10 Examples

In this section, sample programs of how to use the CDF library and toolkit will be presented. The same CDF will be created two different ways: by using just the CDF library from a C program (using stdard interface) and by using the CDF library with the SkeletonTable toolkit program and a Fortran program (using standard interface).

Sample Java programs are also included in Appendix D that describe how to create and read a CDF file using Java APIs. Appendix D also conatins sample C programs that describe how to create variables and add data to them using both the standard interface and the internal interface.

1.10.1 Creating a CDF, the Hard Way (But Not That Hard)

The first example program, written in C, creates a CDF with 2-dimensional rVariables using only CDF library function calls. The CDF created will contain the data and metadata values used in the example presented earlier in this chapter (minus some of the vAttributes/rEntries). An input file, example.dat, whose format is similar to that of Table 1.1 will be read and its data values written into the CDF.

/******************************************************************************

* NSSDC/CDF Create an example CDF (without using a skeleton table).

* Version 1.0, 5-Jan-94, CDF, Inc.

* Modification history:

* V1.0 5-Jan-94, Joe Programmer Original version.

******************************************************************************/

/******************************************************************************

* Note(s):

* This program would have to be modified to run on a DEC Alpha because the

* C language `long' data type is 8 bytes rather than 4 (the CDF data type of

* CDF_INT4 is always 4 bytes).

******************************************************************************/

/******************************************************************************

* Necessary include files.

******************************************************************************/

#include <stdio.h>

#include <stdlib.h>

#include "cdf.h"

/******************************************************************************

* Status handler.

******************************************************************************/

void StatusHandler (status)

CDFstatus status;

{

char message[CDF_ERRTEXT_LEN+1];

if (status < CDF_WARN) {

printf ("An error has occurred, halting...\n");

CDFerror (status, message);

printf ("%s\n", message);

exit (status);

}

else

if (status < CDF_OK) {

printf ("Warning, function may not have completed as expected...\n");

CDFerror (status, message);

printf ("%s\n", message);

}

else

if (status > CDF_OK) {

printf ("Function completed successfully, but be advised that...\n");

CDFerror (status, message);

printf ("%s\n", message);

}

return;

}

/******************************************************************************

* MAIN.

******************************************************************************/

main () {

CDFid id; /* CDF identifier. */

CDFstatus status; /* CDF completion status. */

FILE *fp; /* File pointer - used to read input data file. */

long numDims = 2; /* Number of dimensions, rVariables. */

static long dimSizes[2] = {2,2}; /* Dimension sizes, rVariables. */

long dimVarys[2]; /* Dimension variances. */

long indices[2]; /* Dimension indices. */

long recNum; /* Record number. */

long attrNum; /* Attribute number. */

long TimeVarNum; /* 'Time' rVariable number. */

long LonVarNum; /* 'Longitude' rVariable number. */

long LatVarNum; /* 'Latitude' rVariable number. */

long TmpVarNum; /* 'Temperature' rVariable number. */

long Time; /* 'Time' rVariable value. */

float Lat; /* 'Latitude' rVariable value. */

float Lon; /* 'Longitude' rVariable value. */

float Tmp; /* 'Temperature' rVariable value. */

long TimeValidMin = 0; /* 'Time' valid minimum (0000). */

long TimeValidMax = 2359; /* 'Time' valid maximum (2359). */

float LonValidMin = -180.0; /* 'Longitude' valid minimum. */

float LonValidMax = 180.0; /* 'Longitude' valid maximum. */

float LatValidMin = -90.0; /* 'Latitude' valid minimum. */

float LatValidMax = 90.0; /* 'Latitude' valid maximum. */

float TmpValidMin = -40.0; /* 'Temperature' valid minimum. */

float TmpValidMax = 50.0; /* 'Temperature' valid maximum. */

/****************************************************************************

* Create the CDF.

****************************************************************************/

status = CDFcreate ("example1", numDims, dimSizes, NETWORK_ENCODING,

ROW_MAJOR, &id);

if (status != CDF_OK) StatusHandler (status);

/****************************************************************************

* Create rVariables.

****************************************************************************/

dimVarys[0] = NOVARY;

dimVarys[1] = NOVARY;

status = CDFvarCreate (id, "Time", CDF_INT4, 1L, VARY, dimVarys,

&TimeVarNum);

if (status != CDF_OK) StatusHandler (status);

dimVarys[0] = VARY;

dimVarys[1] = NOVARY;

status = CDFvarCreate (id, "Longitude", CDF_REAL4, 1L, NOVARY, dimVarys,

&LonVarNum);

if (status != CDF_OK) StatusHandler (status);

dimVarys[0] = NOVARY;

dimVarys[1] = VARY;

status = CDFvarCreate (id, "Latitude", CDF_REAL4, 1L, NOVARY, dimVarys,

&LatVarNum);

if (status != CDF_OK) StatusHandler (status);

dimVarys[0] = VARY;

dimVarys[1] = VARY;

status = CDFvarCreate (id, "Temperature", CDF_REAL4, 1L, VARY, dimVarys,

&TmpVarNum);

if (status != CDF_OK) StatusHandler (status);

/****************************************************************************

* Create attributes.

****************************************************************************/

status = CDFattrCreate (id, "TITLE", GLOBAL_SCOPE, &attrNum);

if (status != CDF_OK) StatusHandler (status);

status = CDFattrCreate (id, "VALIDMIN", VARIABLE_SCOPE, &attrNum);

if (status != CDF_OK) StatusHandler (status);

status = CDFattrCreate (id, "VALIDMAX", VARIABLE_SCOPE, &attrNum);

if (status != CDF_OK) StatusHandler (status);

/****************************************************************************

* Write TITLE gAttribute gEntry.

****************************************************************************/

status = CDFattrPut (id, CDFattrNum(id,"TITLE"), 0L, CDF_CHAR, 50L,

"An example CDF (1). ");

if (status != CDF_OK) StatusHandler (status);

/****************************************************************************

* Write vAttribute rEntries for 'Time' rVariable.

****************************************************************************/

status = CDFattrPut (id, CDFattrNum(id,"VALIDMIN"),

CDFvarNum(id,"Time"), CDF_INT4, 1L, &TimeValidMin);

if (status != CDF_OK) StatusHandler (status);

status = CDFattrPut (id, CDFattrNum(id,"VALIDMAX"),

CDFvarNum(id,"Time"), CDF_INT4, 1L, &TimeValidMax);

if (status != CDF_OK) StatusHandler (status);

/****************************************************************************

* Write vAttribute rEntries for 'Longitude' rVariable.

****************************************************************************/

status = CDFattrPut (id, CDFattrNum(id,"VALIDMIN"),

CDFvarNum(id,"Longitude"), CDF_REAL4, 1L, &LonValidMin);

if (status != CDF_OK) StatusHandler (status);

status = CDFattrPut (id, CDFattrNum(id,"VALIDMAX"),

CDFvarNum(id,"Longitude"), CDF_REAL4, 1L, &LonValidMax);

if (status != CDF_OK) StatusHandler (status);

/****************************************************************************

* Write vAttribute rEntries for 'Latitude' rVariable.

****************************************************************************/

status = CDFattrPut (id, CDFattrNum(id,"VALIDMIN"),

CDFvarNum(id,"Latitude"), CDF_REAL4, 1L, &LatValidMin);

if (status != CDF_OK) StatusHandler (status);

status = CDFattrPut (id, CDFattrNum(id,"VALIDMAX"),

CDFvarNum(id,"Latitude"), CDF_REAL4, 1L, &LatValidMax);

if (status != CDF_OK) StatusHandler (status);

/****************************************************************************

* Write vAttribute rEntries for 'Temperature' rVariable.

****************************************************************************/

status = CDFattrPut (id, CDFattrNum(id,"VALIDMIN"),

CDFvarNum(id,"Temperature"), CDF_REAL4, 1L,

&TmpValidMin);

if (status != CDF_OK) StatusHandler (status);

status = CDFattrPut (id, CDFattrNum(id,"VALIDMAX"),

CDFvarNum(id,"Temperature"), CDF_REAL4, 1L,

&TmpValidMax);

if (status != CDF_OK) StatusHandler (status);

/****************************************************************************

* Read input values for rVariables and write them to the CDF. Not

* every value must be written to the CDF - many of the values are redundant.

* The 'Time' value only has to be written once per CDF record (every 4 input

* records). The 'Longitude' and 'Latitude' values are only written to the

* first CDF record (and only at the appropriate indices). Each 'Temperature'

* value read is written to the CDF.

****************************************************************************/

fp = fopen ("example.dat", "r");

if (fp == NULL) {

printf ("Error opening input file.\n");

exit (-1);

}

for (recNum = 0; recNum < 24; recNum++) {

for (indices[0] = 0; indices[0] < 2; indices[0]++) {

for (indices[1] = 0; indices[1] < 2; indices[1]++) {

fscanf (fp, "%d %f %f %f", &Time, &Lon, &Lat, &Tmp);

if (indices[0] == 0 && indices[1] == 0) {

status = CDFvarPut (id, TimeVarNum, recNum, indices, &Time);

if (status != CDF_OK) StatusHandler (status);

}

if (recNum == 0 && indices[1] == 0) {

status = CDFvarPut (id, LonVarNum, recNum, indices, &Lon);

if (status != CDF_OK) StatusHandler (status);

}

if (recNum == 0 && indices[0] == 0) {

status = CDFvarPut (id, LatVarNum, recNum, indices, &Lat);

if (status != CDF_OK) StatusHandler (status);

}

status = CDFvarPut (id, TmpVarNum, recNum, indices, &Tmp);

if (status != CDF_OK) StatusHandler (status);

}

fclose (fp);

/****************************************************************************

* Close CDF.

****************************************************************************/

status = CDFclose (id);

if (status != CDF_OK) StatusHandler (status);

return;

}

1.10.2 Creating a CDF, an Easier Way

The CDF toolkit program SkeletonCDF is provided through the CDF distribution to make the task of creating a CDF easier for a programmer. SkeletonCDF reads a specially formatted text file called a skeleton table and generates a skeleton CDF. Everything about a CDF can be specified in a skeleton table except data values for variables that vary from record to record (record-variant). The toolkit program SkeletonTable is also provided. It reads an existing CDF and produces a skeleton table. The skeleton table for the CDF created using only the CDF library in Section 1.10.1 would be as follows.

! Skeleton table for the "example" CDF.

! Generated: Wed 5 Jan 1994 10:53:58

#header

CDF NAME: example1

DATA ENCODING: NETWORK

MAJORITY: ROW

FORMAT: SINGLE

! Variables G.Attributes V.Attributes Records Dims Sizes

! --------- ------------ ------------ ------- ---- -----

4/0 1 2 1/z 2 2 2

#GLOBALattributes

! Attribute Entry Data

! Name Number Type Value

! --------- ------ ---- -----

"TITLE" 1: CDF_CHAR { "An example CDF (1). " -

" " } .

#VARIABLEattributes

"VALIDMIN"

"VALIDMAX"

#variables

! Variable Data Number Record Dimension

! Name Type Elements Variance Variances

! -------- ---- -------- -------- ---------

"Time" CDF_INT4 1 T F F

! Attribute Data

! Name Type Value

! -------- ---- -----

"VALIDMIN" CDF_INT4 { 0 }

"VALIDMAX" CDF_INT4 { 2359 } .

! Variable Data Number Record Dimension

! Name Type Elements Variance Variances

! -------- ---- -------- -------- ---------

"Longitude" CDF_REAL4 1 F T F

! Attribute Data

! Name Type Value

! -------- ---- -----

"VALIDMIN" CDF_REAL4 { -180.0 }

"VALIDMAX" CDF_REAL4 { 180.0 } .

! NRV values follow...

[ 1, 1 ] = -165.0

[ 2, 1 ] = -150.0

! Variable Data Number Record Dimension

! Name Type Elements Variance Variances

! -------- ---- -------- -------- ---------

"Latitude" CDF_REAL4 1 F F T

! Attribute Data

! Name Type Value

! -------- ---- -----

"VALIDMIN" CDF_REAL4 { -90.0 }

"VALIDMAX" CDF_REAL4 { 90.0 } .

! NRV values follow...

[ 1, 1 ] = 40.0

[ 1, 2 ] = 30.0

! Variable Data Number Record Dimension

! Name Type Elements Variance Variances

! -------- ---- -------- -------- ---------

"Temperature" CDF_REAL4 1 T T T

! Attribute Data

! Name Type Value

! -------- ---- -----

"VALIDMIN" CDF_REAL4 { -40.0 }

"VALIDMAX" CDF_REAL4 { 50.0 } .

#end

Assuming that SkeletonCDF was used to create a CDF containing the metadata and data in the above skeleton table, the following Fortran program would be used to complete the creation of the CDF.

PROGRAM exampleSKT

C----------------------------------------------------------------------------

C NSSDC/CDF Create an example CDF (using skeleton table).

C Version 1.0, 5-Jan-94, CDF, Inc.

C Modification history:

C V1.0 5-Jan-94, Joe Programmer Original version.

C----------------------------------------------------------------------------

INCLUDE '../../include/cdf.inc'

INTEGER*4 id ! CDF identifier.

INTEGER*4 status ! CDF completion status.

INTEGER*4 lun ! Logical unit number for input data file.

INTEGER*4 indices(2) ! Dimension indices.

INTEGER*4 rec_num ! Record number.

INTEGER*4 time_var_num ! 'Time' rVariable number.

INTEGER*4 tmp_var_num ! 'Temperature' rVariable number.

INTEGER*4 time ! 'Time' rVariable value.

REAL*4 lat ! 'Latitude' rVariable value.

REAL*4 lon ! 'Longitude' rVariable value.

REAL*4 tmp ! 'Temperature' rVariable value.

DATA lun/1/

C----------------------------------------------------------------------------

C Open the CDF.

C----------------------------------------------------------------------------

CALL CDF_open ('example2', id, status)

IF (status .NE. CDF_OK) CALL StatusHandler (status)

C----------------------------------------------------------------------------

C Determine rVariable numbers.

C----------------------------------------------------------------------------

time_var_num = CDF_var_num (id, 'Time')

IF (time_var_num .LT. CDF_OK) CALL StatusHandler (status)

tmp_var_num = CDF_var_num (id, 'Temperature')

IF (tmp_var_num .LT. CDF_OK) CALL StatusHandler (status)

C----------------------------------------------------------------------------

C Read input values for rVariables and write them to the CDF. Not

C every value must be written to the CDF - many of the values are redundant.

C The 'Time' value only has to be written once per CDF record (every 4 input

C records). The 'Longitude' and 'Latitude' values are not written at all

C because they had been specified in the skeleton table. Each 'Temperature'

C value read is written to the CDF.

C----------------------------------------------------------------------------

OPEN (lun, FILE='example.dat', ERR=99)

DO rec_num = 1, 24

DO x1 = 1, 2

DO x2 = 1, 2

indices(1) = x1

indices(2) = x2

READ (lun, *, ERR=99) time, lon, lat, tmp

IF (indices(1) .EQ. 1 .AND. indices(2) .EQ. 1) THEN

CALL CDF_var_put (id, time_var_num, rec_num, indices,

. time, status)

IF (status .NE. CDF_OK) CALL StatusHandler (status)

END IF

CALL CDF_var_put (id, tmp_var_num, rec_num, indices,

. tmp, status)

IF (status .NE. CDF_OK) CALL StatusHandler (status)

END DO

CLOSE (lun, ERR=99)

C----------------------------------------------------------------------------

C Close CDF.

C----------------------------------------------------------------------------

CALL CDF_close (id, status)

IF (status .NE. CDF_OK) CALL StatusHandler (status)

STOP

C----------------------------------------------------------------------------

C Input file error handler.

C----------------------------------------------------------------------------

99 WRITE (6,101)

101 FORMAT (' ','Error reading input file')

STOP

END

C----------------------------------------------------------------------------

C Status handler.

C----------------------------------------------------------------------------

SUBROUTINE StatusHandler (status)

INTEGER*4 status

INCLUDE '../../include/cdf.inc'

CHARACTER message*(CDF_ERRTEXT_LEN)

IF (status .LT. CDF_WARN) THEN

WRITE (6,10)

10 FORMAT (' ','Error (halting)...')

CALL CDF_error (status, message)

WRITE (6,11) message

11 FORMAT (' ',A)

STOP

ELSE

IF (status .LT. CDF_OK) THEN

WRITE (6,12)

12 FORMAT (' ','Warning...')

CALL CDF_error (status, message)

WRITE (6,13) message

13 FORMAT (' ',A)

ELSE

IF (status .GT. CDF_OK) THEN

WRITE (6,14)

14 FORMAT (' ','Be advised that...')

CALL CDF_error (status, message)

WRITE (6,15) message

15 FORMAT (' ',A)

END IF

RETURN

END

The CDF was opened (since it already existed) and the values for only the Time and Temperature rVariables were written to the CDF. All of the other functions performed by the program in Section 1.10.1 were done by the SkeletonCDF program when it read the skeleton table.

Chapter 2

Concepts

2.1 CDF Library

The CDF library is the only way to access a CDF. Various properties of the CDF library are described in the following sections.

2.1.1 Interfaces

Two interfaces to the CDF core library exist for C and Fortran programs. They are described in the following sections. For CDF Java Interface, see http://nssdc.gsfc.nasa.gov/cdf/cdfjava doc/index.html for a complete description.

Standard Interface

The Standard Interface provides a standard set of routines with which to access a CDF. Not all CDF features are available with the Standard Interface. The Internal Interface must be used to perform operations not available with the Standard Interface routines (e.g., access to zVariables). The Standard Interface is callable from both C and Fortran applications. Table 2.1 lists the routines available when using the Standard Interface. Each routine is described in detail in the corresponding programmer's guide.

Internal Interface

The Internal Interface may be used to perform all supported CDF operations. The Internal Interface must be used to perform those operations not available with the Standard Interface. Table 2.2 lists the routines available when using the Internal Interface. Each is described in detail in the corresponding programmer's guide.

Callable from C	Callable from Fortran	Purpose
CDFCreate()	CDF_create()	Creates a new CDF.
CDFopen()	CDF_open()	Opens an existing CDF.
CDFdoc()	CDF_doc()	Inquires version/release and copyright notice.
CDFinquire()	CDF_inquire()	Inquires rVariable dimensionality, etc.
CDFclose()	CDF_close()	Closes a CDF.
CDFdelete()	CDF_delete()	Deletes a CDF.
CDFerror()	CDF_error()	Inquires error (status) code meaning.

CDFvarCreate()	CDF_var_create()	Creates a rVariable.
CDFvarNum()	CDF_var_num()	Determines a rVariable number.
CDFvarRename()	CDF_var_rename()	Renames a rVariable.
CDFvarInquire()	CDF_var_inquire()	Inquires about a rVariable.
CDFvarPut()	CDF_var_put()	Writes a rVariable value.
CDFvarGet()	CDF_var_get()	Reads a rVariable value.
CDFvarHyperPut()	CDF_var_hyper_put()	Writes one or more rVariable values.
CDFvarHyperGet()	CDF_var_hyper_get()	Reads one or more rVariable values.
CDFvarClose()	CDF_var_close()	Closes a rVariable.

CDFgetrVarsRecordData()	CDF_getrVarsRecordData()	Reads a full record data for a group of rVariables.
CDFgetzVarsRecordData()	CDF_getzVarsRecordData()	Reads a full record data for a group of zVariables.
CDFputrVarsRecordData()	CDF_putrVarsRecordData()	Writes a full record data for a group of rVariables.
CDFputzVarsRecordData()	CDF_putzVarsRecordData()	Writes a full record data for a group of zVariables.
CDFattrCreate()	CDF_attr_create()	Creates an attribute.
CDFattrNum()	CDF_attr_num()	Determines an attribute number.
CDFattrRename()	CDF_attr_rename()	Renames an attribute.
CDFattrInquire()	CDF_attr_inquire()	Inquires about an attribute.
CDFattrEntryInquire()	CDF_attr_entry inquire()	Inquires about an attribute rEntry.
CDFattrPut()	CDF_attr_put()	Writes an attribute rEntry.
CDFattrGet()	CDF_attr_get()	Reads an attribute rEntry.

Table 2.1 Standard Interface Routines

Callable from C

Callable from Fortran

Purpose

CDFlib()

CDF_lib()

Performs all available operations that can be found in the CDF C and Fortran reference manuals.

Table 2.2 Internal Interface Routines

CDF's IDL Interface

The CDF distribution contains an interface that allows full access to the CDF library (and hence CDFs) from within IDL. CDF's IDL interface consists of a set of functions that mirror the functions in the Standard and Internal interfaces for C and Fortran applications. CDF's IDL interface is described in Appendix B.

IDL also provides its own interface to the CDF library (as well as other data formats) that differs from CDF's IDL interface. The differences are mainly syntactic with the functionality of the two interfaces being essentially the same. IDL's documentation describes their built-in CDF interface. Another difference between the two interfaces is that CDF's IDL interface is only available on those computers that support dynamic linking. Appendix B lists the computers on which this is the case.

2.1.2 CDF Modes

Once a CDF has been opened (or created and not yet closed), the CDF library may be configured to act on that CDF in one or more modes. These modes are specified independently for each open CDF.

Read-Only Mode

A CDF may be placed in read-only mode via the Internal Interface using the <SELECT_,CDF_READONLY_MODE_> operation[14]. Only read access will be allowed on the CDF - all attempts to modify the CDF will fail. A CDF may be toggled in and out of read-only mode any number of times (Note that attempts to modify a CDF may also fail if insufficient access privileges exist for the CDF - the file system enforces this access.)

zMode

A CDF may be placed into zMode[15] via the Internal Interface using the <SELECT_,CDF_zMODE_> operation. When in zMode a CDF's rVariables essentially disappear and are replaced by corresponding zVariables.[16] Likewise, the rEntries for a vAttribute become zEntries (because they are now associated with zVariables). While in zMode most operations involving rVariables/rEntries will fail. (Some inquiry operations will be allowed. For example, inquiring the number of rVariables is allowed [but will always be zero].) When zMode is used, the number of variables remains the same - rVariables simply change into zVariables. Note that the existing contents of the CDF are not changed - the CDF simply appears different.

Each new zVariable has the same exact properties as the corresponding (hidden) rVariable except for dimensionality and variances. The data specification (data type and number of elements), pad value, etc. stay the same. The dimensionality/variances of each zVariable are dependent on which zMode is currently being used: zMode/1 or zMode/2. In zMode/1 the dimensionality/variances stay exactly the same. In zMode/2, however, those dimensions with a false variance (NOVARY) are eliminated. Consider a CDF with an rVariable dimensionality of 2:[180,360][17] containing the following rVariables.

rVariable Name	Variances
EPOCH	T/FF[18]
LATITUDE	T/TF
LONGITUDE	T/FT
HUMIDITY	T/TT

If this CDF were to be placed into zMode/1, the following zVariables would replace the existing rVariables.

rVariable Name	Dimensionality	Variances
EPOCH	2:[180,360]	T/FF
LATITUDE	2:[180,360]	T/TF
LONGITUDE	2:[180,360]	T/FT
HUMIDITY	2:[180,360]	T/TT

Note that the dimensionality of of each zVariable is the same as it was for the rVariables in the CDF. However, if zMode/2 were used, the following zVariables would replace the existing rValues.

rVariable Name	Dimensionality	Variances
EPOCH	0:[]	T/
LATITUDE	1:[180]	T/T
LONGITUDE	1:[360]	T/T
HUMIDITY	2:[180,360]	T/TT

In this case the false dimensional variances were removed (which decreased the dimensionality in several of the variables).

A CDF can be placed into or taken out of zMode any number of times while it is open. Each time the zMode is changed for a CDF, it would be best to think of the CDF as being closed and reopened in that zMode. The numbering of variable/entries may or may not be as you would expect (and the scheme used could change in a future release of CDF). Most applications will simply select a zMode immediately after opening a CDF. (zMode being off is the default if a zMode is not selected.)

NOTE: Using zMode does not change the contents of a CDF. A CDF containing rVariables will appear to contain only zVariables when in zMode. If the same CDF is then opened without using zMode, the rVariables will still exist.

-0.0 to 0.0 Mode

The floating-point value -0.0 is legal on those computers which use the IEEE 754 floating-point representation (e.g., UNIX-based computers, the Macintosh, and the PC) but is illegal on VAXes and DEC Alphas running OpenVMS. Attempting to use -0.0 results in a reserved operand fault on a VAX and a high performance arithmetic fault on a DEC Alpha running OpenVMS. Because of this the CDF library can be told to convert -0.0 to 0.0 when read from or written to a CDF. When reading from a CDF the values physically stored in the CDF are not modified - only the values returned to an application are converted. When writing to a CDF the values physically stored are modified - -0.0 is converted to 0.0 before being written to the CDF. This mode is available on all supported computers but is only really necessary on VAXes and DEC Alphas running OpenVMS. The CDF library is told to convert -0.0 to 0.0 for a CDF via the Internal Interface using the <SELECT_,CDF_NEGtoPOSfp0_MODE_> operation. When this mode is disabled, a warning (NEGATIVE FP ZERO) is returned when -0.0 is read from a CDF (and the decoding is that of a VAX or DEC Alpha running OpenVMS) or written to a CDF (and the encoding is that of a VAX or DEC Alpha running OpenVMS).

2.1.3 Limits

Open CDFs

The only limit on the number of CDFs that may be open simultaneously is the operating system's limit

on the number of open files that an application may have. Each open CDF will always have at least one associated open file (the dotCDF file). The CDF library will open and close the variable files of a multi-file CDF as needed (see Sections 2.3.3 and 2.3.4).

2.1.4 Scratch Files

The CDF library will make use of scratch files when necessary. These scratch files are associated with an open CDF. Scratch files are used instead of core memory in an effort to prevent memory limitation problems (especially on the Macintosh and PC). The following types of scratch files are used.

Staging The staging scratch file is used when a CDF contains compressed variables. As each variable is accessed, a portion of the staging scratch file is allocated to hold a specific number of uncompressed records for that variable. The number of records allocated depends on the variable's blocking factor (see Section 2.3.12). The staging scratch file is also used (when necessary) with variables having sparse records. If the records being written are not first allocated, the staging scratch file will be used to minimize the indexing overhead (see Section 2.2.7) by trying to keep consecutive records contiguous in the dotCDF file.

Compression The compression scratch file is used when writing to a compressed variable in a CDF. Because the CDF library does not know how well a block of variable records will compress, the compression algorithm first writes the compressed block to the compression scratch file. The compressed block is then copied to the dotCDF file. Note that when reading a compressed variable, a compressed block of records is decompressed directly to the staging scratch file because the CDF library knows the size of the uncompressed block of records.

Uncompressed dotCDF When overall compression is specified for a CDF, the CDF library maintains an uncompressed version of the dotCDF file as a scratch file.

By default, these scratch files are created in the current directory. On VMS systems the logical name CDF$TMP can be defined with an alternate directory in which to create scratch files. On UNIX and MS-DOS systems the environment variable CDF TMP would be used. An application can also select a directory to be used for scratch files with the <SELECT_,SCRATCHDIR_> operation of the Internal Interface (which will override a scratch directory specified with CDF$TMP/CDF TMP).

The caching scheme used by the CDF library (see Section 2.1.5) affects how these scratch files can impact performance. On machines with large amounts of core memory available, the cache size of a scratch files can be set high enough to result in no blocks actually being written (paged out) to that file. In that case, the scratch file is more like an allocated block of core memory.

2.1.5 Caching Scheme

The CDF library reads and writes to open files in 512-byte blocks. A cache of 512-byte memory buffers is maintained by the CDF library for each open file. The CDF library attempts to keep in the cache the set of file blocks currently being accessed. This results in fewer actual I/O operations to the file if repeated accesses to these blocks would occur. When the cache is completely full and a new block of the file is accessed, one of the cache buffers is written back to the file (if it was modified) and the new block is read into that cache buffer (unless the file is being extended in which case the cache buffer is simply cleared). This process is known as paging. By optimizing the number of cache buffers for a file, improved performance can be achieved. There is a tradeoff between having too few cache buffers and having too many. Having too few cache buffers will cause excessive paging while having too many cache buffers may slow performance because of the overhead involved in maintaining the cache (although this is very rare). Having too many cache buffers may also cause problems on machines having limited memory such as the PC and Macintosh.

The CDF library attempts to choose optimal default cache sizes based on a CDF's format and the operating system being used. This is difficult because the CDF library does not know how an application will access a CDF. For that reason an application may specify, via the Internal Interface, the number of cache buffers to be used for a file. The number of cache buffers may be changed as many times as necessary while a file is open (the first time will override the default used by the CDF library). Default cache sizes may be configured for your CDF distribution when it is built and installed. Consult your system manager for the values of these defaults (or use the CDFinquire toolkit program).

The situations in which it will be necessary to specify a cache size will depend on how a CDF is accessed. For example, consider a variable in a multi-file, row-major CDF having a dimensionality of 2:[10,64], a data specification of CDF REAL8/1, and variances of T/TT. This variable definition results in each record of the variable being spread across 10 file blocks with the second dimension varying the fastest (since the CDF's variable majority is row-major). If single value reads were used to access this variable (see Section 2.3.16), only one cache buffer would be necessary for the variable file if the second dimension were incremented the fastest (i.e., [1,1], [1,2], …, [10,63], [10,64]). This is because the values of a record would be accessed sequentially from the first block to the last block. If, however, the first dimension were incremented the fastest (i.e., [1,1], [2,1], …, [9,64], [10,64]), 10 cache buffers would improve performance. The values of a record are not being accessed sequentially but rather each read would be from a different block. Since the reads would be spread access 10 blocks, having (at least) 10 cache buffers would be optimal.

A similar situation arises when accessing standard variables in a single-file CDF. If values are accessed for each variable at a particular record number, then performance will be improved by setting the number of cache buffers for the dotCDF file to be equal to (or greater than) the number of variables. This is because the variable values will most likely be located in that many different file blocks for a particular record number.

The Internal Interface is used to select and confirm the cache sizes being used for various files by the CDF library. Confirming a cache size (if it has not been explicitly selected) will determine the default being used. The operations used for each type of file are shown in Table 2.3.

NOTE: The default cache sizes used by the CDF library are fairly conservative in order to minimize the

problems that can arise due to memory limitations (especially on computers having limited memory such as the PC and Macintosh). If the performance of your application is critical, it is very important to experiment with using larger cache sizes. Significant gains in performance can be achieved with the proper cache sizes. It is also important to allocate records for uncompressed variables. This will reduce the fragmentation that can occur in the dotCDF file (which degrades performance because of the increased indexing that occurs). Allocating variable records is described in Section 2.3.12.

File type	Selecting	Confirming
dotCDF file[19]	<SELECT_,CDF_CACHESIZE_>	<CONFIRM_,CDF_CACHESIZE_>
rVariable file	<SELECT_,rVAR_CACHESIZE_>	<CONFIRM_,rVAR_CACHESIZE_>
All rVariable files	<SELECT_,rVARs_CACHESIZE_>	<CONFIRM_,rVARs_CACHESIZE_>
zVariable file	<SELECT_,zVAR_CACHESIZE_>	<CONFIRM_,zVAR_CACHESIZE_>
All zVariable files	<SELECT_,zVARs_CACHESIZE_>	<CONFIRM_,zVARs_CACHESIZE_>
Staging scratch file	<SELECT_,STAGE_CACHESIZE_>	<CONFIRM_,STAGE_CACHESIZE_>
Compression scratch file	<SELECT_,COMPRESS_CACHESIZE_>	<CONFIRM_,COMPRESS_CACHESIZE_>

Table 2.3 Cache Size Operations, Internal Interface

2.2 CDFs

The following sections describe various aspects of a CDF.

2.2.1 Accessing

Only Version 2 CDFs may be accessed with the current CDF distribution. Version 1 CDFs must be converted to Version 2 CDFs using the CDFconvert program in a CDF distribution prior to CDF V2.5 before they will be readable.

All supported CDF operations are available using the Internal Interface. A subset of these operations are available using the Standard Interface. The Obsolete Interface is no longer supported. (Applications written for CDF Version 1 must be ported to the Standard or Internal Interface of CDF Version 2.)

2.2.2 Creating

A CDF must be created by the CDF library. In a C application CDFs are created using either the CDFcreate function (Standard Interface) or the <CREATE_, CDF_> operation of the CDFlib function (Internal Interface). In a Fortran application CDFs are created using either the CDF create subroutine (Standard Interface) or the <CREATE_, CDF_> operation of the CDF lib function (Internal Interface).

2.2.3 Opening

An application must open an existing CDF before access to that CDF is allowed by the CDF library. In a C application CDFs are opened using either the CDFopen function (Standard Interface) or the <OPEN_,CDF_> operation of the CDFlib function (Internal Interface). In a Fortran application CDFs are opened using either the CDF open subroutine (Standard Interface) or the <OPEN_, CDF_> operation of the CDF lib function (Internal Interface).

2.2.4 Closing

It is absolutely essential that a CDF that has been created or modified by an application be closed before the program exits. If the CDF is not closed it will in most cases be corrupted and unreadable. This is because the cache buffers maintained by the CDF library will not have been written to the CDF file(s). An existing CDF that has been opened and only read from should also be closed. In a C application CDFs are closed using either the CDFclose function (Standard Interface) or the <CLOSE_,CDF_> operation of the CDFlib function (Internal Interface). In a Fortran application CDFs are closed using either the CDF close subroutine (Standard Interface) or the <CLOSE_,CDF_> operation of the CDF lib function (Internal Interface).

2.2.5 Deleting

An open CDF may be deleted at any time. The dotCDF file is deleted along with any variable files if a multi- file CDF. Note that if the CDF is corrupted and cannot be opened by the CDF library you will have to delete the CDF file(s) manually using the capabilities of the operating system being used. In a C application CDFs are deleted using either the CDFdelete function (Standard Interface) or the <DELETE_,CDF_> operation of the CDFlib function (Internal Interface). In a Fortran application CDFs are deleted using either the CDF delete subroutine (Standard Interface) or the <DELETE_,CDF_> operation of the CDF lib function (Internal Interface).

2.2.6 Naming

The file name specified when opening or creating a CDF can be any legal file name for the operating system being used. This includes logical symbols on VMS systems and environment variables on UNIX systems. Trailing blanks are also allowed but will be ignored. This is so Fortran applications do not have to be concerned with the trailing blanks of a Fortran CHARACTER variable. (C character strings use terminating NUL characters.)

In almost all cases when a CDF file name is specified, the .cdf extension should not be appended.[20] (It will be appended automatically by the CDF library.) The exception to this is when a user has renamed an existing CDF with a different extension or with no extension (for whatever reason). When a CDF is opened, the CDF library first appends the .cdf extension to the file name specified and then checks to see if that file exists.[21] If not, the CDF library will also check to see if a file exists whose file name is exactly as specified (without .cdf appended). If this is the case, the CDF must be single-file. If the CDF is multi-file, an error occurs since the CDF library would have no idea as to how the variable files had been renamed. Note also that the CDF library always appends .cdf to the file name specified when creating a CDF.

NOTE: The CDF toolkit programs will in some cases not recognize a CDF if it does not have an extension

of .cdf.[22]

2.2.7 Format

There are two CDF formats: multi-file and single-file. The choice of which format to use will depend on how the CDF is to be accessed. Note that the CDFconvert toolkit program can be used to change the format of an existing CDF (creating a new CDF with the desired format).

The default format for a created CDF was determined when your CDF distribution was built and installed. Consult your system manager for this default. In a user application, the Internal Interface must be used to change the format of a CDF. The format of an existing CDF can be changed only if no variables have been created in the CDF. If the SkeletonCDF toolkit program is used to create a CDF, the format is specified in the skeleton table (see Section 3.8).

A CDF's format is changed by using the <PUT_,CDF_FORMAT_> operation of the Internal Interface.

Single-File CDFs

A single-file CDF (SINGLE FILE) consists of only one file (with extension .cdf). This file is referred to as the dotCDF file. The dotCDF file contains the control information for the entire CDF, the attribute entry data, and all of the variable data. An indexing scheme is used to provide efficient access to variable records.

Indexing Scheme. In single-file CDFs an indexing scheme is used to keep track of where a variable's records are located within the dotCDF file. The order that variable (and attribute entry) values are written to a single-file CDF by an application may result in a variable's records being noncontiguous. There will be blocks of contiguous records, but these blocks will not be contiguous in the dotCDF file.

For each variable in a single-file CDF one or more index records will exist. Each of these index records will contain one or more index entries. Because the indexing scheme is now hierarchical,[23] each index entry will point to either another index record (at a lower level in the hierarchy) or to a block of contiguous variable records (at the lowest level of the hierarchy). An index entry consists of the following fields:

FirstRecord The number of the first record in a block of contiguous variable records or the first record indexed in a lower-level index record.

LastRecord The number of the last record in a block of contiguous variable records or the last record indexed in a lower-level index record.

ByteOffset The byte offset within the dotCDF file of the block of contiguous variable records or the byte offset of a lower-level index record.

To find a particular variable record the CDF library must search through the index entries for that variable. Improved performance will result if there are fewer index entries to search. This can be achieved by having a larger number of records in each block of contiguous variable records (resulting in fewer overall index entries). Techniques used to achieve fewer index entries are outlined in the Allocated Records and Blocking Factor descriptions in Section 2.3.12.

It is possible to inquire the indexing statistics for a variable. Using the Internal Interface, an application may inquire the number of indexing levels in the hierarchy, the number of index records, and total number of entries for a variable using the <GET_,r/zVAR_nINDEXLEVELS_>,[24] <GET_,r/zVAR_nINDEXRECORDS_>, and <GET_,r/zVAR_nINDEXENTRIES_> operations.

Multi-File CDFs

A multi-file CDF (MULTI FILE) consists of one file (with extension .cdf referred to as the dotCDF file) containing control information and attribute entry data and a separate file for each variable defined in the CDF (with extensions .v0,.v1, ... for rVariables and .z0,.z1, ... for zVariables). Each variable file contains the data values for the corresponding variable. (The control information for each variable is stored in the dotCDF file.)

Performance

The most efficient access to CDF variables will usually occur when the CDF has the multi-file format. The extra overhead involved with the indexing scheme used in single-file CDFs is small, so the difference may not be significant (especially if hyper reads/writes are used). The drawback to using the multi-file format is that more than one file is associated with a CDF (which may or may not be a problem for your system management).

There is a case in which the single-file format may be more efficient. If a CDF has a large number of variables (larger than the number of files that may be open at once by an application) and the variables values are accessed variable-by-variable (rather than accessing an entire variable before going to the next variable), the multi-file format may be much slower than the single-file format. This is because the CDF library will have to close one variable file and then open another as each variable value is accessed by the application (since the operating system's open file limit will be reached). If the application was to access every value for a variable before going on to the next variable, this would not occur (but it might create complications for the application).

Note that the format of a CDF can also be converted using the CDFconvert toolkit program (which creates a new CDF with the specified format). Section 3.4 describes CDFconvert.

2.2.8 Encoding

The encoding of a CDF determines how attribute entry data and variable data values are stored on disk in the CDF file(s). An application program never has to concern itself with the encoding of the CDF being accessed. The CDF library performs all of the encoding and decoding of data values for the application.

A CDF's encoding is specified when the CDF is created when using the Standard Interface but is set to the default encoding for your CDF distribution when created using the Internal Interface. The encoding of an existing CDF may be changed with the Internal Interface if no variable values or attribute entries have been written (variables and attributes may exist, however). If the SkeletonCDF toolkit program is used to create a CDF the encoding is specified in the skeleton table (see Section 3.8).

The encoding specified when creating/modifying a CDF may be any of the native encodings for the computers supported by CDF in addition to network (XDR) encoding.[25] A CDF with any supported encoding is also readable on any computer supported by CDF.

Host Encodings

Host encoding (HOST_ENCODING) specifies that variable and attribute entry data values be written to the CDF in the native encoding of the computer being used. In addition, the following explicit host encodings are supported:

VAX_ENCODING VAX and microVAX computers. Double-precision floating-point values are encoded in Digital's D FLOAT representation.

ALPHAVMSd_ENCODING DEC Alpha computers running OpenVMS. Double-precision floating-point values are encoded in Digital's D FLOAT representation.

ALPHAVMSg_ENCODING DEC Alpha computers running OpenVMS. Double-precision floating-point values are encoded in Digital's G FLOAT representation.

ALPHAVMSi_ENCODING DEC Alpha computers running OpenVMS. Double-precision floating-point values are encoded in IEEE representation.

ALPHAOSF1_ENCODING DEC Alpha computers running OSF/1.

SUN_ENCODING Sun computers.

SGi_ENCODING Silicon Graphics Iris and Power Series computers.

DECSTATION_ENCODING DECstation computers.

IBMRS_ENCODING IBM RS6000 series computers.

HP_ENCODING HP 9000 series computers.

PC_ENCODING PC personal computers.

NeXT_ENCODING NeXT computers.

MAC_ENCODING Macintosh computers.

When HOST_ENCODING is specified, it is translated to the actual host encoding from the above list. All host encodings are readable and writeable on any machine supported by CDF.

Network Encoding

Network encoding (NETWORK_ENCODING) specifies that variable and attribute entry data values be written to the CDF in the XDR (External Data Representation) format. As values are written to the CDF, the CDF library encodes them into network encoding. Network encoded CDFs are readable and writeable on any machine supported by CDF (as are all of the other encodings).

Equivalent Encodings

While an encoding exists for each supported computer, not every encoding is different. The following sections describe which computers use the same encoding for the various data types.

Character/1-Byte Integer Data Types Since each supported computer uses the ASCII character set and orders the bits in a byte the same way, the character and 1-byte integer data types (CDF CHAR, CDF UCHAR, CDF BYTE, CDF INT1, and CDF UINT1) are encoded in the same way on each.

Multiple-Byte Integer Data Types The multiple-byte integer data types (CDF INT2, CDF UINT2, CDF INT4, and CDF UINT4) are encoded in one of two ways: big-Endian or little-Endian. Big-Endian has the least significant byte (LSB) in the highest memory location while little-Endian has the LSB in the lowest memory location. The supported computers use big-Endian or little-Endian as shown in Table 2.4. Network (XDR) encoding uses big-Endian encoding for multiple-byte integer data types.

Big-Endian	Little-Endian
Sun	VAX
SGi Iris	DECstation
IBM RS6000	PC
HP 9000	DEC Alpha (OSF/1)
NeXT	DEC Alpha (OpenVMS)
Macintosh
(Network - XDR)

Table 2.4 Equivalent Byte Orderings

Single-Precision Floating-Point Data Types The single-precision floating-point encodings on the supported computers are either IEEE 754 floating-point or Digital's F FLOAT floating-point. There are also two different byte orderings for the computers that use IEEE 754 (big-Endian and little-Endian). The single-precision floating-point encodings for each supported computer are shown in Table 2.5. Network (XDR) encoding uses IEEE 754 (big-Endian) encoding for single-precision floating-point data types.

IEEE 754 (Big Endian)	IEEE 754 (Little Endian)	Digital's F FLOAT
Sun	DECstation	VAX
SGi Iris	DEC Alpha (OSF/1)	DEC Alpha / OpenVMS/D
IBM RS6000	DEC Alpha (OpenVMS/I)	DEC Alpha / OpenVMS/G
HP 9000
NeXT
Macintosh
(Network - XDR)

Table 2.5 Equivalent Single-Precision Floating-Point Encodings

Double-Precision Floating-Point Data Types The double-precision floating-point encodings on the supported computers are either IEEE 754 floating-point, Digital's D FLOAT floating-point, or Digital's G FLOAT floating-point. There are also two different byte orderings for the computers that use IEEE 754 (big-Endian and little-Endian). The double-precision floating-point encodings for each supported computer are shown in Table 2.6. Network (XDR) encoding uses IEEE 754 (big-Endian) encoding for double-precision floating-point data types.

IEEE 754 (Big Endian)	IEEE 754 (Little Endian)
Sun	DECstation
SGi Iris	PC
IBM RS6000	DEC Alpha/OSF/1
HP 9000	DEC Alpha/OpenVMS/I
NeXT
Macintosh
(Network - XDR)

Digital's D FLOAT	Digital's G FLOAT
VAX	DEC Alpha/OpenVMS/G
DEC Alpha/OpenVMS/D

Table 2.6 Equivalent Double-Precision Floating-Point Encodings

Performance

The best performance when accessing (reading or writing) a CDF will occur when that CDF is in the host encoding of the computer being used (and host decoding is in effect - see Section 2.2.9). This is because no encoding or decoding has to be performed by the CDF library. A CDF that must be portable between two or more different types of computers should normally be network encoded. There may be cases, however, where it would be desirable to create a CDF with host encoding (e.g., on a slow machine) and then transfer it to a faster machine for processing or conversion to another encoding. Obviously, there are trade-offs as to which encoding should be used in any one particular case. Keep in mind that a CDF can always be converted to the host encoding of the machine being used (with CDFconvert) before being accessed.

2.2.9 Decoding

The decoding of a CDF determines how attribute entry and variable data values are passed to a calling application program from the CDF library. The default decoding when a CDF is initially opened is host decoding (the native encoding of the computer being used). When host decoding is in effect, all data values read by an application are immediately ready for manipulation and display. Almost all of your applications will simply use the default of host decoding and not be concerned with selecting a decoding. There are some situations, however, where selecting a different decoding will be advantageous. Some possibilities are as follows:

1. A client/server model where a number of CDFs are maintained on a server computer (in any of the supported encodings). Clients on different type computers could request data from a CDF on the server computer. The server computer would then select a decoding for the CDF based on the client's computer type and then read the data value(s). The value(s) could then be sent directly to the client computer by the server computer without a conversion being necessary by either the client or the server. The CDF library would perform the necessary conversions.

2. If data values were being read from a CDF and written in binary form to a file for use on a different type computer. The proper decoding could be selected for the CDF before any of the data values are read. No conversions would be necessary by the application program.

A CDF's decoding may be selected and reselected at any time after the CDF has been opened and as many times as necessary. A CDF's decoding is selected via the Internal Interface with the <SELECT_,CDF_DECODING_> operation. Also, a CDF's decoding does not affect the values that already exist in a CDF or any values subsequently written. A CDF's encoding determines how the values are written to the CDF file(s). Section 2.2.8 describes a CDF's encoding.

The supported decodings correspond to the supported encodings. They are as follows:

HOST_DECODING The data representation of the host computer. This is the default.

NETWORK_DECODING The External Data Representation (XDR).

VAX_DECODING VAX and microVAX data representation. Double-precision floating-point values will be in Digital's D FLOAT representation.

ALPHAVMSd_DECODING DEC Alpha running OpenVMS data representation. Double-precision floating- point values will be in Digital's D FLOAT representation.

ALPHAVMSg_DECODING DEC Alpha running OpenVMS data representation. Double-precision floating- point values will be in Digital's G FLOAT representation.

ALPHAVMSi_DECODING DEC Alpha running OpenVMS data representation. Double-precision floating- point values will be in IEEE representation.

ALPHAOSF1_DECODING DEC Alpha running OSF/1 data representation.

SUN_DECODING Sun data representation.

SGi_DECODING Silicon Graphics Iris and Power Series data representation.

DECSTATION_DECODING DECstation data representation.

IBMRS_DECODING IBM RS6000 series data representation.

HP_DECODING HP 9000 series data representation.

PC_DECODING PC data representation.

NeXT_DECODING NeXT data representation.

MAC_DECODING Macintosh data representation

Performance

The best performance when reading a CDF will occur when the CDF's decoding is the same as the CDF's encoding since no conversion will have to be performed by the CDF library. Since host decoding is the only directly usable decoding by an application, CDFs with the host's encoding will provide the best performance. Care should be taken when selecting the encoding for a CDF.

2.2.10 Compression

A compression may be specified for a single-file CDF that is performed when the CDF is closed and written to disk.[26] This compression applies to the overall CDF - individual variables may instead be compressed as described in Section 2.3.14. When compression is specified for a CDF, the CDF library maintains an uncompressed version of the dotCDF file in a scratch file. When the CDF is closed, the uncompressed dotCDF file is compressed and written to the file with the name specified when the CDF was opened/created. If the application program closing the CDF were to abnormally terminate before the dotCDF file was successfully compressed and written, the uncompressed dotCDF scratch file would remain in the scratch directory. The scratch directory used by the CDF library is described in Section 2.1.4.

Overall compression for a CDF is specified with the <PUT_,CDF_COMPRESSION_> operation of the Internal Interface. It may be respecified as often as desired. A CDF's overall compression may be inquired using

the <GET_,CDF_COMPRESSION_> operation for an open CDF and the <GET_,CDF_INFO_> operation for a CDF

that has not been opened (which saves the overhead of actually decompressing the CDF). The available compression algorithms are described in Section 2.6.

2.2.11 Limits

Limits within a CDF are defined in the appropriate include files: cdf.h for C applications and cdf.inc for Fortran applications. The following limits exist:[27]

CDF_MAX_DIMS The maximum number of dimensions that rVariables/zVariables may have.

CDF_VAR_NAME_LEN The maximum number of characters in a variable name.

CDF_ATTR_NAME_LEN The maximum number of characters in an attribute name.

CDF_PATHNAME_LEN The maximum number of characters in the name of a file used to specify a CDF.

Most of these limits can be raised. Contact CDF User Support if that becomes necessary.

2.3 Variables

CDF variables are the mechanism for storing data. (Attributes are used to store metadata.) A new variable may be created in a CDF at any time. Two varieties of variables are supported: rVariables and zVariables.[28] The main difference is that all rVariables in a CDF have the same dimensionality whereas zVariables can have differing dimensionalities. In the following sections the differences between the two varieties will be noted where appropriate.

2.3.1 Types

With the introduction of compression and sparseness for variables, there now exist several different types of variables (in addition to the distinction between rVariables and zVariables). The various types of variables are as follows. . .

"standard variable" A variable in a single-file CDF that is not compressed nor has sparse records or arrays.

"compressed variable" A variable in a single-file CDF that is compressed and may or may not have sparse records (but cannot have sparse arrays).

"variable with sparse records" A variable in a single-file CDF that has sparse records and may be compressed, have sparse arrays, or have neither.

"variable with sparse arrays" A variable in a single-file CDF that has sparse arrays and may or may not have sparse records (but cannot be compressed).

"multi-file variable" A variable in a multi-file CDF. It cannot be compressed, have sparse records, or have sparse arrays.

The term "variable" is used when a discussing a property that applies to all of the various variable types.

2.3.2 Accessing

The Standard Interface deals exclusively with rVariables. No access to zVariables is provided. The Internal Interface may be used to access either rVariables or zVariables.

2.3.3 Opening

The CDF library automatically opens the variable files in a multi-file CDF as the variables are accessed. An application never has to concern itself with opening variables. The opening of variables does not apply to single-file CDFs since individual files do not exist for each variable.

2.3.4 Closing.

The CDF library automatically closes the variable files in a multi-file CDF when the CDF itself is closed by an application.[29] Variable files are also closed automatically by the CDF library as other variables are accessed if insufficient file pointers exist to keep all of the variables open at once This would be due to an open file quota enforced by the operating system being used.

A case also exists where it may be beneficial for an application to close a variable in a multi-file CDF. Since each open variable file uses some number of cache buffers, a large amount of system memory could be in use (see Section 2.1.5). This may not be a problem on VAX or UNIX machines but could result in a program crashing on an MS-DOS machine. If memory is limited, an application may want to close variables after they have been accessed in order to minimize the total number of cache buffers being used. In a C application rVariables are closed using either the CDFvarClose function (Standard Interface) or the <CLOSE_,rVAR_> operation of the CDFlib function (Internal Interface). zVariables are closed using the <CLOSE_,zVAR_> operation of the CDFlib function (Internal Interface). In a Fortran application rVariables are closed using either the CDF var close subroutine (Standard Interface) or the <CLOSE_,rVAR_> operation of the CDF lib function (Internal Interface). zVariables are closed using the <CLOSE_,zVAR_> operation of the CDF lib function (Internal Interface).

The closing of variables does not apply to single-file CDFs since individual files do not exist for each variable.

2.3.5 Naming

Each variable in a CDF has a unique name. This applies to rVariables and zVariables together (i.e., an rVariable cannot have the same name as a zVariable). Variable names are case sensitive regardless of the operating system being used and may consist of up to CDF VAR NAME LEN printable characters (including blanks). Trailing blanks, however, are ignored when the CDF library compares variable names. "LAT" and "LAT " are considered to be the same name, so they cannot both exist in the same CDF. This was done because Version 1 of CDF padded variable names on the right with blanks out to eight characters. When a Version 1 CDF was converted to a Version 2 CDF these trailing blanks remained in the variable names. To allow CDF Version 2 applications to read such a CDF without having to be concerned with the trailing blanks, the trailing blanks are ignored by the CDF library when comparing variable names. The trailing blanks are returned as part of the name, however, when a variable is inquired by an application program.

2.3.6 Numbering

The rVariables in a CDF are numbered consecutively starting at one (1) for Fortran applications and starting at zero (0) for C applications. Likewise, the zVariables in a CDF are numbered consecutively starting at one (1) for Fortran applications and starting at zero (0) for C applications. The CDF library assigns variable numbers as the variables are created.

2.3.7 Deleting

A variable may be deleted from a single-file CDF.[30] Deleting a variable also causes the deletion of the corresponding attribute entries for the variable. The disk space used by the variable definition, the variable's data records, and the corresponding attribute entries becomes available for use as needed by the CDF library. Also, the variables which numerically follow the variable being deleted are renumbered immediately. (Each is decremented by one.) Variables are deleted using the <DELETE_, r/zVAR_> operation of the Internal Interface.

2.3.8 Dimensionality

Variable values are stored in arrays. A variable's dimensionality refers to the number of dimensions and the dimension sizes of these arrays.

Each rVariable in a CDF has the same dimensionality. An array of values exists for each rVariable at each record in a CDF. The values may not be physically stored but may be virtual (see Sections 2.3.12, 2.3.10, and 2.3.11).

A zVariable may have a dimensionality which is different from that of the rVariables and the other zVariables. An array of values exists for each zVariable at each record in a CDF. As with rVariables the values may not be physically stored but may be virtual. zVariables are intended for use in those situations where using an rVariable would waste disk space or not logically make sense.

A variable array having two or more dimensions also contains subarrays. For instance, in a 3-dimensional array with dimension sizes [10,20,30], each array consists of ten 2-dimensional subarrays of size [20,30], and each of those 2-dimensional subarrays consists of twenty 1-dimensional subarrays of size [30]. Subarrays will be referred to when discussing other properties of CDF variables.

2.3.9 Data Specification

Each variable in a CDF has a defined data specification. A variable's data specification consists of a data type and a number of elements of that data type. A variable's data specification is specified when the variable

is created. The data specification of an existing variable may also be changed if either of the following conditions is true.

1. Values have not yet been written to the variable (including an explicitly written pad value - see Section 2.3.20).

2. The old data type and new data type are considered equivalent, and the number of elements for the variable are the same. Equivalent data types are described in Section 2.5.5.

Data Type

The supported data types are described in Section 2.5. Variables having any combination of data types may exist in the same CDF.

Number of Elements

In addition to a data type, each variable also has a number of elements. This refers to the number of elements of the data type at each variable value. For character data types (CDF CHAR and CDF UCHAR) this is the number of characters in each string. (A variable value consists of the entire character string.) The character string can be thought of as an array of characters. For non-character data types, this must always be one (1). An array of elements per variable value is not allowed for non-character data types.

2.3.10 Record Variance

A variable's record variance specifies whether or not the variable's values change from record to record. The effect of a variable's record variance is defined as follows.

VARY The values do change from record to record. Each variable record is physically written with no gaps between records (i.e., if a record more than one beyond the maximum record is written, the intervening records are also physically written and contain pad values). If a record is read beyond the maximum record written to a variable, the pad value for the variable is returned. Variables of this type are referred to as record-variant (RV).

NOVARY The values do not change from record to record. Only one record is physically written to the variable. Each record contains the same values (including virtual records beyond the first record). Variables of this type are referred to as non-record-variant (NRV).

Section 2.3.12 describes variable records in more detail.

A variable's record variance is specified when the variable is created. The record variance of an existing variable may be changed only if values have not yet been written to that variable. (An explicit pad value may have been specified however.)

2.3.11 Dimension Variance

A variable's dimension variances specify whether or not the values change along the corresponding dimension. The effects of a dimension variance are defined as follows:

VARY The values do change along the dimension. All of the values for the dimension (or all of the subarrays) are physically stored.

NOVARY The values do not change along the dimension. Only one value (or subarray) is physically written for that dimension. Each value (or subarray) along that dimension is the same (including virtual values/subarrays beyond the first value/subarray).

Figure 2.1 illustrates the effect of dimension variances on a variable with 2-dimensional arrays (for a particular record). For variable 1 each value in the array is physically stored and therefore unique. Because variable does not vary along the second dimension, each value along that dimension is the same so only one value for that dimension is physically stored (the other values are virtual). The same is true for variable 3 which does not vary along the first dimension. Variable 4 does not vary along either dimension. Only one value is physically stored for the array - all of the other values are the same (they are virtual).

A variable's dimension variances are specified when the variable is created. The dimension variances of an existing variable may be changed only if values have not yet been written to that variable. (An explicit pad value may have been specified, however.)

Figure 2.1 Physical vs. Virtual Dimensions

2.3.12 Records.

A CDF record is a set of variable arrays, one per rVariable and one per zVariable in the CDF. The variable arrays in a particular record are generally related to each other in some way (often time). This does not have to be the case and is not enforced by the CDF library in any way. A variable record is simply the corresponding variable array within a CDF record.

Physical variable records are actually stored in the CDF file(s). Virtual variable records are not actually stored but do exist in the conceptual view of the variable provided by CDF. Virtual records can occur in a CDF because of the following reasons:

1. If a variable's values do not vary from record to record (record variance of NOVARY), all of that variable's records beyond the first one are virtual and have the same values as the first record (only the first record is physically stored). If a record has not yet been written to that variable, then all of its records are virtual and contain the pad value for that variable.

2. If a variable's values do vary from record to record (record variance of VARY), then the records beyond the last record actually written are virtual and contain the pad value for that variable.

3. If a variable has sparse records, then any unwritten records for that variable are virtual and contain either the pad value for that variable or the previous existing record's values (depending on the type of sparse records). Sparse records are described on page 48.

Record variance is described in Section 2.3.10. Variable pad values are described in Section 2.3.20.

The maximum record written is maintained by the CDF library for each variable in the CDF. The "maximum CDF record" is simply the maximum rVariable record written (of all the rVariables). This quantity is available through the Standard Interface when inquiring about a CDF. Because the Standard Interface does not allow access to zVariables, zVariables are not considered when determining the "maximum CDF record." The "maximum CDF record" would be used by applications dealing only with rVariables. The maximum record written for each rVariable and zVariable is available via the Internal Interface.

Figure 2.2 illustrates the relationships between physical and virtual records for a standard variable. Variable 1 has five records that were physically written. Only two records were physically written to variable 2 so the following records are virtual (containing the pad value for that variable). Only one record can be physically written to variable 3 because its record variance is NOVARY. The other records are virtual and contain the same values as the first record. Because a record has not been physically written to variable 4, all of its records are virtual containing the pad value for that variable. Likewise, since no records have been written to variable 5, all of its records are also virtual and contain the pad value for that variable.

Figure 2.2 Physical vs. Virtual Records, Standard Variable

Note that a variable's records do not have to be written sequentially starting at the first record. The records may be written in any order. For a variable not having sparse records with a VARY record variance, if a new record more than one record beyond the current maximum record for the variable is written, the intervening records will be physically written and contain the pad value for that variable. For a variable having sparse records, only those records written by an application are physically stored. Unwritten records are virtual as described in Sparse Records on 48.

Also, when one or more values are written to a new physical record, the entire record is physically written with the pad value for the variable being used for the unspecified values (if any). The remaining values in the record may or may not be subsequently written. Variable pad values are described in Section 2.3.20.

Numbering

The record numbers in a CDF are numbered starting at one (1) for Fortran applications and starting at zero (0) for C applications.

Sparse Records

A variable in a single-file CDF can be specified as having sparse records.[31] If so, then only those records that are explicitly written to the variable will be physically stored. If a variable is not specified as having sparse records, then all of the records up to the maximum written will be physically stored. Sparse records are only allowed in single-file CDFs (where the indexing scheme used for variable records makes this possible). Considerable disk space can be saved in the dotCDF file for a variable that has gaps of missing data if that variable is specified as having sparse records.

For an uncompressed variable having sparse records, it is also beneficial if the blocks of records that are going to be written can first be allocated. This will allow the CDF library to optimize the indexing for the variable. Otherwise, the CDF library will use the staging scratch file to minimize the indexing needed. Note that records cannot be allocated for compressed variables (whether or not they have sparse records).

Two types of sparse records can be specified for a variable. They differ only in how unwritten records are presented in the conceptual view of the variable. These missing records are considered virtual records just like the records beyond the last record written. Pad-missing sparse records specifies that when a virtual record is read the variable's pad value should be returned. Previous-missing sparse records specifies that when a virtual record is read the previous existing record's values should be returned. If a previous record does not exist, the variable's pad value will be returned.

Note that previous-missing sparse records can also be used to save disk space for a variable if that variable's values do not change from record to record except occasionally. If the only records written were those that changed from the previous record, then the virtual records following each record actually written (physically stored) would all have the same value(s). This could save considerable disk space if the values do not change often. For example, consider a 0-dimensional variable having previous-missing sparse records that is being used to store temperature data. Each record corresponds to a temperature reading at a given time. Table 2.7 shows how the variable might appear conceptually along with which records are physically stored. Note that only three records are physically stored but that nine records appear in the conceptual view of the variable.

Sparse records are specified for a variable using the <PUT_,r/zVAR_SPARSERECORDS_> operation of the Internal Interface. One of the following types of sparse records must be specified:

NO_SPARSERECORDS The variable does not have sparse records.

PAD SPARSERECORDS The variable has pad-missing sparse records. The notation sRecords.PAD is used by the CDF toolkit for pad-missing sparse records.

PREV SPARSERECORDS The variable has previous-missing sparse records. The notation sRecords.PREV is used by the CDF toolkit for previous-missing sparse records.

Record	Temperature
1	101.4	(Physical)
2	101.4	(Virtual)
3	101.5	(Physical)
4	101.5	(Virtual)
5	101.5	(Virtual)
6	101.5	(Virtual)
7	101.5	(Virtual)
8	101.6	(Physical)
9	101.6	(Virtual)

Table 2.7 Previous-missing Sparse Records Example, Conceptual View vs. Physical Storage

The <GET_,r/zVAR_SPARSERECORDS_> operation can be used to inquire the type of sparse records.

Allocated Records.

The Internal Interface may be used to allocate records for an uncompressed variable in a single-file CDF[32] Normally the number of records allocated would be the number that are to be written (assuming this can be determined). This can greatly improve performance when writing (and reading) values for the variable because of reduced overhead when searching the index entries (as described in Section 2.2.7). The application is normally expected to write to all of the allocated records. For NRV variables, only one record may be allocated (because only one record will ever physically exist). If the variable has sparse records, only those blocks of records that are going to be written would be allocated. Records cannot be allocated by an application for compressed variables because they are allocated automatically by the CDF library when their compressed size is known.

Performance is improved when using this method because the allocated records will be as contiguous as possible requiring the fewest number of index entries. This will greatly improve the time needed to locate a particular record when the variable is accessed. In addition, the CDF will be slightly smaller because of the reduced number of index records.

Note that records do not have to be allocated by an application before they are written to a variable. The CDF library will automatically allocate any needed records based on the variable's blocking factor. Also, records may be allocated at any time (not only before records have been written as in previous CDF releases).

Records are allocated using the <PUT_,r/zVAR_ALLOCATERECS_> and <PUT_,r/zVAR_ALLOCATEBLOCK_> operations of the Internal Interface. The number of records allocated for a variable can be inquired using the <GET_,r/zVAR_NUMallocRECS_> operation. The maximum record allocated for a variable can be inquired using the <GET_,r/zVAR_MAXallocREC_> operation. The exact records allocated for a variable can be determined using a combination of the <GET_,r/zVAR_ALLOCATEDTO_> and <GET_,r/zVAR_ALLOCATEDFROM_> operations.

Initial Records

The Internal Interface may be used to specify an initial number of records to be written for a variable.[33] The pad value for the variable is written at each record as if the application had done so itself. The Internal Interface allows this to be done more conveniently with only one function call. Note that the default pad value for the variable's data type will be used unless a pad value is explicitly specified for the variable. If a specific pad value is desired for a variable, then it must be specified before the number of initial records is specified. Also, any compression or sparseness for the variable must be specified before writing the initial records because those properties cannot be changed after records have been written.

Specifying a number of initial records for a variable would usually be done only for a CDF with the single-file format. Because the records would be allocated as contiguously as possible within the CDF file, the indexing scheme (see Section 2.2.7) would require fewer entries making the access to that variable more efficient. Note that this method is not as efficient as allocating records in those cases where all of the records are going to be written by the application. This is because the records would be written twice - once with the pad value and then again by the application.

The number of initial records specified would in most cases be the number of records planned for a variable. Note that additional records may be added to a variable at any time. For NRV variables the number of

initial records must always be specified as one (1). This is because only one physical record will ever actually be written. Initial records for a variable may be specified only once.

Initial records are written to variables using the <PUT_,r/zVAR_INITIALRECS_> operation of the Internal Interface. Explicit pad values are specified using the <PUT_,r/zVAR_PADVALUE_> operation.

Blocking Factor.

A variable's blocking factor[34] affects how records are allocated in the CDF file(s). For NRV variables the blocking factor is not applicable because only one physical record will ever exist. For variables in a multi-file CDF the blocking factor is not used because only those records written by an application will exist in the variable files. But for the other types of variables in a single-file CDF the blocking factor can have a significant impact. The following sections will describe how a variable's blocking factor is used in each case.

Standard Variables Space in the dotCDF file for records written to a standard variable is either allocated explicitly by an application or automatically by the CDF library. If the records are allocated by the application the exact number needed can be specified. This can be used to optimize the indexing for the variable resulting in fewer (or even just one) index entries that must be searched when accessing the variable. If the records are not allocated by the application, however, they must be automatically allocated by the CDF library. Because the CDF library wants to optimize the indexing for a variable, it may allocate additional records beyond those needed at the time in an attempt to minimize the number of index entries. The variable's blocking factor specifies the minimum number of records to allocate when an application writes to an unallocated record. This is based on the assumption that the addition records allocated will eventually be written. If that is not the case, the allocated but unwritten records will simply waste space in the dotCDF file. The best way to prevent that situation is for an application to explicitly allocate the records that are going to be written. An application can specify a blocking factor for a variable or let the CDF library use a default blocking factor. Note that setting the blocking factor too low (and not allocating the records being written) may result in excessive indexing for a variable. Even using the default blocking factor for a variable may result in excessive indexing unless the records to be written are first allocated. The indexing scheme used by the CDF library is described in Section 2.2.7.

Compressed Variables The blocking factor for compressed variables specifies the number of records that will be compressed together. The CDF library stages the records of a compressed variable in a scratch file. The number of records in the staging area is also based on the variable's blocking factor. When necessary, the CDF library compresses the records in the staging area and writes the compressed block of records to the dotCDF file. Each block of compressed records has an associated index entry (see Section 2.2.7). Setting the blocking factor high will minimize the indexing for a variable but will increase the time needed to access an individual record because the entire block in which it is compressed will have to be decompressed. If the blocking factor is too low, the decompression of an individual record will not take as long but excessive indexing may result (which will increase the access overhead). Also, most compression algorithms work better as the number of records (bytes) being compressed is increased. Note that if the compressed variable also has sparse records, the blocking factor becomes the maximum number of records per compressed block. Depending on which records are written some of the compressed blocks may contain fewer records. The blocking factor for a compressed variable may be explicitly specified by an application or a default may be used as determined by the CDF library. Once a record has been written to the variable, however, the blocking factor cannot be changed.

Uncompressed Variables With Sparse Records The CDF library uses a staging area scratch file for uncompressed variables with sparse records. This is done in an attempt to minimize the indexing for the variable (as described in Section 2.2.7) when the records being written are not first allocated by an application. The blocking factor specifies the number of records to be maintained in the staging area for the variable (which will be the maximum number of unallocated consecutive records that would be stored contiguously in a block when written by an application). An explicit blocking factor can be specified or a default determined by the CDF library may be used.

Blocking factors are explicitly specified for variables using the <PUT_,r/zVAR_BLOCKINGFACTOR_> operation of the Internal Interface. The blocking factor may be inquired using the <GET_,r/zVAR_BLOCKINGFACTOR_> operation. If an explicit blocking factor has not been specified, the default blocking factor for the variable will be returned.

Note the distinction between records allocated and records actually written. The CDF library may allocate more records than are actually written by an application for the reasons stated above. Both the number of records written to a variable and the number of records allocated for that variable may be inquired using the Internal Interface.

Deleting

The records of a variable in a single-file CDF may be deleted.[35] If the variable has sparse records, the deleted records simply cease to exist. A gap of one or more missing records will be formed. But if the variable does not have sparse records, the records following the block of deleted records are immediately renumbered to fill in the gap created. The record numbers remain consecutive without a gap.

Variable records are deleted using the <DELETE_,r/zVAR_RECORDS_> operation of the Internal Interface.

2.3.13 Sparse Arrays

Sparse arrays are planned for a future release of CDF. The idea being that only those values actually written to a variable array (record) will be physically stored. Currently, unwritten values in each variable array are physically stored using the variable's pad value. Note that specifying a compression for a variable will in many cases result in a disk space savings similar to that of sparse arrays. The exact differences in disk space savings and execution overhead between sparse arrays and variable compression will not be known until sparse arrays have been implemented.

2.3.14 Compression

A compression may be specified for a variable in a single-file CDF which gets performed automatically as values are written.[36] The values are transparently decompressed as they are read from the variable. The values of a variable are compressed in blocks of one or more variable records. The blocking factor for a compressed variable (described beginning on page 50) specifies the number of records in each block (or the maximum number in the case of a compressed variable with sparse records). Properly setting the blocking factor involves a trade-off between the compression percentage achieved and execution speed when accessing values in individual variable records. The CDF library also uses a staging area scratch file to minimize access overhead for a compressed variable. Note that if a block of variable records actually increases in size when compressed, the block of records will be stored uncompressed in the CDF. This could happen if the blocking factor is set too low or simply because of the nature of the data and the compression algorithm being used.

The compression for a variable is specified with the <PUT_,r/zVAR_COMPRESSION_> operation of the internal interface. A variable's compression may be inquired with the <GET_,r/zVAR_COMPRESSION_> operation. Section 2.6 describes the available compression algorithms.

Reserve Percentage.

If a value in a compressed block of records is changed, the amount of compression achieved for that block may also change. If it increases, the block of compressed records may have to be moved in the dotCDF file. This will most likely result in the dotCDF file increasing in size if the block of compressed records is placed at the end (leaving a block of unused bytes where the compressed block of records previously existed). This is not a desirable situation considering that the variable compression is supposed to make the CDF smaller. To alleviate this potential problem a reserve percentage may be selected for a compressed variable. When a compressed block of variable records is initially written to the dotCDF file some additional space will be allocated. This will allow that block of compressed records to expand in size if necessary. The reserve percentage is interpreted as follows:

0 No reserve space is allocated. This is the default.

1..100 Allocates that percentage of the uncompressed size of the block of variable records (as a minimum). For example, if a 1000-byte block of records compressed down to 600 bytes and the reserve percentage is 70%, then 700 bytes would actually be allocated for the block in the dotCDF file. If the reserve percentage is 50%, then 600 bytes would of course still have to be allocated.

101… Allocates that percentage of the size of the compressed block of variable records but not exceeding the uncompressed size. For example, if a 1000- byte block of records compressed down to 800 bytes and the reserve per- centage is 110%, then 880 bytes would be allocated for the block.

Even specifying a reserve percentage for a compressed variable does not guarantee that the problem with moving blocks of compressed records as the variable's values are changed will be avoided. If a CDF does become fragmented in this way remember that the CDFconvert utility can always be used to create a new CDF with each variable's compression being optimized (e.g., no fragmentation).

The reserve percentage for a compressed variable is selected with the <SELECT_,r/zVAR_RESERVEPERCENT_> operation. A variable's reserve percentage may be confirmed with the <CONFIRM_,r/zVAR_RESERVEPERCENT_> operation.

2.3.15 Majority

The variable majority of a CDF describes how variable values within each variable array (record) are stored. Each variable in a CDF has the same majority. The majority can be either row major or column major.

ROW MAJOR Row majority. The first dimension changes the slowest.

COLUMN MAJOR Column majority. The first dimension changes the fastest.

For example, an array for an rVariable with [VARY,VARY] dimension variances in a 2-dimensional CDF with dimension sizes [2,4] and row majority would be stored as follows:

v(1,1), v(1,2), v(1,3), v(1,4), v(2,1), v(2,2), v(2,3), v(2,4)

where v(i,j) is the value at indices (i,j). If the CDF had column majority, the array would be stored as follows:

v(1,1), v(2,1), v(1,2), v(2,2), v(1,3), v(2,3), v(1,4), v(2,4)

In each case v(1,1) is stored at the low address.

An application needs to be concerned with the majority of a CDF in the following cases:

1. When performing a variable hyper read, the values placed in the buffer by the CDF library will be in the variable majority of the CDF. The application must process the values according to that majority.

When performing a variable hyper write, the CDF library expects the values in the buffer to be in the variable majority of the CDF. The application must place the values into the buffer in that majority.

2. When sequential access is used, the values are read/written in the order imposed by the variable majority of the CDF.

3. When single value reads/writes are performed, the majority could have an effect. The CDF library uses a caching scheme to optimize[37] the random access to variable values. If all of the values of a record are to be read/written, there may be an increase in performance if the values are accessed with (rather than against) the majority. For example, if the majority is row-major, increment the last index the fastest.

4. When performing a multiple variable read/write, the full-physical records in the buffer will/must be in the variable majority of the CDF.

A CDF's variable majority is specified when the CDF is created when using the Standard Interface but is set to the default variable majority for your CDF distribution when created using the Internal Interface. The majority of an existing CDF may be changed using the Internal Interface only if variable values have not yet been written. (Variables may exist and explicit pad values may have been specified, however.)

2.3.16 Single Value Access

Single value access allows only one value to be read from or written to a variable with a single call to the CDF library. Two parameters are specified when performing a single value read/write:

RecordNumber The record number at which to perform the access.

DimensionIndices The indices within the record at which to perform the access.

For 0-dimensional variables, the dimension indices are not applicable.

Single value access is sensitive to the record and dimension variances of a variable. For instance, if a variable has a record variance of NOVARY (with one record written) and a value is read from the fourth record, the CDF library will actually read the value from the first record (the record that is physically stored). If a value were written to the fourth record, the CDF library would actually write the value to the first record (the only record that actually physically exists). If the record variance is VARY, the values are written to the actual records. (The physical records are the same as the virtual records.) The same applies to any dimension variances that are NOVARY. When a set of indices is specified for a single value read/write, the index for a dimension whose variance is NOVARY is forced to the first index regardless of the actual index specified for that dimension (see Section 2.3.11).

In a C application single value access for rVariables is performed using either the CDFvarGet and CDFvarPut functions (Standard Interface) or the <GET_,rVAR_DATA_> and <PUT_,rVAR_DATA_> operations of the CDFlib function (Internal Interface). Single value access for zVariables must be performed using the <GET_,zVAR_DATA_> and <PUT_,zVAR_DATA_> operations of CDFlib. In a Fortran application single value access for rVariables is performed using either the CDF var get and CDF var put subroutines (Standard Interface) or the <GET_,rVAR_DATA_> and <PUT_,rVAR_DATA_> operations of the CDF lib function (Internal Interface). Single value access for zVariables must be performed using the <GET_,zVAR_DATA_> and <PUT_,zVAR_DATA_> operations of CDF lib.

2.3.17 Hyper Access

Hyper access allows more than one value to be read from or written to a variable with a single call to the CDF library. In fact, the entire variable may be accessed at once (if a large enough memory buffer is available to your application). Hyper reads cause the CDF library to read from the variable record(s) in the CDF and place the values into a memory buffer provided by the application. Hyper writes cause the CDF library to take values from a memory buffer provided by the application and write them to the variable records in the CDF. Six parameters are specified when performing a hyper read/write:

RecordNumber The record number at which to start the access.

RecordCount The number of records to access.

RecordInterval The interval between records being accessed. An interval of two (2) would indicate that every other record is to be accessed.

DimensionIndices The indices within each record at which the access should begin.

DimensionCounts The number of values along each dimension that should be accessed.

DimensionIntervals For each dimension, the interval between values being accessed. An interval of three (3) would indicate that every third value is to be accessed.

For 0-dimensional variables, the dimension indices, counts, and intervals are not applicable.

A hyper access may or may not read/write a contiguous set of values stored for a variable in the CDF. However, the values in the memory buffer received/provided by the application are contiguous.

Hyper access is sensitive to the record and dimension variances of a variable. For instance, if a variable has a record variance of NOVARY (with one record written) and a hyper read of the first five records for that variable is requested, the CDF library will read the single record that is physically stored and place it five times (contiguously) into the memory buffer provided by the application. The same applies to any dimension variances that are NOVARY. For example, if the count for a dimension is three and the dimension variance is NOVARY, the one value (or subarray) physically stored will be read by the CDF library and placed into the application's memory buffer three times (contiguously).

Example (Fortran application)

Assume a 2-dimensional variable array with sizes [2,4], row majority, a record variance of VARY, dimension variances of [VARY,VARY], and hyper read parameters as follows:

record number 5

record count 2

record interval 1

dimension indices 1,1

dimension counts 2,4

dimension intervals 1,1

The values placed in the application's buffer would be as follows (with the first value being in low memory):

5(1,1) 5(1,2) 5(1,3) 5(1,4) 5(2,1) 5(2,2) 5(2,3) 5(2,4)

6(1,1) 6(1,2) 6(1,3) 6(1,4) 6(2,1) 6(2,2) 6(2,3) 6(2,4)

where r(i,j) is a physically stored value with r being the record number, i being the first dimension index, and j being the second dimension index. (r, i, and j are physical record numbers and dimension indices.)

If the dimension variances had been [VARY,NOVARY], the values placed in the buffer would have been

5(1,1) 5(1,1) 5(1,1) 5(1,1) 5(2,1) 5(2,1) 5(2,1) 5(2,1)

6(1,1),6(1,1) 6(1,1) 6(1,1) 6(2,1) 6(2,1) 6(2,1) 6(2,1)

If the record count had been 3 and the record interval 2, the values placed in the buffer would have been

5(1,1) 5(1,2) 5(1,3) 5(1,4) 5(2,1) 5(2,2) 5(2,3) 5(2,4)

7(1,1) 7(1,2) 7(1,3) 7(1,4) 7(2,1) 7(2,2) 7(2,3) 7(2,4)

9(1,1) 9(1,2) 9(1,3) 9(1,4) 9(2,1) 9(2,2) 9(2,3) 9(2,4)

If the dimension counts had been [2,2] and the dimension intervals [1,2], the values placed in the buffer would have been

5(1,1) 5(1,3) 5(2,1) 5(2,3)

6(1,1) 6(1,3) 6(2,1) 6(2,3)

If the CDF majority had been column major, the values placed in the buffer would have been.

5(1,1) 5(2,1) 5(1,2) 5(2,2) 5(1,3) 5(2,3) 5(1,4) 5(2,4)

6(1,1) 6(2,1) 6(1,2) 6(2,2) 6(1,3) 6(2,3) 6(1,4) 6(2,4)

Had these examples been for hyper writes, the CDF library would have expected to find the values in the application's buffer exactly as they were placed there during the corresponding hyper read. In the case where the record interval was 2, the records being skipped would be written using the variable's pad value if they did not already exist. If they did already exist, they would not be affected.

In a C application, hyper writes for rVariables are performed using the CDFvarHyperPut function (Standard Interface) or the <PUT_,rVAR_HYPERDATA_> operation of the CDFlib function (Internal Interface). Hyper writes for zVariables must be performed using the <PUT_,zVAR_HYPERDATA_> operation of CDFlib. Hyper reads for rVariables are performed using the CDFvarHyperGet function (Standard Interface) or the

<GET_,rVAR_HYPERDATA_> operation of CDFlib. Hyper reads for zVariables must be performed using the <GET_,zVAR_HYPERDATA_> operation of CDFlib.

In a Fortran application, hyper writes for rVariables are performed using the CDF_var_hyper_put subroutine (Standard Interface) or the <PUT_,rVAR_HYPERDATA_> operation of the CDF lib function (Internal Interface). Hyper writes for zVariables must be performed using the <PUT_,zVAR_HYPERDATA_> operation of CDF lib. Hyper reads for rVariables are performed using the CDF_var_hyper_get subroutine (Standard Interface) or the <GET_,rVAR_HYPERDATA_> operation of CDF lib. Hyper reads for zVariables must be performed using the

<GET_,zVAR_HYPERDATA_> operation of CDF lib.

2.3.18 Sequential Access

Sequential access provides a way to sequentially read/write the values physically stored for a variable. To use sequential access, a starting value must first be selected by specifying a record number and dimension indices. This selects the "current sequential value." A sequential read will return the value at the current sequential value and then automatically increment the current sequential value to the next value. Likewise, a sequential write will store a value at the current sequential value and then increment the current sequential value to the next value. Sequential reads are allowed until the end of the physical records has been reached (not the end of the virtual records [they never end]). Sequential reading will increment to the beginning of the next physical record if necessary. Sequential writing can be used to extend the physical records for a variable (as well as to overwrite existing values).

If the variable has sparse records, the virtual records in a gap of missing records are not skipped. The type of sparse records (see Section 2.3.12) will determine the values returned. When a virtual record in a gap of missing records is read, the informational status code VIRTUAL RECORD DATA is returned (rather than END OF VARIABLE). Sequential writes will create any necessary record in a gap of missing records (i.e., sequential writes do not skip virtual records in a gap of missing records).

Example (Fortran application)

Assume a 2-dimensional array with sizes [2,3], column majority, a record variance of VARY, dimension variances of [VARY,VARY], nine (9) physical records written, and that the current sequential value has been set to record number 7 and indices [2,2]. Consecutive sequential reads would cause the following values to be read and returned to the application:

7(2,2) 7(1,3) 7(2,3)

8(1,1) 8(2,1) 8(1,2) 8(2,2) 8(1,3) 8(2,3)

9(1,1) 9(2,1) 9(1,2) 9(2,2) 9(1,3) 9(2,3)

END_OF_VAR

… where r(i,j) is a physically stored value with r being the record number, i the first dimension index, and j the second dimension index. (r, i, and j are physical record numbers and dimension indices.) The next sequential read after the last physical value would cause a status code indicating the end of the variable to be returned (END OF VAR).

Had the dimension variances been [NOVARY,VARY], the values read would have been

7(1,2) 7(1,3)

8(1,1) 8(1,2) 8(1,3)

9(1,1) 9(1,2) 9(1,3)

END_OF_VAR

Note that specifying the virtual value 7(2,2) as the current sequential value caused physical value 7(1,2) to actually be selected (because the first dimension variance is NOVARY).

Sequential access for variables is performed using the <GET_,r/zVAR_SEQDATA_> and <PUT_,r/zVAR_SEQDATA_> operations of the Internal Interface.

2.3.19 Multiple Variable Access

Multiple variable access allows an application to read from or write to multiple variables in a single operation. Multiple variable access works on either the rVariables or the zVariables of a CDF - not a mixture of the two. Up to all of the rVariables/zVariables may be accessed with a single call to the CDF library. For each variable specified in a multiple variable access, a full-physical record for that variable will be read/written. A full-physical record consists of all of the values exactly as they are physically stored in each variable record (the physical values). Virtual values do not apply when performing a multiple variable access (see Section 2.3.11). Three parameters are specified when performing a multiple variable read/write.

VariableCount The number of rVariables/zVariables that are being accessed.

VariableList The rVariables/zVariables being accessed (specified by number).

RecordNumbers The record numbers at which the reads/writes will take place. For rVariables the record numbers must all be the same. For zVariables the record numbers can vary (but for most applications will all be the same).

Multiple variable access is sensitive to the record variances of the variables being accessed. (Dimension variances do not apply since full-physical records are being read/written.) If a variable has a record variance of NOVARY, then a read/write to that variable will always occur at the first record regardless of the actual record number specified (since at most only one physical record will ever exist). If the record variance were VARY, the reads/writes would take place at the actual record numbers specified.

For a multiple variable write operation an application must place into a memory buffer each of the full- physical records to be written. The order of the full-physical records must correspond to the order of the list of variables specified, and the memory buffer must be contiguous - there can be no gaps between the full-physical records. This memory buffer is then passed to the CDF library which scans through the buffer writing the full-physical records to the corresponding variables.

Likewise, for a multiple variable read operation the CDF library places into a memory buffer provided by the application the full-physical records read. The order of the full-physical records will correspond to the order of the list of variables specified and the full-physical records will be contiguous. The application must then process the buffer as needed.

Care must be used when generating and processing the memory buffer containing the full-physical records. If C struct objects or Fortran STRUCTURE variables are being used, it may be necessary to order the variables being read/written such that there are no gaps between elements of the structures (assuming you are defining structures containing one element per full-physical record where an element is a scalar variable or an array depending on the corresponding variable definition). On some computers the C and Fortran compilers will place gaps between the elements of these structures so that memory alignment errors are not generated when the elements are accessed. In general, defining the structures so that "larger" data types are before "smaller" data types should result in no gaps (e.g., the Fortran REAL*8 data type is "larger" than a INTEGER*2, which is "larger" than a BYTE). The list of variables would be adjusted accordingly.

The variable majority must also be considered when performing a multiple variable read/write since full-physical records are being accessed. The majority of the values in the full-physical records retrieved from/placed into the memory buffer must be the same as the variable majority of the CDF.

For example, consider a column-major CDF containing the following three zVariables (as well as others):

zVariable Name	Data Spcification	Dimensionality	Variances
zVar1	CDF INT2/14[38]	0:[]	T/
zVar2	CDF_CHAR/7	1:[5]	T/T
ZVar3	CDF REAL8/1	2:[2,4]	T/TT

If a Fortran application were to perform a multiple variable read on these three zVariables, it could define a

STRUCTURE to receive the physical records as follows:

STRUCTURE /inputStruct/

REAL*8 zVar3values(2,4)

INTEGER*2 zVar1value

CHARACTER*7 zVar2values(5)

END STRUCTURE

Note that because a full-physical record for the zVariable zVar2 is an odd number of bytes it would most likely cause a gap in the STRUCTURE if not placed at the end (on some computers). An approach that would work on all computers would be to use EQUIVALENCE statements as follows:

INTEGER*2 zVar1value

CHARACTER*7 zVar2values(5)

REAL*8 zVar3values(2,4)

BYTE buffer(101)

EQUIVALENCE (zVar3values,buffer(1))

EQUIVALENCE (zVar1value,buffer(65))

EQUIVALENCE (zVar2values,buffer(67))

The EQUIVALENCE statements ensure that the full-physical records will be contiguous. In each of the above examples, the order of the zVariables would be zVar3, zVar1, zVar2.

C applications must also be concerned with the ordering of full-physical records in the memory buffer. Even if a void memory buffer is used with type casting to access individual values, the alignment of the values in the memory buffer is important (on some computers).

Multiple variable writes are performed using the <PUT_,r/zVARs_RECDATA_> operation of the Internal Interface. Multiple variable reads are performed using the <GET_,r/zVARs_RECDATA_> operation. The selection of record numbers is performed using the <SELECT_,r/zVARs_RECNUMBER_> operation.

2.3.20 Variable Pad Values.

Variable pad[39] values are used in several situations. .

1. When the first value is written to a new record (for records containing multiple values), the other values in that record will contain the pad value. This also applies to hyper writes if less than the entire record is written. The unwritten values will contain the pad value.

2. For a variable not having sparse records, when a new record is written that is more than one record beyond the last record already written, the intervening records will also be written and will contain pad values. This does not apply to NRV variables because only one physical record actually exists.

3. For a variable having the pad-missing style of sparse records (sRecords.PAD), if a record is read from a gap of missing records, pad values will be returned. The previous-missing style of sparse records (sRecords.PREV) would cause the previous existing record's values to be returned (unless there is no previous record in which case pad values would be returned).

4. When reading a record beyond the last record written for a variable, pad values will be returned except if the variable has the previous-missing style of sparse records. In that case, the last written record's values are returned (unless there are no written records in which case pad values are returned).

The pad value for a variable may be specified with the Internal Interface. It should be specified before any values are read from or written to the variable - otherwise the default pad value will be used. The pad value may be changed at any time (and any number of times) and will be in effect for all subsequent operations. The default pad value for each data type are shown in Table 2.8.[40]

Data Type	Default Pad Value
CDF_BYTE	0
CDF_INT1	0
CDF_UINT1	0
CDF_INT2	0
CDF_UINT2	0
CDF_INT4	0
CDF_UINT4	0
CDF_REAL4	0.0
CDF_FLOAT	0.0
CDF_REAL8	0.0
CDF_DOUBLE	0.0
CDF_EPOCH	01-Jan-0000 00:00:00.000
CDF_CHAR	" " (space character)
CDF_UCHAR	" " (space character)

Table 2.8 Default Pad Values.

Variable pad values are specified using the <PUT_,r/zVAR_PADVALUE_> operation of the Internal Interface. The pad value being used for a variable can be inquired with the <GET_,r/zVAR_PADVALUE_> operation. If a pad value has not been explicitly specified for a variable, the default pad value (based on the variable's data type) will be returned along with the NO_PADVALUE_SPECIFIED informational status code. The existence of an explicitly specified pad value can be confirmed for a variable (without actually inquiring the value) using the <CONFIRM_,r/zVAR_PADVALUE_> operation.

2.4 Attributes

CDF attributes are the mechanism for storing metadata. (Variables are used to store data.) A new attribute may be created in a CDF at any time.

2.4.1 Naming

Each attribute in a CDF has a unique name. Attribute names are case sensitive regardless of the operating system being used and may consist of up to CDF_ATTR_NAME_LEN printable characters (including blanks). Trailing blanks, however, are ignored when the CDF library compares attribute names. "UNITS" and "UNITS" are considered to be the same name, so they cannot both exist in the same CDF. This was done because Version 1 of CDF padded attribute names on the right with blanks out to eight characters. When a Version 1 CDF was converted to a Version 2 CDF these trailing blanks remained in the attributes names. To allow CDF Version 2 applications to read such a CDF without having to be concerned with the trailing blanks, the trailing blanks are ignored by the CDF when comparing attributes names. The trailing blanks are returned as part of the name, however, when an attribute is inquired by an application program.

2.4.2 Numbering

The attributes in a CDF are numbered consecutively starting at one (1) for Fortran applications and starting at zero (0) for C applications. The CDF library assigns attribute numbers as the attributes are created. Note that there are not separate lists of global and variable scoped attributes. Only one list of attributes exists in a CDF (containing both global and variable scoped attributes).

2.4.3 Attribute Scopes

Attribute scopes declare the intended purpose of an attribute. Global scope attributes (gAttributes) describe some aspect of the entire CDF. Variable scope attributes (vAttributes) describe some property of each variable.

An attribute's scope exists to assist in the interpretation of its entries by CDF toolkit programs and user applications (e.g., entries of a vAttribute should correspond to variables). The CDF library also places some restrictions on the operations that may be performed on an attribute of a particular scope.[41] These restrictions consist of the following:

1. A gEntry operation may not be performed on a vAttribute.

2. A zEntry or rEntry operation may not be performed on a gAttribute.

3. While in zMode, only zEntry operations may be performed on vAttributes (see Section 2.1.2).

All other operations involving attributes and their entries remain available.

Assumed Scopes

CDF Version 1 did not allow the scope of an attribute to be explicitly declared. This led to ambiguities in the interpretation of attribute entries in the toolkit programs and user applications. CDF Version 2 does allow the scope of an attribute to be declared when the attribute is created. To ease the transition from Version 1 to Version 2, CDF distributions prior to CDF V2.5 contained the notion of assumed attribute scopes. Assumed attribute scopes arose when the CDF library had to guess the scope of an attribute in a Version 1 CDF (e.g., when the CDFconvert program converted a Version 1 CDF to a Version 2 CDF). Beginning withCDF V2.5, all assumed attribute scopes are converted to the corresponding definite scope. When a CDF is read this conversion occurs only in the CDF library - the CDF is not physically altered. When an existing CDF is written to, each assumed attribute scope detected will be physically converted to the corresponding definite scope. Note that if this automatic conversion is incorrect, the scope of an attribute can be corrected using the Internal Interface in an application program or by editing the CDF with the CDFedit program.

2.4.4 Deleting

An attribute may be deleted from a CDF. Deleting an attribute also deletes the corresponding entries. The disk space used by the attribute definition and the corresponding entries becomes available for use as needed by the CDF library. Also, the attributes which numerically follow the attribute being deleted are renumbered immediately. (Each is decremented by one.) Attributes are deleted using the <DELETE_,ATTR_> operation of the Internal Interface.

2.4.5 Attribute Entries

Attribute entries are used to actually store metadata. Each attribute in a CDF may have zero or more associated entries. For vAttributes two types of entries are supported: rEntries and zEntries. rEntries describe some property of the corresponding rVariable, and zEntries describe some property of the corresponding zVariable. Note that an entry does not have to exist for each variable in the CDF. For gAttributes only one type of entry is supported and is referred to as a gEntry. The gEntries are independent of anything else in the CDF and have meaning only to the application. Note that gEntries are sometimes referred to simply as "entries."

Accessing

The Standard Interface deals exclusively with rEntries (for vAttributes) and gEntries (for gAttributes). No access to zEntries is provided. The Internal Interface may be used to access any type of attribute entry.

Numbering

The rEntries and zEntries for a vAttribute and the gEntries for a gAttribute are numbered starting at one (1) for Fortran applications and starting at zero (0) for C applications. For vAttributes the entry numbers are in fact the variable numbers of the variables being described. rEntries correspond to rVariables and zEntries correspond to zVariables. For gAttributes the gEntry numbers have meaning only to the application.

The entry numbers used need not be contiguous (as are variable and attribute numbers). An application may choose to write any combination of entries for a particular attribute (keeping in mind that the entry numbers used for a vAttribute correspond to the existing variables).

Data Specification

Each entry for an attribute has a data specification and an associated value. A data specification consists of a data type and a number of elements of that data type. The supported data types are described in Section 2.5. The entries for an attribute may have any combination of data specifications.

For character data types the number of elements is the number of characters in the string. For example, if a gEntry value for a gAttribute named TITLE were "Example CDF Title." (not including the double quotes), the data type would be CDF_CHAR, and the number of elements would be 18 (a character string of size 18).

For non-character data types the number of elements is the size of an array of the data type. For example, if a zEntry value of a vAttribute named RANGE were [100.0,900.0], the data type would be CDF_REAL4, and the number of elements would be two (an array of two values).

Deleting

An entry may be deleted from an attribute. The disk space used by the entry becomes available for use as needed by the CDF library. There is no renumbering of entries (as with deleting a variable or attribute). Entries are deleted using the <DELETE_,gENTRY_>, <DELETE_,rENTRY_>, and <DELETE_,zENTRY_> operations of the Internal Interface.

2.5 Data Types

CDF supports a variety of data types consistent with the types available with C and Fortran compilers on most computers. All data types are based on an 8-bit byte. The size of an element of a data type is the same regardless of the computer/operating system being used. The <GET_,DATATYPE_SIZE_> operation of the Internal Interface may be used to inquire the size in bytes of a particular data type.

2.5.1 Integer Data Types

CDF_BYTE 1-byte, signed integer.

CDF_INT1 1-byte, signed integer.

CDF_UINT1 1-byte, unsigned integer.

CDF_INT2 2-byte, signed integer.

CDF_UINT2 2-byte, unsigned integer.

CDF_INT4 4-byte, signed integer.

CDF_UINT4 4-byte, unsigned integer.

NOTE: When using C on a DEC Alpha running OSF/1, keep in mind that a long is 8 bytes and that an int is 4 bytes. Use an int with the data types CDF_INT4 and CDF_UINT4 rather than a long.

NOTE: When using C on a PC under MS-DOS, keep in mind that an int is most likely 2 bytes and that a long is 4 bytes. Use a long with the data types CDF_INT4 and CDF_UINT4 rather than an int.

2.5.2 Floating Point Data Types

CDF_REAL4 & CDF_FLOAT 4-byte, single-precision floating-point.

CDF_REAL8 & CDF_DOUBLE 8-byte, double-precision floating-point.

A special case exists with respect to the value -0.0 (negative floating-point zero). This value is legal on those computers that use the IEEE 754 floating-point representation (e.g., most UNIX-based computers and the PC) but is illegal on VAXes and DEC Alphas running OpenVMS. Attempting to use -0.0 will result in a reserved operand fault on a VAX and a high performance arithmetic fault on a DEC Alpha running OpenVMS. A warning is returned whenever -0.0 is read by an application on a VAX or DEC Alpha running OpenVMS. The CDF library can be put into a mode where -0.0 will be converted to 0.0 when detected (see Section 2.1.2). If -0.0 is not being converted to 0.0, the CDF toolkit programs are designed to display -0.0 in all cases. This includes those computers that normally suppress the negative sign.

2.5.3 Character Data Types

CDF_CHAR 1-byte, character.

CDF_UCHAR 1-byte, unsigned character.

Character data types are unique for variables in that they are the only data types for which more than one element per value is allowed. Each variable value consists of a character string with the number of elements being the number of characters. More than one element is allowed for any of the data types when dealing with attribute entries.

2.5.4 EPOCH Data Type

CDF_EPOCH 8-byte, double precision floating point.

The CDF_EPOCH data type is used to store time values referenced from a particular epoch. For NSSDC applications that epoch is 01-Jan-0000 00:00:00.000.[42] CDF_EPOCH values are the number of milliseconds since the epoch. The standard format used to display a CDF_EPOCH value is

dd-mmm-yyyy hh:mm:ss.ccc

where dd is the day of the month (01-31), mmm is the month (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep,

Oct, Nov, or Dec), yyyy is the year (0000-9999) hh is the hour (00-23), mm is the minute (00-59), ss is the

second (00-59), and ccc is the millisecond (000-999).

Functions exist that parse, encode, compute, and decompose CDF_EPOCH values. These functions are described in the CDF C Reference Manual for C applications and in the CDF Fortran Reference Manual for Fortran applications.

2.5.5 Equivalent Data Types

Certain data types are considered equivalent with respect to their representation in memory and in a CDF. Table 2.9 shows the groups of equivalent data types.

CDF_CHAR	CDF_INT2	CDF_INT4	CDF_REAL4	CDF_REAL8
CDF_UCHAR	CDF_UINT2	CDF_UINT4	CDF_FLOAT	CDF_DOUBLE
CDF_INT1				CDF_EPOCH
CDF_UINT1
CDF_BYTE

Table 2.9 Equivalent Data Types

Note that while the signed and unsigned forms of a data type are considered equivalent by the CDF library, they must be correctly interpreted by an application to produce the desired results.

2.6 Compression Algorithms

Several compression algorithms are supported by the CDF library. Selecting the proper algorithm to use will depend on the characteristics of the data being compressed. Experimentation with the available algorithms on the CDF or variable being compressed will also be necessary. The following sections describe each compression algorithm, any associated parameters, and the types of data for which they are appropriate.

2.6.1 Run-Length Encoding

The run-length encoding compression algorithm, RLE_COMPRESSION, takes advantage of repeating bytes in the data. Currently, only the run-length encoding of zeros (0's) is supported. RLE_COMPRESSION has one parameter which must be set to RLE_OF_ZEROs. The notation RLE.0 is used for this type of RLE compression.

2.6.2 Huffman

The Huffman compression algorithm, HUFF_COMPRESSION, takes advantage of the frequency at which certain byte values occur in the data. A sequence of bytes that contain a high percentage of a limited number of byte values will compress better than if each byte value occurs with equal probability. HUFF_COMPRESSION has one parameter which must be set to OPTIMAL_ENCODING_TREES.[43] The notation HUFF.0 is used for this type of HUFF compression.

2.6.3 Adaptive Huffman

The adaptive Huffman compression algorithm, AHUFF_COMPRESSION, also takes advantage of the frequency at which certain byte values occur in the data. AHUFF_COMPRESSION is very similar to HUFF_COMPRESSION and generally provides slightly better compression. AHUFF_COMPRESSION has one parameter which must be set to OPTIMAL_ENCODING_TREES. The notation AHUFF.0 is used for this type of AHUFF compression.

2.6.4 GZIP

The Gnu ZIP compression algorithm, GZIP_COMPRESSION, uses the Lempel-Ziv coding (LZ77) taking advantage of common substrings within the data. Significant compression occurs over a wide variety of data sets.GZIP_COMPRESSION has one parameter which may be set to a level value in the range from 1 (one) to 9 (nine). 1 provides the least amount of compression and executes the fastest. 9 provides the most compression but executes the slowest. Levels between 1 and 9 allow for a trade-off between compression and execution speed. The notation GZIP.<level> is used for GZIP compression where <level> is a value from 1 to 9. For example, GZIP.7 specifies a level of 7.

NOTE: GZIP compression is disabled for PCs running 16-bit DOS/Windows 3.x due to their memory constraint.

Chapter 3

Toolkit Reference

3.1 Introduction

The CDF toolkit is a set of utility programs that allow the creation, analysis, and modification of CDFs. The following sections will describe the use of these programs.

NOTE: Java version of the CDF toolkit[44] is available starting with CDF 2.7, and it is only available for the Unix platform since the CDF toolkit provided for the Window 95/98/NT and Macintosh platforms are already Graphical User Interface (GUI) based programs.

3.1.1 VMS, UNIX & MS-DOS

Each program is executed at the command line (or may be executed from within your applications using the methods provided by the operating system being used). The following rules apply to the command line syntax:

1. Parameters are required unless noted otherwise. Parameters are shown in angle brackets (<>'s) in the sections which describe each toolkit program.

2. Qualifiers are optional unless noted otherwise.

3. Qualifiers can be truncated as long as no ambiguities result.

4. Optional parts of a command are shown in brackets ([]'s) in the sections which describe each toolkit program.

5. A vertical line (|) is used to separate two or more options in those cases when only one of the options may be specified.

6. Wildcard characters are allowed in CDF names to allow more than one CDF to be specified (where appropriate). Wildcard characters may be used in the CDF name but not the directory path portion of a specification. The wildcard characters supported are similar to those available on the operating system being used.

UNIX: If a CDF specification is to contain a wildcard character, the entire specification must be

enclosed in single quote marks (e.g., '/disk3/sst*').

7. On VMS/OpenVMS systems, qualifiers begin with a slash (/). On UNIX and MS-DOS systems, qualifiers begin with a hyphen (-).

NOTE: You can override the default notation by specifying a slash or hyphen as the first parameter/qualifier immediately after the program name. When this is done, you may have to adjust the syntax used as follows:

(a) When the slash notation is used on UNIX systems, character string will be necessary in the file names (e.g., specify "//disk1//CDFs" rather than "/dist1/CDFs"). Also, double quote marks are required around options enclosed in parenthesis.

(b) When the slash notation is used on MS-DOS systems, double quote marks may be needed around entire qualifier/option combinations.

8. On MS-DOS systems the executable names may be different from the names shown in this chapter (file names are limited to 8.3 characters). Where the names differ, the actual name will be noted.

If you add the directory containing the toolkit executables to your path, you will have to use the 8-character (or fewer) names. If you use a command aliasing program, you could specify the aliases to be the names shown in this chapter with each pointing to the corresponding executable file name.

9. On UNIX systems all parameters/qualifiers entered at the command line are case sensitive. On VMS, OpenVMS, and MS-DOS systems parameters/qualifiers are not case sensitive. Note that variable names are always case sensitive regardless of the operating system being used.

10. If an option contains blanks, it will generally be necessary to enclose the entire option in double quote marks.

11. On UNIX systems, it may be necessary to execute "stty tab3" before running CDFedit or CDFexport.

12. Some of the toolkit programs have a "paging" qualifier. Paging is not allowed if the output of the program has been directed to a file.

13. Most toolkit programs have an "about" qualifier that can be used to determine the CDF distribution from which the program came. On the Macintosh, an "about" selection is available on the "apple" pull-down menu.

In the following sections the available qualifiers and options for each of the toolkit programs will be presented. The default settings for these qualifiers and options will not be shown since they can be configured for a particular CDF distribution. Use CDFinquire to determine these defaults.

On VMS/OpenVMS systems you should have executed the command procedure named DEFINITIONS.COM before running any of the CDF toolkit programs. This will define the necessary logical names and symbols. Your system administrator knows the location of DEFINITIONS.COM.

On UNIX systems you should have source'd (or equivalent) the script file named definitions.<shell-type> where <shell-type> is the type of shell you are using: C for the C-shell (csh) and tcsh, K for the Korn (ksh), BASH, and POSIX shells, and B for the Bourne shell (sh). This will define the necessary environment variables and aliases. Your system administrator knows the location of definitions.<shell-type>.

3.1.2 Macintosh

Each toolkit program is started by double-clicking on the appropriate icon. A dialog box will be displayed in which the parameters and qualifiers needed to execute the program are specified. When the parameters/qualifiers have been selected, clicking on Enter causes the initial execution to begin.

For the programs that use a full-screen interface (e.g., CDFedit and CDFexport), a "pasteboard" window is opened in which the program displays menus, prompts, etc. When the "pasteboard" window is closed (by exiting the execution), the parameters/qualifiers dialog box is redisplayed. A new set of parameters/qualifiers may be selected and executed or the program may be terminated.

For the programs that simply output to the screen (e.g., CDFstats, CDFcompare, and CDFinquire), a "standard output" window is opened in which the output will be written. When the execution completes, the "apple" and File menus are available in the menu bar. Under the File menu the following commands are available:

Execute Causes the parameters/qualifiers dialog box to be redisplayed. A new set of parameters/qualifiers may be selected and executed. The output from each execution is appended to the existing output.

Save Saves the current output to a file named <program-name>.so where <program-name> is the name of the program.

Save as... Saves the current output to the file specified in the standard output file dialog box that will be displayed.

Clear Clears the current output.

Quit Terminates the program.

The vertical scroll bar as well as the page up and page down keys may be used to scroll through the output. When a large amount of text has been written, a dialog box may be displayed indicating that an output overow is about to occur. The output may be saved to a file before being cleared (to allow the execution to continue).

The parameters/qualifiers dialog box for each program uses the standard Macintosh controls. Edit fields are used to enter text values (e.g., the file name of a CDF). Leaving an edit field blank is allowed in some cases (which will be noted). Check boxes are used to enable or disable a qualifier. An X in the check box indicates that the qualifier is enabled. Radio buttons are used in groups to allow one of several options to be chosen for a qualifier. Generally, only one of the radio buttons in a group may be selected.

Several types of files are specified to the toolkit programs. These consist of CDFs, skeleton tables, and output files. In a parameters/qualifiers dialog box edit field or a toolkit program's prompt field a file must be specified using a full or partial file name. Full file names consist of a volume name (which is also the corresponding folder name), zero or more folder names, and finally the file name (with or without an extension). These are all separated by semi-colons (:'s). Partial file names do not start with a volume name and may start with or without a semi-colon. If a partial file name starts with a semi-colon, one or more folder names will follow, each separated by a semi-colon, followed by the file name. The first folder must exist in the currently selected folder. If a partial file name starts without a semi-colon, then only a file name should be present and the file is (or will be) located in the currently selected folder. To ease in the selection of files in parameters/qualifiers dialog boxes, the corresponding edit fields are followed by a Select button. When clicked on, a standard input/output file dialog will be displayed in which a file may be specified. When that has been done the file name of the selected file will appear in the edit field.

A directory/wildcard[45] specification is allowed for some of the CDF specifications required by the toolkit programs. This allows more than one of the CDFs in a directory to be selected. If a CDF specification ends with a folder name, then all of the CDFs in that folder will have been specified. A trailing semi-colon is not required (but may be present). The supported wildcard characters are the asterick (*) which matches zero or more characters and the question mark (?) which matches exactly one character.

NOTE: You may find it necessary to increase the partition size available to a toolkit program when dealing with very large CDFs. You can do this by editing the "current size" field of the window opened when using the Get Info item of the File menu (from the Desktop menu bar) on the toolkit executable.

3.1.3 Windows NT/95/98

Two excutable programs (i.e. CDFfsi.exe & CDFso.exe) are provided as part of the standard distribution package, and each program contains the following CDF utilities/tools:

	CDFfsi.exe	CDFso.exe
	CDFedit	CDFcompare
	CDFexport	CDFconvert
		CDFinquire
		CDFdump
		CDFstats
		SkeletonCDF
		SkeletonTable

A CDF utility/tool can be invoked by running CDFfsi.exe or CDFso.exe and selecting the tool listed under the File menu. For example, the SkeletonCDF utility can be invoked by running the CDfso.exe program and then selecting the SkeletonCDF option under the File menu.

3.1.4 Java Version of the CDF Toolkit

Java version of the CDF toolkit is available starting with CDF 2.7. A desired CDF tool can be invoked by typing "java CDFToolsDriver" at the system prompt and selecting the CDF tool with a single click.

Environment variable called CLASSPATH must be set to point to the location (full path name) of the cdftools.jar file that is located under the cdf27-dist/cdfjava/tools jdk1.2 directory. If this environment variable is not set, the "java CDFToolsDriver" command will not work.

3.1.5 Special Attributes

There is a set of vAttributes that have special meaning to some of the CDF toolkit programs.[46] Your CDFs

do not have to use these special attributes. The CDF toolkit programs will function properly whether or not these special attributes are present in a CDF. How the entries of each vAttribute are used for the corresponding variables is as follows:

FORMAT A Fortran or C format specification that is used when displaying a variable value.

VALIDMIN The minimum valid value for a variable.

VALIDMAX The maximum valid value for a variable.

FILLVAL The value used for missing or invalid variable values.[47]

MONOTON The monotonicity of a variable: INCREASE (strictly increasing values), DECREASE (strictly decreasing values), or FALSE (not monotonic). Monotonicity only applies to NRV variables that vary along one dimension and RV variables that vary along no dimensions.

SCALEMIN The minimum value for scaling a variable when graphically displaying its values.

SCALEMAX The maximum value for scaling a variable when graphically displaying its values.In the description of each CDF toolkit program, the special attributes that may affect that program's operation are defined. Note that most of the CDF toolkit programs can be instructed to ignore these special attributes.

3.1.6 Special Qualifier

There is a special qualifier applied to all toolkit programs. This qualifier, as "-about" on all platforms except Macintosh, will show version, release and increment information of the distribution that the toolkit program is based on. This special qualifier, if present, supersedes all other qualifiers and parameters.

3.2 CDFedit

3.2.1 Introduction

The CDFedit program allows the display and/or modification of practically all of the contents of a CDF by way of a full-screen interface. It is also possible to run CDFedit in a browse-only mode in order to prevent accidental modifications.[48]

3.2.2 Special Attribute Usage

The special attribute FORMAT is used by CDFedit (depending on the setting of the "format" qualifier) when displaying variable values.

3.2.3 Executing the CDFedit Program

Usage:

VMS:

$ CDFEDIT [/[NO]BROWSE] [/ZMODE=<mode>] [/[NO]FORMAT] [/[NO]PROMPT]

[/[NO]NEG2POSFP0] [/REPORT=(<types>)] [/CACHE=(<sizes>)]

[/[NO]STATISTICS] [/[NO]GWITHENTRIES] [/[NO]VWITHENTRIES]

<cdf-spec>

UNIX:

% cdfedit [-[no]browse] [-zmode <mode>] [-[no]format] [-[no]prompt]

[-[no]neg2posfp0] [-report "<types>"] [-cache "<sizes>"]

[-[no]statistics] [-[no]gwithentries] [-[no]vwithentries]

<cdf-spec>

MS-DOS:

> cdfedit [-[no]browse] [-zmode <mode>] [-[no]format] [-[no]prompt]

[-[no]neg2posfp0] [-report "<types>"] [-cache "<sizes>"]

[-[no]statistics] [-[no]gwithentries] [-[no]vwithentries]

<cdf-spec>

Macintosh:

Double-click on the CDFedit icon.

Windows NT/95/98:

Double-click on the CDFfsi icon and select the CDFedit option under the File menu.

Java/UNIX:

This option is not yet available in the Java toolkit for Unix.

Macintosh & Windows NT/95/98:

When the desired parameters/qualifiers have been selected in the dialog box, click on the Enter button to begin editing the CDF. Clicking on the Help button will display online help. Clicking on the Quit button terminates CDFedit.

Parameter(s):

<cdf-spec> (VMS, UNIX & MS-DOS)

CDF edit field (Macintosh, Java/UNIX & Windows NT/95/98)

The specification of the CDF(s) to edit. (Do not specify an extension.) This may be either a single CDF file name or a directory/wildcard path. Wildcards are allowed in the CDF name but not in the directory path. If the "prompt" qualifier is used, this will appear as the initial specification at the prompt. If this parameter is omitted, the "prompt" qualifier must be specified (and the initial specification at the prompt will be the default/current directory).

Macintosh & Windows NT/95/98: At the end of the CDF edit field, a button labeled Select is present. When selected, a standard input file dialog is displayed from which a single CDF may be selected. Also present is a button labeled New. When selected, a standard output file dialog is displayed in which a single CDF may be specified.

Qualifier(s):

/[NO]BROWSE (VMS)

-[no]browse (UNIX & MS-DOS)

Browse only check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not a browsing mode is desired. In browsing mode the creation, modification, or deletion of a CDF is not allowed.

/ZMODE=<mode> (VMS)

-zmode <mode> (UNIX & MS-DOS)

zMode radio buttons (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies which zMode should be used. The zMode may be one of the following:

0 Indicates that zMode should be disabled.

1 Indicates that zMode/1 should be used. The dimension variances of rVariables will be preserved.

2 Indicates that zMode/2 should be used. The dimensions of rVariables having a variance of NOVARY [false] are removed.

/[NO]FORMAT (VMS)

-[no]format (UNIX & MS-DOS)

Use FORMAT check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not the FORMAT attribute is used when displaying variable values (if the

FORMAT attribute exists and an entry exists for the variable).

/[NO]PROMPT (VMS)

-[no]prompt (UNIX & MS-DOS)

Prompt for CDF check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not a prompt is issued for the CDF(s) specification. When enabled the prompt will be issued both at program startup and after editing the current CDF(s) specification (at which point a new CDF[s] specification may be specified).

VMS, UNIX & MS-DOS: If a CDF(s) specification was entered on the command line, that CDF(s) specification will appear at the prompt. (Otherwise, the current/default directory will appear at the prompt.)

Macintosh, Java/UNIX & Windows NT/95/98: If a CDF(s) specification was entered in

the CDF edit field, that CDF(s) specification will appear at the prompt. (Otherwise, the current directory will appear at the prompt.)

/[NO]NEG2POSFP0 (VMS)

-[no]neg2posfp0 (UNIX & MS-DOS)

-0.0 to 0.0 check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not -0.0 is converted to 0.0 by the CDF library when encountered in a CDF. -0.0 is an illegal floating point value on VAXes and DEC Alphas running OpenVMS.

/REPORT=(<types>) (VMS)

-report "<types>" (UNIX & MS-DOS)

Report info's/warnings/errors check boxes (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies the types of return status codes from the CDF library that should be reported/displayed. The <types> option is a comma-separated list of zero or more of the following symbols: errors, warnings, or informationals. Note that these symbols can be truncated (e.g., e, w, and i).

/CACHE=(<sizes>) (VMS)

-cache "<sizes>" (UNIX & MS-DOS)

Cache sizes edit field (Macintosh & Java/UNIX)

Cache edit field (Windows NT/95/98)

Specifies the cache sizes to be used by the CDF library for the dotCDF file and the various scratch files. The <sizes> option is a comma-separated list of <size><type> pairs where <size> is a cache size and <type> is the type of file as follows: d for the dotCDF file, s for the staging scratch file, and c for the compression scratch file. For example, 200d,100s specifies a cache size of 200 for the dotCDF file and a cache size of 100 for the staging scratch file. The dotCDF file cache size can also be specified without the d file type for compatibility with older CDF releases (e.g., 200,100s). Note that not all of the file types must be specified. Those not specified will receive a default cache size chosen by the CDF library. A cache size is the number of 512-byte buffers to be used. Section 2.1.5 explains the caching scheme used by the CDF library.

/[NO]STATISTICS (VMS)

-[no]statistics (UNIX & MS-DOS)

Display statistics check box (Macintosh & Java/UNIX)

Caching statistics check box (Windows NT/95/98)

Specifies whether or not caching statistics are displayed when a CDF is closed.

/[NO]GWITHENTRIES (VMS)

-[no]gwithentries (UNIX & MS-DOS)

gEntries with gAttributes check box (Macintosh & Java/UNIX)

with gEntries check box (Windows NT/95/98)

Specifies whether or not gEntries are displayed with the gAttributes or on separate menus (with one menu per gAttribute).

/[NO]VWITHENTRIES (VMS)

-[no]vwithentries (UNIX & MS-DOS)

rEntries/zEntries with vAttributes check box (Macintosh & Java/UNIX)

with r/zEntries check box (Windows NT/95/98)

Specifies whether or not rEntries/zEntries are displayed with the vAttributes or on separate menus (with one menu per vAttribute).

Example(s):

VMS:

$ CDFEDIT [.SAMPLES]

$ CDFEDIT/ZMODE=2/NOFORMAT/CACHE=(10D,100S,200C) GISS_WETLX

$ CDFEDIT/BROWSE/PROMPT/REPORT=(ERRORS)

UNIX:

% cdfedit samples

% cdfedit -zmode 2 -noformat -cache "10d,100s,200c" giss_wetl

% cdfedit -browse -prompt -report "errors"

MS-DOS:

> cdfedit samples

> cdfedit -zmode 2 -noformat -cache "10d,100s,200c" giss_wetl_> cdfedit -browse -prompt -report "errors"

3.2.4 Interaction with CDFedit

Interaction with CDFedit is through a series of menus and windows. Extensive online help is provided and will not be repeated here.[49] The online help does refer to the sections of a window by name. Figure 3.1 illustrates the various sections of the possible types of windows.

Figure 3.1 Window Sections, CDFedit

ItemWindows are used when a choice is to be made from a list of one or more items (e.g., functions to perform, CDFs to edit, variable names, etc.). In some cases the entire list of items may not fit on the screen at once. When this occurs, the ItemSection may be scrolled to display hidden items. Some ItemWindows have a percentage indicator at the bottom right portion of the ItemSection. The percentage indicator shows which part of the ItemSection is being displayed.

PromptWindows are used when a textual response is required (e.g., a CDF specification, a new attribute name, a variable value, etc.). If the text is too long to fit into the PromptField, the "more" indicators ("<" and ">") at the left and right ends of the PromptField will display where hidden characters exist.

EditWindows are used to display/edit a text file or group of lines. EditWindows are currently used to display online help and to edit gAttribute character string entries as if they were a text file.

3.3 CDFexport

3.3.1 Introduction

CDFexport allows the contents of a CDF to be exported to the terminal screen, a text file, or another CDF. The variables to be exported can be selected along with a filter range for each variable which allows a subset of the CDF to be generated. When exporting to another CDF, a new compression and sparseness can be specified for each variable. When exporting to the terminal screen or a text file, the format of the output can be tailored as necessary.

3.3.2 Special Attribute Usage

CDFexport uses the following special attributes:

FORMAT Used as the initial value in a variable's Format field.

VALIDMIN Used as the initial filter value in a variable's Minimum field.

VALIDMAX Used as the initial filter value in a variable's Maximum field.

FILLVAL Used as the initial value in a variable's FillValue field.

MONOTON Used as the initial setting in a variable's Monotonicity field.

These fields are described in the online help for the appropriate menu. The values of these fields can be changed at any time. The special attributes are simply used to provide initial values. Note also that the usage of these special attributes can be controlled by the options selected with the "initial" qualifier.

3.3.3 Executing the CDFexport Program

Usage:

VMS:

$ CDFEXPORT [/INITIAL=(<options>)] [/[NO]PROMPT] [/ZMODE=<mode>]

[/REPORT=(<types>)] [/[NO]STATISTICS] [/[NO]NEG2POSFP0]

[/CACHE=(<sizes>)] [/[NO]SIMPLE] [/BATCH=<mode>] [/CDF=<path>]

[/TEXT=<path>] [/SETTINGS=<path>] <cdf-spec>

UNIX:

% cdfexport [-initial "<options>"] [-[no]prompt] [-zmode <mode>]

[-report "<types>"] [-[no]statistics] [- [no]neg2posfp0]

[-cache "<sizes>"] [-[no]simple] [-batch <mode>] [-cdf <path>]

[-text <path>] [-settings <path>] <cdf-spec>

MS-DOS:[50]

> cdfexport [-initial "<options>"] [-[no]prompt] [-zmode <mode>]

[-report "<types>"] [-[no]statistics] [-[no]neg2posfp0]

[-cache "<sizes>"] [-[no]simple] [-batch <mode>] [-cdf <path>]

[-text <path>] [-settings <path>] <cdf-spec>

Macintosh:

Double-click on the CDFexport icon.

Windows NT/95/98:

Double-click on the CDFfsi icon and select the CDFexport option under the File menu.

Java/UNIX:

This option is not yet available in the Java toolkit for Unix.

Macintosh & Windows NT/95/98: When the desired parameters/qualifiers have been selected in the dialog box, click on the Enter button to begin exporting from the CDF(s). Clicking on the Help button will display online help. Clicking on the Quit button terminates CDFexport.

Parameter(s):

<cdf-spec> (VMS, UNIX & MS-DOS)

CDF edit field (Macintosh, Java/UNIX & Windows NT/95/98)

The specification of the CDF(s) from which to export. Do not specify an extension. This may be either a single CDF file name or a directory/wildcard path. Wildcards are allowed in the CDF name but not in the directory path.

VMS, UNIX & MS-DOS: If the "prompt" qualifier is used, this will appear as the initial specification. If this parameter is omitted, the "prompt" qualifier must be specified and the initial specification will be the current directory.

Macintosh & Windows NT/95/98: At the end of the CDF edit field, a button labeled Select is present. When selected, a standard input file dialog is displayed from which a single

CDF may be selected.

Qualifier(s):

/[NO]PROMPT (VMS)

-[no]prompt (UNIX & MS-DOS)

Not applicable. (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not a prompt is issued for the CDF(s) specification. If this qualifier is not specified, the CDF(s) specification must be entered on the command line and is automatically opened.

VMS, UNIX & MS-DOS: If a CDF(s) specification was entered on the command line, that CDF(s) specification will initially appear at the prompt. Otherwise, the current directory will appear at the prompt.

Macintosh, Java/UNIX & Windows NT/95/98: This qualifier is not applicable on the Macintosh. The CDF(s) specification must always be entered in the dialog box and is then automatically opened.

/INITIAL=(<defaults>) (VMS)

-initial "<defaults>" (UNIX & MS-DOS)

Initial options check boxes, see below (Macintosh, Java/UNIX & Windows NT/95/98)

The default settings that are initially in affect when a CDF is opened. These setting are only the settings initially in effect. The user may change any of them at any time. More detailed descriptions of each option may be found in the appropriate sections that follow.

VMS, UNIX & MS-DOS: <defaults> is a comma-separated list of settings consisting of one

or more of the options in the list that follows. Macintosh, Java/UNIX & Windows NT/95/98: The initial settings are selected using the check boxes described in the list that follows.

[NO]FILTER (VMS)

[no]filter (UNIX & MS-DOS)

Filters enabled check box (Macintosh, Java/UNIX & Windows NT/95/98)

Whether or not each item/variable is initially filtered.

[NO]FILLS (VMS)

[no]fills (UNIX & MS-DOS)

Use fills check box (Macintosh, Java/UNIX & Windows NT/95/98)

Whether or not the use of fill values is enabled.

[NO]FORMAT (VMS)

[no]format (UNIX & MS-DOS)

Use FORMAT check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not a variable's FORMAT attribute entry is used as its initial "format" field.

[NO]FILLVAL (VMS)

[no]fillval (UNIX & MS-DOS)

Use FILLVAL check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not a variable's FILLVAL attribute entry is used as its initial "fill value" field.

[NO]VALIDMIN (VMS)

[no]validmin (UNIX & MS-DOS)

Use VALIDMIN check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not a variable's VALIDMIN attribute entry is used as its initial minimum filter value.

[NO]VALIDMAX (VMS)

[no]validmax (UNIX & MS-DOS)

Use VALIDMAX check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not a variable's VALIDMAX attribute entry is used as its initial maximum filter value.

[NO]MONOTON (VMS)

[no]monoton (UNIX & MS-DOS)

Use MONOTON check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not a variable's MONOTON attribute entry is used as its initial monotonicity.

[NO]RECORD (VMS)

[no]record (UNIX & MS-DOS)

Show `Record' check box (Macintosh & Java/UNIX)

Show records check box (Windows NT/95/98)

Specifies whether or not the Record item will be present.

[NO]INDICES (VMS)

[no]indices (UNIX & MS-DOS)

Show `Indices' check box (Macintosh & Java/UNIX)

Show indices check box (Windows NT/95/98)

Specifies whether or not the Indices item will be present.

[NO]EXCLUSIVE (VMS)

[no]exclusive (UNIX & MS-DOS)

Exclusive filters check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not exclusive filters are allowed.

[NO]OUTPUT (VMS)

[no]output (UNIX & MS-DOS)

Outputs enabled check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not each item/variable is initially output.

[NO]DELETE (VMS)

[no]delete (UNIX & MS-DOS)

Delete existing CDF check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies the initial setting of whether or not an existing CDF will be deleted when a new CDF is created with the same name.

[NO]PREALLOCATE (VMS)

[no]preallocate (UNIX & MS-DOS)

Preallocate records check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies the initial setting of whether or not variable records are to be preallocated when creating a new CDF.

SINGLE or MULTI (VMS)

single or multi (UNIX & MS-DOS)

New format radio buttons (Macintosh & Java/UNIX)

Format radio buttons (Windows NT/95/98)

Specifies the initial setting of whether single-file or multi-file CDFs are created.

HOST or NETWORK (VMS)

host or network (UNIX & MS-DOS)

New encoding radio buttons (Macintosh & Java/UNIX)

Encoding radio buttons (Windows NT/95/98)

Specifies the initial setting of whether host-encoded or network-encoded CDFs are created.

ROW or COLUMN (VMS)

row or column (UNIX & MS-DOS)

Majority radio buttons (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies the initial setting of whether row-major, column-major, or input-major CDFs/listings are generated. Input-majority is the majority of the input CDF.

VMS, UNIX & MS-DOS: Input-majority is selected by specifying neither row-majority nor column-majority.

EPOCH, EPOCH1, EPOCH2, EPOCH3, EPOCHf or EPOCHx (VMS)

epoch, epoch1, epoch2, epoch3, epochf or epochx (UNIX & MS-DOS)

EPOCH style radio buttons (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies the initial EPOCH encoding style.

HORIZONTAL or VERTICAL (VMS)

horizontal or vertical (UNIX & MS-DOS)

Orientation radio buttons (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies the initial setting of whether horizontal or vertical listings are generated.

Note that these options can be changed at any time after the CDF has been opened. If this qualifier is not specified, each of these options has a default setting. These default settings are also used for options not specified with this qualifier.

/ZMODE=<mode> (VMS)

-zmode <mode> (UNIX & MS-DOS)

zMode radio buttons (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies which zMode should be used. The zMode may be one of the following:

0 Indicates that zMode should be disabled.

1 Indicates that zMode/1 should be used. The dimension variances of rVariables will be preserved.

2 Indicates that zMode/2 should be used. The dimensions of rVariables having a variance of NOVARY [false] are removed.

/[NO]NEG2POSFP0 (VMS)

-[no]neg2posfp0 (UNIX & MS-DOS)

-0.0 to 0.0 check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not -0.0 is converted to 0.0 by the CDF library when encountered in a CDF. -0.0 is an illegal floating point value on VAXes and DEC Alphas running OpenVMS.

/REPORT=(<types>) (VMS)

-report "<types>" (UNIX & MS-DOS)

Report info's/warnings/errors check boxes (Macintosh, Java/UNIX & Windows NT/95/98)

/CACHE=(<sizes>) (VMS) -cache "<sizes>" (UNIX & MS-DOS)

Cache sizes edit field (Macintosh & Java/UNIX)

Cache edit field (Windows NT/95/98)

/[NO]STATISTICS (VMS)

-[no]statistics (UNIX & MS-DOS)

Display statistics check box (Macintosh & Java/UNIX)

Caching statistics check box (Windows NT/95/98)

Specifies whether or not caching statistics are displayed when a CDF is closed.

/[NO]SIMPLE (VMS)

-[no]simple (UNIX & MS-DOS)

Not applicable. (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies if a simplified version of CDFexport should be executed. The following conditions apply to simple mode:

- Only text listings can be generated (to the screen or a file).

- No filtering is available.

- When listing to a text file, FORMAT attribute entries are ignored and standard formats are used instead.

- Only a limited set of the options for the `initial' qualifier may be specified.

- zMode/2 is used by default.

- Horizontal listings are created by default.

/BATCH=<mode> (VMS)

-batch <mode> (UNIX & MS-DOS)

Not applicable. (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies if CDFexport should execute in a non-interactive batch mode. The mode option may be either "text" to generate a text file listing or "cdf" to output to a new CDF. A settings file will be used if one exists with the default name in the current directory or is explicitly specified with the `settings' qualifier. The settings file contains the parameters necessary to specify how the output CDF or text file should be generated. If a settings file is not available, default parameters will be used. CDFexport must be used interactively to create a settings file.

/CDF=<cdf> (VMS)

-cdf <cdf> (UNIX & MS-DOS)

Not applicable. (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies an output CDF file name to be used when exporting to a CDF in batch mode. Do not include an extension. When executing interactively, this file name will initially appear at the output CDF prompt. If this qualifier is not specified, the default CDF name is "default" (in the current directory).

/TEXT=<path> (VMS)

-text <path> (UNIX & MS-DOS)

Not applicable. (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies a file name to be used when exporting to a text file listing in batch mode. When executing interactively this file name will initially appear at the text file prompt. If this qualifier is not specified, the default text file name is "default.lis" (in the current directory).

/SETTINGS=<path> (VMS) -settings <path> (UNIX & MS-DOS)

Not applicable. (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies a settings file name to be used when executing in batch mode. When executing interactively this file name will initially appear at the settings file prompt when saving/restoring the current settings. The default settings file is "simple.set" if executing in simple mode and "export.set" otherwise (with each being in the current directory).

Example(s):

VMS:

$ CDFEXPORT [.SAMPLES]

$ CDFEXPORT/ZMODE=2/CACHE=(50d,100s) GISS_WETLX

$ CDFEXPORT/PROMPT/REPORT=(W,E)/INITIAL=(EXCLUSIVE,NOFORMAT)

$ CDFEXPORT/SIMPLE/BATCH=TEXT/TEXT=FLUX.OUT FLUX1996

UNIX:

% cdfexport samples

% cdfexport -zmode 2 -cache "50d,100s" giss_wetl

% cdfexport -prompt -report "w,e" -initial "exclusive,noformat"

% cdfexport -simple -batch text -text flux.out flux1996

MS-DOS:

> cdfexport samples

> cdfexport -zmode 2 -cache "50d,100s" giss_wetl

> cdfexport -prompt -report "w,e" -initial "exclusive,noformat"

3.3.4 Interaction with CDFexport

Interaction with CDFexport is through a 4-part SelectionWindow, an ActionMenu, an OptionMenu, numerous prompt windows, and several screen listing windows. Detailed online help is available for each window so only a brief description of each will be given here. After selecting a CDF from which to export, part 1 of the SelectionWindow will be loaded with a line for the <Record> item, the <Indices> item, and each variable. The <Record> item allows the record number to be included in a screen/file listing and/or filtering on the record number for any type of output. The <Indices> item allows the dimension indices to be included in a screen/file listing and/or filtering on the dimension indices for any type of output. Each variable line allows that variable to be included and/or filtered when generating any type of output. The KeyDefinitions window displays the available functions and their corresponding keys for a given window/prompt. The MessageBuffer displays errors/instructions as necessary.

Cycling through the four parts of the SelectionWindow allows the selection of the output to be generated. The online help explains the purpose of each field in the four parts of the SelectionWindow. The OptionMenu allows additional selections affecting the output. The ActionMenu is then used to generate the desired type of output (as well as some other miscellaneous operations).

The easiest way to learn how to use CDFexport is to read through the online help while generating the various types of output using a CDF with which you are familiar.

3.4 CDFconvert

3.4.1 Introduction

The CDFconvert program is used to convert various properties of a CDF. In all cases new CDFs are created. (Existing CDFs are not modified.) Any combination of the following properties may be changed when converting a CDF.

1. The format of the CDF may be changed (see Section 2.2.7).

2. The data encoding of the CDF may be changed (see Section 2.2.8).

3. The variable majority of the CDF may be changed (see Section 2.3.15).

4. The compression of the CDF (see Section 2.2.10) or the CDF's variables (see Section 2.3.14) may be changed.

5. The sparseness of the CDF's variables may be changed (see Sections 2.3.12 and 2.3.13).

3.4.2 Executing the CDFconvert Program

Usage:

VMS:

$ CDFCONVERT [/SKELETON=<skt-cdf-path>] [/[NO]LOG] [/[NO]PERCENT]

[/REPORT=(<types>)] [/CACHE=(<sizes>)] [/[NO]PAGE] [/[NO]STATISTICS]

<src-cdf-spec>

[/ZMODE=<mode>] [/[NO]NEG2POSFP0]

<dst-cdf-spec>

[/SINGLE | /MULTI] [/ROW | /COLUMN] [/[NO]DELETE]

[/ENCODING=<encoding> | /HOST | /NETWORK]

[/COMPRESSION=(<types>)] [/SPARSENESS=(<types>)]

UNIX:

% cdfconvert [-skeleton <skt-cdf-path>] [-[no]log] [-[no]percent]

[-report "<types>"] [-cache "<sizes>"] [-[no]page] [-[no]statistics]

<src-cdf-spec>

[-zmode <mode>] [-[no]neg2posfp0]

<dst-cdf-spec>

[-single | -multi] [-row | -column] [-[no]delete]

[-encoding <encoding> | -host | -network]

[-compression <types>] [-sparseness <types>]

MS-DOS:[51]

> cdfconvert [-skeleton <skt-cdf-path>] [-[no]log] [-[no]percent]

[-report "<types>"] [-cache "<sizes>"] [-[no]page] [-[no]statistics]

<src-cdf-spec>

[-zmode <mode>] [-[no]neg2posfp0]

<dst-cdf-spec>

[-single | -multi] [-row | -column] [-[no]delete]

[-encoding <encoding> | -host | -network]

[-compression <types>] [-sparseness <types>]

Macintosh:

Double-click on the CDFconvert icon.

Windows NT/95/98:

Double-click on the CDFso icon and select the CDFconvert option under the File menu.

Java/UNIX:

Type "java CDFToolsDriver" at the system prompt and select the CDFconvert option.

Macintosh, Java/UNIX & Windows NT/95/98:

When the desired parameters/qualifiers have been selected in the dialog box, click on the Enter button to convert the CDF. Clicking on the Help button will display online help. Clicking on the Quit button terminates CDFconvert.

Parameter(s):

<src-cdf-spec> (VMS, UNIX & MS-DOS)

Source edit field (Macintosh, Java/UNIX & Windows NT/95/98)

The source CDF(s). This can be either a single CDF file name or a directory/wildcard path in which case all CDFs that match the specification will be converted. Wildcards are allowed in the CDF name but not in the directory path. In either case do not specify an extension.

Macintosh, Java/UNIX & Windows NT/95/98: At the end of the Source edit field, a button labeled Select is present. When selected, a standard input file dialog is displayed from which a single CDF may be selected.

<dst-cdf-spec> (VMS, UNIX & MS-DOS)

Destination edit field (Macintosh, Java/UNIX & Windows NT/95/98)

The destination of the converted CDF(s). This may be a single CDF file name only if a single source CDF was specified. If the directory paths are the same, then a different CDF name must be specified. If the source CDF specification is a directory/wildcard path, then this must be a directory path (other than the source directory path). This may also be a directory path if only a single CDF is being converted. In any case do not specify an extension.

Macintosh, Java/UNIX & Windows NT/95/98: At the end of the Destination edit field, a button labeled Select is present. When selected, a standard output file dialog is displayed in which a single CDF may be specified.

Qualifier(s):

/SKELETON=<skt-cdf-path> (VMS)

-skeleton <skt-cdf-path> (UNIX & MS-DOS)

Skeleton edit field (Macintosh, Java/UNIX & Windows NT/95/98)

The file name of a skeleton CDF to be used during the conversions. (Do not enter an extension.) The skeleton CDF is used in the following cases:

1. If a format for the destination CDF was not specified, then the format of the skeleton CDF will be used.

2. If a variable majority for the destination CDF was not specified, then the variable majority of the skeleton CDF will be used.

3. If a data encoding for the destination CDF was not specified, then the data encoding of the skeleton CDF will be used.

Specifying a skeleton CDF is optional.

Macintosh, Java/UNIX & Windows NT/95/98: At the end of the Skeleton edit field, a

button labeled Select is present. When selected, a standard input file dialog is displayed from which the skeleton CDF may be selected.

/[NO]LOG (VMS)

-[no]log (UNIX & MS-DOS)

Log progress check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not messages about the progress of each conversion are displayed.

/[NO]PAGE (VMS)

-[no]page (UNIX & MS-DOS)

Page output check box (Macintosh & Java/UNIX)

Not applicable (Windows NT/95/98)

Specifies whether or not the output is displayed a page at a time. A prompt for the RETURN key will be issued after each page. A page is generally 22 lines of output.

/[NO]PERCENT (VMS)

-[no]percent (UNIX & MS-DOS)

Display percentages check box (Macintosh & Java/UNIX)

Percentage complete check box (Windows NT/95/98)

Specifies whether or not the percentage of a variable's values converted is displayed during the conversion of that variable. Message logging must also be enabled.

/[NO]DELETE (VMS)

-[no]delete (UNIX & MS-DOS)

Delete existing check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not a destination CDF is deleted if it already exists.

/SINGLE | /MULTI (VMS)

-single | -multi (UNIX & MS-DOS)

Source/Single/Multi radio buttons (Macintosh, Java/UNIX & Windows NT/95/98)

The format of the destination CDF(s).

VMS, UNIX & MS-DOS: This overrides the format of the skeleton CDF (if one was specified). If neither this qualifier nor a skeleton CDF is specified, then the format of a destination CDF will be the same as that of the source CDF.

Macintosh, Java/UNIX & Windows NT/95/98: Selecting Single or Multi will override the format of the skeleton CDF (if one was specified). If Source is selected (and a skeleton CDF was not specified), then the format of a destination CDF will be the same as that of the source CDF. (Selecting Source will not override the format of a specified skeleton CDF.)

/ROW | /COLUMN (VMS)

-row | -column (UNIX & MS-DOS)

Source/Row/Column radio buttons (Macintosh, Java/UNIX & Windows NT/95/98)

The variable majority of the destination CDF(s).

VMS, UNIX & MS-DOS: This overrides the variable majority of the skeleton CDF (if one was specified). If neither this qualifier nor a skeleton CDF is specified, then the variable majority of a destination CDF will be the same as that of the source CDF.

Macintosh, Java/UNIX & Windows NT/95/98: Selecting Row or Column will override the variable majority of the skeleton CDF (if one was specified). If Source is selected (and a skeleton CDF was not specified), then the variable majority of a destination CDF will be the same as that of the source CDF. (Selecting Source will not override the variable majority of a specified skeleton CDF.)

/ENCODING=<encoding> | /HOST | /NETWORK (VMS)

-encoding <encoding> | -host | -network (UNIX & MS-DOS)

Source/Host/Network/Sun...Vax radio buttons (Macintosh, Java/UNIX & Windows NT/95/98)

The data encoding of the destination CDF(s).

VMS, UNIX & MS-DOS: This overrides the data encoding of the skeleton CDF (if one was specified). If neither this qualifier nor a skeleton CDF is specified, then the data encoding of a destination CDF will be the same as that of the source CDF. The possible values of <encoding> are host, network, sun, vax, decstation, sgi, ibmpc, ibmrs, mac, hp, next, alphaosf1, alphavmsd, and alphavmsg (and their uppercase equivalents). Note that the host

and network qualifiers are no longer necessary (but are supported for compatibility with previous CDF distributions).

Macintosh, Java/UNIX & Windows NT/95/98: Selecting Host, Network, or a specific machine will override the data encoding of the skeleton CDF (if one was specified). If Source is selected (and a skeleton CDF was not specified), then the data encoding of a destination CDF will be the same as that of the source CDF. (Selecting Source will not override the data encoding of a specified skeleton CDF.)

/COMPRESSION=(<types>) (VMS)

-compression <types> (UNIX & MS-DOS)

Compression edit field (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies the types of compression to be used for the CDF and/or variables. The <types> option consists of a comma-separated list of the following. . .

cdf:<cT> CDF's compression.

vars:<cT> Compression for all variables.

vars:<cT>:<bF> Compression for all variables with a blocking factor specified.

vars:<cT>:<bF>:<r%> Compression for all variables with a blocking factor and reserve percentage specified.

var:<name>:<cT> Compression for one particular variable.

var:<name>:<cT>:<bF> Compression for one particular variable with a blocking factor specified.

var:<name>:<cT>:<bF>:<r%> Compression for one particular variable with a blocking factor and reserve percentage specified.

Where <cT> is one of the following compressions: none, rle.0, huff.0, ahuff.0, or gzip.<level>; <bF> is a blocking factor; <r%> is a reserve percentage; and <name> is a delimited, case-sensitive variable name with the following syntax:

In general, do not use single or double quote marks as delimiters. VMS: The entire delimited variable name must be enclosed in double quote marks (to preserve case-sensitivity).

For the gzip compression, <level> must be in the range from 1 (fastest compression) to 9 (best compression).

For compressions not specified the compression in the source CDF will be used. Specifying a variable compression using var:…overrides a compression specified with vars:. . .

/SPARSENESS=(<types>) (VMS) -sparseness <types> (UNIX & MS-DOS)

Sparseness edit field (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies the types of sparseness to be used for the variables. The <types> option consists of a comma-separated list of the following. . .

vars:<sT> Sparseness for all variables.

var:<name>:<sT> Sparseness for one particular variable.

Where <sT> is one of the following: srecords.no, srecords.pad, or srecords.prev; and <name> is a delimited, case-sensitive variable name with the following syntax:

In general, do not use single or double quote marks as delimiters. VMS: The entire delimited variable name must be enclosed in double quote marks (to preserve case-sensitivity).

For sparsenesses not specified the sparseness in the source CDF will be used. Specifying a variable sparseness using var:. . . overrides a sparseness specified with vars:.. .

/ZMODE=<mode> (VMS)

-zmode <mode> (UNIX & MS-DOS)

zMode radio buttons (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies the zMode that should be used with the source CDF(s). The zMode may be one of the following:

0 Indicates that zMode should be disabled.

1 Indicates that zMode/1 should be used. The dimension variances of rVariables will be preserved.

2 Indicates that zMode/2 should be used. The dimensions of rVariables having a variance of NOVARY [false] are removed.

Note that using zMode/1 or zMode/2 on a source CDF that contains rVariables will produce a destination CDF containing only zVariables. The zMode "view" provided for the source CDF is written to the destination CDF during the conversion.

/[NO]NEG2POSFP0 (VMS)

-[no]neg2posfp0 (UNIX & MS-DOS)

-0.0 to 0.0 check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not -0.0 is converted to 0.0 by the CDF library when encountered in a CDF. -0.0 is an illegal floating point value on VAXes and DEC Alphas running OpenVMS.

/REPORT=(<types>) (VMS)

-report "<types>" (UNIX & MS-DOS)

Report info's/warnings/errors check boxes (Macintosh, Java/UNIX & Windows NT/95/98)

/CACHE=(<sizes>) (VMS) -cache "<sizes>" (UNIX & MS-DOS)

Cache sizes edit field (Macintosh & Java/UNIX)

Cache edit field (Windows NT/95/98)

/[NO]STATISTICS (VMS)

-[no]statistics (UNIX & MS-DOS)

Display statistics check box (Macintosh & Java/UNIX)

Caching statistics check box (Windows NT/95/98)

Specifies whether or not caching statistics are displayed when a CDF is closed.

Example(s):

VMS:

$ CDFCONVERT CDF$SMPL:TEMPLATE0 TEMPLATE0X

$ CDFCONVERT/LOG/REPORT=(ERRORS) CDF$SMPL: USER_DISK:[USER.CDF]

$ CDFCONVERT CAC_SST_BLENDED CAC_SST_BLENDEDX/SINGLE/NETWORK

$ CDFCONVERT/SKELETON=CDF$SMPL:TEMPLATE3 CAC_SST_BLENDED* [USER.CDF]

UNIX:

% cdfconvert ../samples/template0 template0x

% cdfconvert -log -report "errors" ../samples /disk4/user/cdf

% cdfconvert cac_sst_blended cac_sst_1 -single -network

% cdfconvert -skeleton template3 '../cdf/cac_sst*' ~user/cdf

MS-DOS:

> cdfconvert .."samples"\tplate0 tplate0x

> cdfconvert -log -report "errors" ..\samples c:\dir4\user\cdf

> cdfconvert cac_sst cac_sst1 -single -network

> cdfconvert -skeleton tplate3 a:\cdf\cac_sst dir5\cdf

VMS, UNIX & MS-DOS:

Command line help is displayed when CDFconvert is executed without any arguments.

3.4.3 Output from the CDFconvert Program

As CDFconvert executes, the name of each CDF being converted is displayed. If message logging is enabled, the progress of each conversion is also displayed.

3.5 CDFcompare

3.5.1 Introduction

The CDFcompare program displays the differences between two CDFs. More than one pair of CDFs can be compared. This program would be used to verify changes made to a CDF (comparing it with the saved original) or to verify the conversions performed by CDFconvert (see Section 3.4).

3.5.2 Executing the CDFcompare Program

Usage:

VMS:

$ CDFCOMPARE [/[NO]LOG] [/[NO]ATTR] [/[NO]VAR] [/[NO]NUMBER] [/[NO]ETC]

[/[NO]NEG2POSFP0] [/ZMODES=(<mode1>,<mode2>)] [/[NO]LOCATION]

[/REPORT=(<types>)] [/CACHE=(<sizes>)] [/[NO]PAGE]

[/[NO]STATISTICS] [/[NO]PERCENT] [/[NO]VALUE]

[/TOLERANCE=(<F:tolerance1>,<D:tolerance1>)]

<cdf-spec-1> <cdf-spec-2>

UNIX:

% cdfcompare [-[no]log] [-[no]attr] [-[no]var] [-[no]number] [-[no]etc]

[-[no]neg2posfp0] [-zmodes "<mode1>,<mode2>"] [-[no]location]

[-report "<types>"] [-cache "<sizes>"] [-[no]page]

[-[no]statistics] [-[no]percent] [-[no]value]

[-tolerance "<f:tolerance1>,<d:tolerance2>"]

<cdf-spec-1> <cdf-spec-2>

MS-DOS:[52]

> cdfcompare [-[no]log] [-[no]attr] [-[no]var] [-[no]number] [-[no]etc]

[-[no]neg2posfp0] [-zmodes "<mode1>,<mode2>"] [-[no]location]

[-report "<types>"] [-cache "<sizes>"] [-[no]page]

[-[no]statistics] [-[no]percent] [-[no]value]

<cdf-spec-1> <cdf-spec-2>

Macintosh:

Double-click on the CDFcompare icon.

Windows NT/95/98:

Double-click on the CDFso icon and select the CDFcompare option under the File menu.

Macintosh:

Type "java CDFToolsDriver" at the system prompt and select the CDFcompare option.

Macintosh, Java/UNIX & Windows NT/95/98: When the desired parameters/qualifiers have been selected in the dialog box, click on the Enter button to compare the CDFs. Clicking on the Help button will display online help. Clicking on the Quit button terminates CDFcompare.

Parameter(s):

<cdf-spec-1> <cdf-spec-2> (VMS, UNIX & MS-DOS)

CDF1 and CDF2 edit fields (Macintosh, Java/UNIX & Windows NT/95/98)

The specifications of the CDFs to be compared. (Do not enter extensions.) These can be either a file name specifying a single CDF or a directory/wildcard path specifying more than one CDF. Wildcards are allowed in the CDF name but not in the directory path.

If two directory/wildcard paths are specified, all of the CDFs with matching names will be compared. If a CDF file name and a directory/wildcard path are specified, the CDF specified will be compared with the CDF in the directory/wildcard path having the same name. If two CDF file names are specified, the CDFs are compared. (This is the only way to compare two CDFs having different names.)

Macintosh, Java/UNIX & Windows NT/95/98: At the end of each CDF edit field, a button labeled Select is present. When selected, a standard input file dialog is displayed from which a single CDF may be selected.

Qualifier(s):

/[NO]LOG (VMS)

-[no]log (UNIX & MS-DOS)

Log progress check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not messages about the progress of each comparison are displayed.

/[NO]PERCENT (VMS)

-[no]percent (UNIX & MS-DOS)

Display percentages check box (Macintosh & Java/UNIX)

Percentage complete check box (Windows NT/95/98)

Specifies whether or not the percentage of a variable's values compared is displayed during the comparison of that variable. Message logging must also be enabled.

/[NO]ATTR (VMS)

-[no]attr (UNIX & MS-DOS)

Compare attributes check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not attributes (and their entries) are to be compared.

/[NO]VAR (VMS)

-[no]var (UNIX & MS-DOS)

Compare variables check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not variables are to be compared. Note that an rVariable will never be compared with a zVariable.

/[NO]NUMBER (VMS)

-[no]number (UNIX & MS-DOS)

Compare numbers check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not numbering differences between attributes with the same names and between variables with the same names are to be displayed.

/[NO]ETC (VMS)

-[no]etc (UNIX & MS-DOS)

Compare etc. check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not differences transparent to an application will be displayed. These would consist of the version/release/increment of the creating CDF library, format, encoding, etc.

/ZMODES=(<mode1>,<mode2>) (VMS)

-zmodes "<mode1>,<mode2>" (UNIX & MS-DOS)

zMode1 and zMode2 radio buttons (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies the zModes that should be used with the CDF(s) being compared. Note that different zModes may be used for the two CDF(s) specifications. The zModes may be one of the following:

0 Indicates that zMode should be disabled.

1 Indicates that zMode/1 should be used. The dimension variances of rVariables will be preserved.

2 Indicates that zMode/2 should be used. The dimensions of rVariables having a variance of NOVARY [false] are removed.

/[NO]NEG2POSFP0 (VMS)

-[no]neg2posfp0 (UNIX & MS-DOS)

-0.0 to 0.0 check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not -0.0 is converted to 0.0 by the CDF library when encountered in a CDF. -0.0 is an illegal floating point value on VAXes and DEC Alphas running OpenVMS.

/[NO]PAGE (VMS)

-[no]page (UNIX & MS-DOS)

Page output check box (Macintosh & Java/UNIX)

Not applicable (Windows NT/95/98)

Specifies whether or not the output is displayed a page at a time. A prompt for the RETURN key will be issued after each page. A page is generally 22 lines of output.

/[NO]LOCATION (VMS)

-[no]location (UNIX & MS-DOS)

Display locations check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not the locations of variable value differences are displayed. The locations are displayed in the form:

<record-number>:[<index1>,<index2>,...,<indexN>]

/[NO]VALUE (VMS)

-[no]value (UNIX & MS-DOS)

Display values check box (Macintosh & Java/UNIX)

Show values check box (Windows NT/95/98)

Specifies whether or not the values are displayed when a difference is detected between variable values or attribute entries. Note that for variable values to be displayed, the display of the locations of the differences must also be enabled.

/REPORT=(<types>) (VMS)

-report "<types>" (UNIX & MS-DOS)

Report info's/warnings/errors check boxes (Macintosh, Java/UNIX & Windows NT/95/98)

Cache sizes edit field (Macintosh & Java/UNIX)

/CACHE=(<sizes>) (VMS)

-cache "<sizes>" (UNIX & MS-DOS)

Cache edit field (Windows NT/95/98)

/TOLERANCE=(<F:TOLERANCE1,D:TOLERANCE2>) (VMS)

-tolerance "<f:tolerance1,d:tolerance2>" (UNIX & MS-DOS)

Not applicable (Windows NT/95/98)

Specifies the tolerance(s) that is used to check the equality between two single/double-precision floating-point values. The default option is no tolerance. It means that two values are considered unequal if their data representations in common encoding are different. If a tolerance(s) is provided, it is used against the difference between the two unequal values. If their difference is within the tolerance, they are considered to be technically equal. Either one or both of these two tolerances, one for 4-byte single-precision floating-point data and the other for 8-byte double-precision floating-point data, respectively, can be specified.

If the given tolerance is positive, the following formula is used to check their equality:

abs(value1-value2) > tolerance

If the given tolerance is negative, the following formula is applied:

abs(value1-value2) > abs(tolerance)*max(abs(value1),abs(value2))

tolerance1, used for the single-precision floating-point data, may be in one of the two forms: "default" or a value. Using "default" indicates that the default value, 1.0E-06, is used for the tolerance check for any single-precision floating-point data. Or, the specified value is used for the tolerance check. This field applies to data types of CDF_REAL4 and CDF_FLOAT. "def" can be used to substitute for "default".

tolerance2, used for the double-precision floating-point data,may be in one of the two forms: "default" or a value. Using "default" indicates that the default value, 1.0E-09, is used for the tolerance check for any double-precision floating-point data. Or, the specified value is used for the tolerance check. This field applies to data types of CDF_REAL8, CDF_DOUBLE and CDF_EPOCH. "default" can be abbreviated as "def".

Note: This option is only applicable to command line tool.

/[NO]STATISTICS (VMS)

-[no]statistics (UNIX & MS-DOS)

Display statistics check box (Macintosh & Java/UNIX)

Caching statistics check box (Windows NT/95/98)

Specifies whether or not caching statistics are displayed when a CDF is closed.

Example(s):

VMS:

$ CDFCOMPARE GISS_WETL GISS_WETL1

$ CDFCOMPARE/LOG/TOLERANCE=(F:DEF,D:1.0E-12)/NOATTR/NUMBER/REPORT=(ERRORS) GISS_WETL

CDF$SMPL:GISS_WETL

$ CDFCOMPARE/NOVAR/NOETC/ZMODES=(1,2) NCDS$SMPL: NCDS$DATA:

UNIX:

% cdfcompare giss_wetl giss_wetl1

% cdfcompare -log -tolerance "f:def,d:1.0e-12" -noattr

-number -report "errors" giss_wetl ../giss_wetlx

% cdfcompare -novar -noetc -zmodes "1,2" /user5/CDFs /user6/CDFs

MS-DOS:

> cdfcompare gisswetl c:\gisswetl

> cdfcompare -log -tolerance "f:def,d:1.0e-12" -noattr

-number -report "errors" gisswetl ..\..\giswetlx_

> cdfcompare -novar -noetc -zmodes "1,2" a:\cdfs c:\cdf\cdfs

VMS, UNIX & MS-DOS: Command line help is displayed when CDFcompare is executed without any arguments.

3.5.3 Output from the CDFcompare Program

The output from CDFcompare consists of messages indicating the differences found. If message logging is enabled, the progress of each comparison is also displayed.

3.6 CDFstats

3.6.1 Introduction

The CDFstats program produces a statistical report on a CDF's variable data. Both rVariables and zVariables are analyzed. For each variable it determines the actual minimum and maximum values (in all of the variable records), the minimum and maximum values within a valid range of values (with illegal/fill values being ignored), and the variable's monotonicity.

Monotonicity refers to whether or not a variable's data values increase or decrease from record to record or along a dimension. This property is checked only if the variable varies along just one "dimension" (considering records to be another "dimension"). For example, consider a CDF with the 2-dimensional rVariables shown in Table 3.1.

rVariable	Record Variance	Dimension Variances	Check Monotonicity?
EPOCH	VARY	NOVARY,NOVARY	Yes
LATITUDE	NOVARY	VARY,NOVARY	Yes
LONGITUDE	NOVARY	NOVARY,VARY	Yes
ELEVATION	NOVARY	VARY,VARY	No
TEMPERATURE	VARY	VARY,VARY	No

Table 3.1 Example rVariables, CDFstats Monotonicity Checking

The EPOCH, LATITUDE, and LONGITUDE rVariables would be checked for monotonicity but the ELEVATION and TEMPERATURE rVariables would not be checked.

3.6.2 Special Attribute Usage

CDFstats uses the following special attributes:

FORMAT Used when displaying a variable statistic (e.g., minimum variable value).

VALIDMIN If range checking is enabled, used as the minimum valid value for a variable. For a variable with a non-character data type, only the first element of its VALIDMIN attribute entry is used. Also, if requested, the VALIDMIN attribute entry for a variable will be updated with the actual minimum value found. Again, if the variable has a non-character data type the VALIDMIN attribute entry will be updated to have just one element.

VALIDMAX If range checking is enabled, used as the maximum valid value for a variable. For a variable with a non-character data type, only the first element of its VALIDMAX attribute entry is used. Also, if requested, the VALIDMAX attribute entry for a variable will be updated with the actual maximum value found. Again, if the variable has a non-character data type the VALIDMAX attribute entry will be updated to have just one element.

FILLVAL If fill value usage is enabled, used as the value which is ignored while collecting statistics for a variable.

MONOTON If requested, the MONOTON attribute entry for a variable will be updated with the actual monotonicity found. The possible values for the MONOTON attribute entry are described in Section 3.1.5.

SCALEMIN If requested, the SCALEMIN attribute entry for a variable will be updated with the actual minimum value found.

SCALEMAX If requested, the SCALEMAX attribute entry for a variable will be updated with the actual maximum value found.

The usage of these special attributes can be controlled with command line qualifiers.

3.6.3 Executing the CDFstats Program

Usage:

VMS:

$ CDFSTATS [/[NO]RANGE] [/[NO]FILL] [/OUTPUT=<file-path>] [/[NO]FORMAT]

[/[NO]PAGE] [/[NO]UPDATE_VALIDS] [/[NO]UPDATE_SCALES]

[/[NO]UPDATE_MONOTONIC] [/ZMODE=<mode>] [/[NO]NEG2POSFP0]

[/REPORT=(<types>)] [/CACHE=(<sizes>)] [/[NO]STATISTICS]

<cdf-path>

UNIX:

% cdfstats [-[no]range] [-[no]fill] [-output <file-name>] [-[no]format]

[-[no]page] [-[no]update_valids] [-[no]update_scales]

[-[no]update_monotonic] [-zmode <mode>] [-[no]neg2posfp0]

[-report "<types>"] [-cache "<sizes>"] [-[no]statistics]

<cdf-path>

MS-DOS:

> cdfstats [-[no]range] [-[no]fill] [-output <file-name>] [-[no]format]

[-[no]page] [-[no]update_valids] [-[no]update_scales]

[-[no]update_monotonic] [-zmode <mode>] [-[no]neg2posfp0]

[-report "<types>"] [-cache "<sizes>"] [-[no]statistics]

<cdf-path>

Macintosh:

Double-click on the CDFstats icon.

Windows NT/95/98:

Double-click on the CDFso icon and select the CDFstats option under the File menu.

Java/UNIX:

Type "java CDFToolsDriver" at the system prompt and select the CDFstats option.

Macintosh, Java/UNIX & Windows NT/95/98: When the desired parameters/qualifiers have been selected in the dialog box, click on the Enter button to analyze the CDF. Clicking on the Help button will display online help. Clicking on the Quit button terminates CDFstats.

Parameter(s):

<cdf-path> (VMS, UNIX & MS-DOS)

CDF edit field (Macintosh, Java/UNIX & Windows NT/95/98)

The file name of the CDF to analyze. (Do not specify an extension.)

Macintosh, Java/UNIX & Windows NT/95/98: At the end of the CDF edit field, a

button labeled Select is present. When selected, a standard input file dialog is displayed from which the CDF may be selected.

Qualifier(s):

/[NO]RANGE (VMS)

-[no]range (UNIX & MS-DOS)

Range checking check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not range checking will be performed. To perform range checking, the CDF must contain VALIDMIN and VALIDMAX attributes. A variable must also have an entry for each of these attributes in order for range checking to be performed on that variable. Note that for variables having a non-character data type only the first element of the VALIDMIN and VALIDMAX attribute entries are used.

/[NO]FILL (VMS)

-[no]fill (UNIX & MS-DOS)

Use FILLVAL check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not fill values are ignored when collecting statistics. The FILLVAL attribute entry for a variable (if it exists) is used as the fill value.

/OUTPUT=<file-path> (VMS)

-output <file-path> (UNIX & MS-DOS)

Output edit field (Macintosh & Java/UNIX)

Output edit field (Windows NT/95/98)

If this qualifier is specified, the statistical output is written to the named file. If the named file does not have an extension, .sts (UNIX & Macintosh) or .STS (VMS & MS-DOS) is appended automatically. If this qualifier is not specified, the output is displayed on the screen.

Macintosh, Java/UNIX & Windows NT/95/98: At the end of the Output edit field, a button labeled Select is present. When selected, a standard output file dialog is displayed in which the output file may be specified.

/[NO]FORMAT (VMS)

-[no]format (UNIX & MS-DOS)

Use FORMAT check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not the FORMAT attribute is used when displaying variable values (if the

FORMAT attribute exists and an entry exists for the variable).

/[NO]PAGE (VMS)

-[no]page (UNIX & MS-DOS)

Page output check box (Macintosh & Java/UNIX)

Not applicable (Windows NT/95/98)

Specifies whether or not the output is displayed a page at a time. A prompt for the RETURN key will be issued after each page. A page is generally 22 lines of output.

/[NO]UPDATE VALIDS (VMS)

-[no]update valids (UNIX & MS-DOS)

Update VALIDMIN/MAX check boxes (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not the VALIDMIN and VALIDMAX attribute entry values are updated for each variable based on the actual minimum and maximum values found (with fill values being ignored if requested). If the VALIDMIN and VALIDMAX attributes do not exist, they are created.

/[NO]UPDATE SCALES (VMS)

-[no]update scales (UNIX & MS-DOS)

Update SCALEMIN/MAX check boxes (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not the SCALEMIN and SCALEMAX attribute entry values are updated for each variable based on the actual minimum and maximum values found (with fill values being ignored if requested). If the SCALEMIN and SCALEMAX attributes do not exist, they are created.

/[NO]UPDATE MONOTONIC (VMS)

-[no]update monotonic (UNIX & MS-DOS)

Update MONOTON check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not the MONOTONIC attribute entry values are updated for each variable based on the monotonicity found (with fill values being ignored if requested). If the MONOTONIC attribute does not exist, it is created.

/ZMODE=<mode> (VMS)

-zmode <mode> (UNIX & MS-DOS)

zMode radio buttons (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies the zMode that should be used with the CDF. The zMode may be one of the following:

0 Indicates that zMode should be disabled.

1 Indicates that zMode/1 should be used. The dimension variances of rVariables will be preserved.

2 Indicates that zMode/2 should be used. The dimensions of rVariables having a variance of NOVARY [false] are removed.

/[NO]NEG2POSFP0 (VMS)

-[no]neg2posfp0 (UNIX & MS-DOS)

-0.0 to 0.0 check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not -0.0 is converted to 0.0 by the CDF library when encountered in a CDF. - 0.0 is an illegal floating point value on VAXes and DEC Alphas running OpenVMS.

/REPORT=(<types>) (VMS)

-report "<types>" (UNIX & MS-DOS)

Report info's/warnings/errors check boxes (Macintosh, Java/UNIX & Windows NT/95/98)

/CACHE=(<sizes>) (VMS)

-cache "<sizes>" (UNIX & MS-DOS)

Cache sizes edit field (Macintosh & Java/UNIX)

Cache edit field (Windows NT/95/98)

/[NO]STATISTICS (VMS)

-[no]statistics (UNIX & MS-DOS)

Display statistics check box (Macintosh & Java/UNIX)

Caching statistics check box (Windows NT/95/98)

Specifies whether or not caching statistics are displayed when a CDF is closed.

Example(s):

VMS:

$ CDFSTATS TEST1

$ CDFSTATS/REPORT=(ERRORS) GISS_SOIL

$ CDFSTATS/NOFILL/OUTPUT=TEMPLATE3/NORANGE CDF$SMPL:TEMPLATE3

UNIX:

% cdfstats giss_soil

% cdfstats -range -fill -report "errors" $CDF_SMPL/giss_soil

% cdfstats -norange -output template3 ../../samples/template3

MS-DOS:

> cdfstats gisssoil

> cdfstats -range -nofill -report "errors" a:\cdfs\gisssoil

> cdfstats -norange -output tplate3 ..\..\samples\tplate3

VMS, UNIX & MS-DOS: Command line help is displayed when CDFstats is executed without any

arguments.

3.6.4 Output from the CDFstats Program

The format of the output from CDFstats is as follows:

For each variable (rVariables and zVariables),

<number>. <name> <n-dims>: [<dim-sizes>] <rec-vary>/<dim-varys> (<data-type>/<n-elems>)

min:	<min-value>
min in range:	<min-value-in-range>
valid min:	<valid-min>, <low-values> low value(s)

max:	<max-value>
max in range:	<max-value-in-range>
valid max:	<valid-max>, <high-values> high value(s)

fill value:	<fill-value>, <fill-values> fill value(s)

monotonic:	<monotonicity>

If range checking and/or fill value filtering is disabled, the corresponding fields will not be displayed. The fields are defined as follows:

<number> The variable number.

<name> The variable name.

<rec-vary> The record variance of the variable - either a T or F.

<dim-varys> The dimension variances of the variable - for each dimension either a T or F. This field is not present if there are zero (0) dimensions.

<data-type> The data type of the variable (e.g., CDF REAL4).

<n-elems> The number of elements of the variable's data type.

<n-dims> The number of dimensions of a zVariable. This field is not present for an rVariable.

<dim-sizes> The dimension sizes of a zVariable. This field is not present for an rVariable or if the zVariable has zero (0) dimensions.

<min-value> The minimum value found (regardless of any range checking performed).

<min-value-in-range> The minimum value found within the valid range.

<valid-min> The minimum valid value (VALIDMIN attribute entry value).

<low-values> The number of values found that are less than the valid minimum.

<max-value> The maximum value found (regardless of any range checking performed).

<max-value-in-range> The maximum value found with the valid range.

<valid-max> The maximum valid value (VALIDMAX attribute entry value).

<high-values> The number of values found that are greater than the valid maximum.

<fill-value> The fill value (FILLVAL attribute entry value).

<fill-values> The number of fill values found.

<monotonicity> The monotonicity of the variable.

The <monotonicity> field may take on one of the following values.

Steady (one value) The variable has only one value in the CDF.

Steady (all values the same) All values of the variable are the same.

Increase Values strictly increase (with increasing record number/dimension index).

Decrease Values strictly decrease (with increasing record number/dimension index).

noDecrease (some values the same) Consecutive values either increase or are the same (with increasing record number/dimension index).

noIncrease (some values the same) Consecutive values either decrease or are the same (with increasing record number/dimension index).

False Consecutive values both increase and decrease.

n/a The variable was not checked for monotonicity because it varies along more than one "dimension" (if records are considered another "dimension").

3.7 SkeletonTable

3.7.1 Introduction

The SkeletonTable program is used to create an ASCII text file called a skeleton table containing information about a given CDF. (SkeletonTable can also be instructed to output the skeleton table to the terminal screen.) It reads a CDF and writes to the skeleton table the following information.

1. Format (single or multi file), data encoding, variable majority.

2. Number of dimensions and dimension sizes for the rVariables.

3. gAttribute definitions and gEntry values.

4. rVariable and zVariable definitions and vAttribute definitions with rEntry/zEntry values.

5. Data values for all or a subset of the CDF's variables.

The above information is written in a format that can be "understood" by the SkeletonCDF program (see Section 3.8). SkeletonCDF reads a skeleton table and creates a new CDF (called a skeleton CDF).

3.7.2 Special Attribute Usage

The special attribute FORMAT is used by SkeletonTable (depending on the setting of the "format" qualifier) when writing variable values in a skeleton table.

3.7.3 Executing the SkeletonTable Program

Usage:

VMS:

$ SKELETONTABLE [/SKELETON=<skeleton-path>] [/[NO]LOG] [/ZMODE <mode>]

[/NONRV | /NRVTABLE | /VALUES=<values>] [/[NO]SCREEN]

[-[NO]NEG2POSFP0] [/[NO]FORMAT] [/REPORT=(<types>)]

[/CACHE=(<sizes>)] [/[NO]PAGE] [/[NO]STATISTICS]

<cdf-path>

UNIX:

% skeletontable [-skeleton <skeleton-path>] [-[no]log] [-zmode <mode>]

[-nonrv | -nrvtable | -values <values>] [-[no]screen]

[-[no]neg2posfp0] [-[no]format] [-report "<types>"]

[-cache "<sizes>"] [-[no]page] [-[no]statistics]

<cdf-path>

MS-DOS:[53]

> skeletontable [-skeleton <skeleton-path>] [-[no]log] [-zmode <mode>]

[-nonrv | -nrvtable | -values <values>]

[-[no]screen] [-[no]neg2posfp0] [-[no]format] [-report "<types>"]

[-cache "<sizes>"] [-[no]page] [-[no]statistics]

<cdf-path>

Macintosh:

Double-click on the SkeletonTable icon.

Windows NT/95/98:

Double-click on the CDFso icon and select the SkeletonTable option under the File menu.

Java/UNIX:

Type "java CDFToolsDriver" at the system prompt and select the SkeletonTable option.

Macintosh, Java/UNIX & Windows NT/95/98: When the desired parameters/qualifiers have been selected in the dialog box, click on the Enter button to create the skeleton table. Clicking on the Help button will display online help. Clicking on the Quit button terminates SkeletonTable.

Parameter(s):

<cdf-path> (VMS, UNIX & MS-DOS)

CDF edit field (Macintosh, Java/UNIX & Windows NT/95/98)

The file name of the CDF from which the skeleton table will be created. (Do not enter an extension.)

Macintosh, Java/UNIX & Windows NT/95/98: At the end of the CDF edit field, a button labeled Select is present. When selected, a standard input file dialog is displayed from which the CDF may be selected.

Qualifier(s):

/SKELETON=<skeleton-path> (VMS)

-skeleton <skeleton-path> (UNIX & MS-DOS)

Skeleton edit field (Macintosh, Java/UNIX & Windows NT/95/98)

The file name of the skeleton table to be created. (Do not enter an extension because .skt is appended automatically.) If this qualifier is not specified, the skeleton table will be named <cdf-name>.skt in the default/current directory (where <cdf-name> is the name portion of the CDF from which the skeleton table was created).

Macintosh, Java/UNIX & Windows NT/95/98: At the end of the Skeleton edit field, a button labeled Select is present. When selected, a standard output file dialog is displayed in which the skeleton table may be specified.

/VALUES=<values> | /NRVTABLE | /NONRV (VMS)

-values <values> | -nrvtable | -nonrv (UNIX & MS-DOS)

No values/.../Selected values radio buttons (Macintosh, Java/UNIX & Windows NT/95/98)

Only one of these qualifiers may be specified. The meaning of each is as follows:

/VALUES=<values> (VMS)

-values <values> (UNIX & MS-DOS)

No values/.../Selected values radio buttons (Macintosh, Java/UNIX & Windows NT/95/98)

VMS, UNIX & MS-DOS: The <values> option specifies which variable values should be put in the skeleton table. Select one of the options from the list which follows.

Macintosh, Java/UNIX & Windows NT/95/98: Selecting one of the radio buttons described in the following list specifies which variable values should be put in the skeleton table.

None (VMS)

No values radio button (UNIX & MS-DOS)

Off raio button (Macintosh, Java/UNIX & Windows NT/95/98)

No variable values should be put in the skeleton table.

Nrv (VMS)

NRV values radio button (UNIX & MS-DOS)

NRV radio button (Macintosh, Java/UNIX & Windows NT/95/98)

Only NRV variable values should be put in the skeleton table.

Rv (VMS)

RV values radio button (UNIX & MS-DOS)

RV radio button (Macintosh, Java/UNIX & Windows NT/95/98)

Only RV variable values should be put in the skeleton table.

All (VMS)

All values radio button (UNIX & MS-DOS)

All radio button (Macintosh, Java/UNIX & Windows NT/95/98)

All variable values should be put in the skeleton table.

<named> (VMS)

Selected values radio button (UNIX & MS-DOS)

named radio button (Macintosh, Java/UNIX & Windows NT/95/98)

Values of the named variables should be put in the skeleton table.

VMS, UNIX & MS-DOS: <values> is a comma-separated list of delimited variable names with the entire list enclosed in double quote marks. NOTE: Do not use double quote marks to delimit a variable name.

Macintosh, Java/UNIX & Windows NT/95/98: The named variables are specified in the Variables edit field as a comma-separated list of delimited variable names.

/NONRV (VMS)

-nonrv (UNIX & MS-DOS)

Not supported (Macintosh, Java/UNIX & Windows NT/95/98)

Ignore NRV data. (No values are placed in the skeleton table.)

/NRVTABLE (VMS)

-nrvtable (UNIX & MS-DOS)

Not supported (Macintosh, Java/UNIX & Windows NT/95/98)

Put NRV variable data values in the skeleton table.

VMS, UNIX & MS-DOS: Note that only the "values" qualifier is actually needed. The others are supported for compatibility with previous CDF distributions.

/[NO]LOG (VMS)

-[no]log (UNIX & MS-DOS)

Log progress check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not messages are displayed as the program executes.

/ZMODE=<mode> (VMS)

-zmode <mode> (UNIX & MS-DOS)

zMode radio buttons (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies the zMode that should be used with the CDF. The zMode may be one of the following:

0 Indicates that zMode should be disabled.

1 Indicates that zMode/1 should be used. The dimension variances of rVariables will be preserved.

2 Indicates that zMode/2 should be used. The dimensions of rVariables having a variance of NOVARY [false] are removed.

/[NO]FORMAT (VMS)

-[no]format (UNIX & MS-DOS)

Use FORMAT check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not the FORMAT attribute is used when writing variable values (if the FORMAT attribute exists and an entry exists for the variable).

/[NO]NEG2POSFP0 (VMS)

-[no]neg2posfp0 (UNIX & MS-DOS)

-0.0 to 0.0 check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not -0.0 is converted to 0.0 by the CDF library when encountered in a CDF. -0.0 is an illegal floating point value on VAXes and DEC Alphas running OpenVMS.

/REPORT=(<types>) (VMS)

-report "<types>" (UNIX & MS-DOS)

Report info's/warnings/errors check boxes (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies the types of return status codes from the CDF library that should be reported/displayed. The <types> option is a comma-separated list of zero or more of the following symbols: errors,

warnings, or informationals. Note that these symbols can be truncated (e.g., e, w, and i).

/CACHE=(<sizes>) (VMS) -cache "<sizes>" (UNIX & MS-DOS)

Cache sizes edit field (Macintosh & Java/UNIX)

Cache edit field (Windows NT/95/98)

/[NO]STATISTICS (VMS)

-[no]statistics (UNIX & MS-DOS)

Display statistics check box (Macintosh & Java/UNIX)

Caching statistics check box (Windows NT/95/98)

Specifies whether or not caching statistics are displayed when a CDF is closed.

/[NO]SCREEN (VMS)

-[no]screen (UNIX & MS-DOS)

Output to screen check box (Macintosh & Java/UNIX)

To screen check box (Windows NT/95/98)

Specifies whether or not the skeleton table is to be displayed on the terminal screen (written to the "standard output"). If not, the skeleton table is written to a text file.

/[NO]PAGE (VMS)

-[no]page (UNIX & MS-DOS)

Page output check box (Macintosh & Java/UNIX)

Not applicable (Windows NT/95/98)

Specifies whether or not the output is displayed a page at a time. A prompt for the RETURN key will be issued after each page. A page is generally 22 lines of output.

Example(s):

VMS:

$ SKELETONTABLE/NOLOG/REPORT=(ERRORS) FGGE3B

$ SKELETONTABLE/SKELETON=FGGE3B/NONRV FGGE3B

$ SKELETONTABLE/SCREEN/VALUES="'Var1','Var2'"

UNIX:

% skeletontable -nolog -report "errors" fgge3b

% skeletontable -skeleton fgge3b -nonrv ../cdfs/fgge3b

% skeletontable -screen -values "'Var1','Var2'"

MS-DOS:

> skeletontable -nolog -report "errors" fgge3b

> skeletontable -skeleton fgge3b -nonrv c:\temp\fgge3b

> skeletontable -screen -values "'Var1','Var2'"

VMS, UNIX & MS-DOS: Command line help is displayed when SkeletonTable is executed without any arguments.

3.7.4 Output from the SkeletonTable Program

The format of the skeleton table is described in Appendix A.

3.8 SkeletonCDF

3.8.1 Introduction

The SkeletonCDF[54] program is used to make a fully structured CDF, called a skeleton CDF, by reading a text file called a skeleton table. The SkeletonCDF program allows a CDF to be created with the following:

1. The necessary header information - the number of dimensions and dimension sizes for the rVariables, format, data encoding, and variable majority.

2. The gAttribute definitions and any number of gEntries for each.

3. The rVariable and zVariable definitions.

4. The vAttribute definitions and the entries corresponding to each variable.

5. The data values for any or all of the variables.

The created CDF is referred to as a skeleton CDF.

3.8.2 Executing the SkeletonCDF Program

Usage:

VMS:

$ SKELETONCDF [/CDF=<cdf-path>] [/[NO]LOG] [/[NO]DELETE] [/[NO]FILLVAL] [/REPORT=(<types>)] [/[NO]NEG2POSFP0] [/CACHE=(<sizes>)] [/ZMODE=<mode>] <skeleton-path>

UNIX:

% skeletoncdf [-cdf <cdf-path>] [-[no]log] [-[no]delete] [-[no]fillval]

[-report "<types>"] [-[no]neg2posfp0] [-cache "<sizes>"]

[-zmode <mode>] <skeleton-path>

MS-DOS:[55]

> skeletoncdf [-cdf <cdf-path>] [-[no]log] [-[no]delete] [-[no]fillval]

[-report "<types>"] [-[no]neg2posfp0] [-cache "<sizes>"]

[-zmode <mode>] <skeleton-path>

Macintosh:

Double-click on the SkeletonCDF icon.

Windows NT/95/98:

Double-click on the CDFso icon and select the SkeletonCDF option under the File menu.

Java/UNIX:

Type "java CDFToolsDriver" at the system prompt and select the SkeletonCDF option.

Macintosh, Java/UNIX & Windows NT/95/98: When the desired parameters/qualifiers have been selected in the dialog box, click on the Enter button to create a CDF. Clicking on the Help button will display online help. Clicking on the Quit button terminates SkeletonCDF.

Parameter(s):

<skeleton-path> (VMS, UNIX & MS-DOS)

Skeleton edit field (Macintosh, Java/UNIX & Windows NT/95/98)

The file name of the skeleton table from which a skeleton CDF will be created. (Do not specify an extension.)

Macintosh, Java/UNIX & Windows NT/95/98: At the end of the Skeleton edit field, a button labeled Select is present. When selected, a standard input file dialog is displayed from which a skeleton table may be selected.

Qualifier(s):

/CDF=<cdf-path> (VMS)

-cdf <cdf-path> (UNIX & MS-DOS)

CDF edit field (Macintosh, Java/UNIX & Windows NT/95/98)

The file name of the CDF that will be created (overriding the file name in the skeleton table). If this qualifier is not specified, the CDF file name in the skeleton table is used. Do not specify an extension in the file name.

Macintosh, Java/UNIX & Windows NT/95/98: At the end of the CDF edit field, a

button labeled Select is present. When selected, a standard output file dialog is displayed in which a CDF name may be specified.

/[NO]LOG (VMS)

-[no]log (UNIX & MS-DOS)

Log progress check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not messages are displayed as the program executes.

/[NO]NEG2POSFP0 (VMS)

-[no]neg2posfp0 (UNIX & MS-DOS)

-0.0 to 0.0 check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not -0.0 is converted to 0.0 by the CDF library when encountered in a CDF. -0.0 is an illegal floating point value on VAXes and DEC Alphas running OpenVMS.

/[NO]DELETE (VMS)

-[no]delete (UNIX & MS-DOS)

Delete existing check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not the CDF will be deleted first if it already exists (essentially overwriting it).

/[NO]FILLVAL (VMS)

-[no]fillval (UNIX & MS-DOS)

Use FILLVAL check box (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies whether or not entries of the FILLVAL vAttribute are used to set the pad values for the corresponding variables. If this qualifier is specified, the FILLVAL vAttribute must exist and only those variables with an entry for the FILLVAL vAttribute will be affected.

/CACHE=(<sizes>) (VMS) -cache "<sizes>" (UNIX & MS-DOS)

Cache sizes edit field (Macintosh & Java/UNIX)

Cache edit field (Windows NT/95/98)

/ZMODE=<mode> (VMS)

-zmode <mode> (UNIX & MS-DOS)

zMode radio buttons (Macintosh, Java/UNIX & Windows NT/95/98)

Specifies the zMode that should be used with the skeleton table. If zMode is enabled, zVariables will be created from the definitions in the rVariables section. The zMode may be one of the following:

0 Indicates that zMode should be disabled.

1 Indicates that zMode/1 should be used. The dimension variances of rVariables will be preserved.

2 Indicates that zMode/2 should be used. The dimensions of rVariables having a variance of F [false] are removed.

/REPORT=(<types>) (VMS)

-report "<types>" (UNIX & MS-DOS)

Report info's/warnings/errors check boxes (Macintosh, Java/UNIX & Windows NT/95/98)

Example(s):

VMS:

$ SKELETONCDF FGGE3B

$ SKELETONCDF/NOLOG/CDF=[-.TEMP]FGGE3B_X/REPORT=(ERRORS) FGGE3B

UNIX:

% skeletoncdf fgge3b

% skeletoncdf -nolog -cdf ../fgge3b_x -report "errors" fgge3b

MS-DOS:

> skeletoncdf fgge3b

> skeletoncdf -nolog -cdf ..\fgge3b_x -report "errors" a:\fgge3b

VMS, UNIX & MS-DOS: Command line help is displayed when SkeletonCDF is executed without any arguments.

3.8.3 Creating the Skeleton Table

A skeleton table is a text file having .skt as a file extension. The normal method of creating and using a skeleton table would be to use SkeletonTable on an existing CDF that is similar to the CDF you want to create. Then edit the created skeleton table to meet your needs, and use SkeletonCDF to create the new CDF. The skeleton table could also be created from scratch with any text editor.

The format of the skeleton table is described in Appendix A.

3.9 CDFinquire

3.9.1 Introduction

The CDFinquire program displays the version of the CDF distribution being used, most configurable parameters, and the default toolkit qualifiers.

3.9.2 Executing the CDFinquire Program

Usage:

VMS:

$ CDFINQUIRE /ID [/[NO]PAGE]

UNIX:

% cdfinquire -id [-[no]page]

MS-DOS:[56]

> cdfinquire -id [-[no]page]

Macintosh:

Double-click on the CDFinquire icon.

Windows NT/95/98:

Double-click on the CDFso icon and select the CDFinquire option under the File menu.

Java/UNIX:

Type "java CDFToolsDriver" at the system prompt and select the CDFinquire option.

Macintosh, Java/UNIX & Windows NT/95/98: When the desired parameters/qualifiers have been selected in the dialog box, click on the Enter button to inquire the CDF distribution. Clicking on the Help button will display online help. Clicking on the Quit button terminates CDFinquire.

Parameter(s):

None

Qualifier(s):

/ID (VMS)

-id (UNIX & MS-DOS)

Id check box (Macintosh, Java/UNIX & Windows NT/95/98)

Causes the version of your CDF distribution and the default toolkit qualifiers to be displayed. This qualifier is required.

/[NO]PAGE (VMS)

-[no]page (UNIX & MS-DOS)

Page output check box (Macintosh & Java/UNIX)

Not applicable (Windows NT/95/98)

Specifies whether or not the output is displayed a page at a time. A prompt for the RETURN key will be issued after each page. A page is generally 22 lines of output.

Example(s):

VMS:

$ CDFINQUIRE/ID/PAGE

UNIX:

% cdfinquire -id -page

MS-DOS:

> cdfinquire -id -page

VMS, UNIX & MS-DOS: Command line help is displayed when CDFinquire is executed without any arguments.

3.9.3 Output from the CDFinquire Program

The version of your CDF distribution is displayed first followed by the configurable parameters and then the default toolkit qualifiers (in the style of the system being used).

3.10 CDFdir

3.10.1 Introduction

The CDFdir utility is used to display a directory listing of a CDF's files.[57] The dotCDF file is displayed first followed by the rVariable files and then the zVariable files (if either exist in a multi-file CDF) in numerical order.

3.10.2 Executing the CDFdir Program

The command line syntax for CDFdir is as follows:

Usage:

VMS:

$ CDFDIR <cdf-path>

UNIX:

% cdfdir <cdf-path>

MS-DOS:

> cdfdir <cdf-path>

NOTE: This tool is not supported by Macintosh and Windows NT/95/98.

Parameter(s):

<cdf-path> The file name of the CDF for which to display a directory listing (do not specify an extension).

Example(s):

VMS:

$ CDFDIR NCDS$DATA:GISS_WETL_CLIMATOLOGY

$ CDFDIR [-.TEMP]FGGE3B

UNIX:

% cdfdir ../cac_sst_blended

% cdfdir ~/CDFs/giss_wetl_climatology

MS-DOS:

> cdfdir ..\cac_sst

> cdfdir c:\cdfs\gisswetl

Help is displayed when CDFdir is executed without any arguments.

3.10.3 Output from the CDFdir Program

The format of the output from CDFdir is that of a directory listing on the operating system being used.

3.11 CDFbrowse

CDFbrowse has been replaced by CDFedit (see Section 3.2).[58]

3.12 CDFlist

CDFlist has been replaced by CDFexport (see Section 3.3).

3.13 CDFwalk

The functionallity of CDFwalk has been added to CDFexport (see Section 3.3).

Appendix A

Skeleton Table Format

A.1 Introduction

Skeleton tables are both created by and read by CDF utility programs. SkeletonTable creates a skeleton table by reading a CDF. SkeletonCDF creates a CDF by reading a skeleton table. In almost all cases the format of the skeleton tables read and written will be the same. Any differences are minor and will be described where appropriate.

The skeleton table has a free format (except where noted) - you need not be concerned with any column alignments, spaces between fields, or spaces between successive lines. However, certain syntax rules do apply to skeleton tables.

1. Lines are limited to 132 characters.

2. Keywords for the header section, gAttributes section, vAttributes section, rVariables section, and end section must always be specified (in that order). The zVariables section is optional - its keyword may be omitted.

3. An exclamation point (!) at any point signifies a comment until the end of the line. Any characters encountered after the exclamation point will be ignored. An exclamation point may begin a line (making the entire line a comment). Exclamation points inside delimited character strings are part of the string and do not cause the start of a comment.

4. Attribute and variable names must be delimited. Any character not in the name may be used as the delimiter with the following exceptions:

(a) Do not use an exclamation point (!) to delimit an attribute or variable name.

(b) Do not use a period (.) to delimit an attribute name in the variables section.

5. When specifying a character string attribute entry value, do not use a hyphen (-) to delimit the string or strings (if the string is split across one or more lines).

6. All items are referenced from one (1). These include gAttribute gEntry numbers and NRV variable index values.

In the descriptions that follow, optional fields are shown in brackets ([...]).

A.2 Header Section

The header section contains general information about the CDF. The format of the header section is as follows:

#header

CDF NAME: <cdf-name>

DATA ENCODING: <data-encoding>

MAJORITY: <variable-majority>

FORMAT: <cdf-format>

!	Variables	G.Attributes	V.Attributes	Records	Dims	Size
!	-----------	---------------	---------------	----------	-------	-----
	<rVars>/<zVars>	<gAttrs>	<vAttrs>	<n-recs>/z	<n-dims>	<dim-sizes>

The fields are defined as follows:

<cdf-name> The name of the CDF. When SkeletonTable creates a skeleton table, this will be the name of the corresponding CDF (not the full file name specified). When SkeletonCDF reads a skeleton table, this will be the name of the CDF created unless a CDF file name is specified on the command line. If the CDF name in the skeleton table is to be used, a full file name must be specified (if desired) or else the CDF will be created in the default/current directory.

<data-encoding> The data encoding of the CDF. When specifying a data encoding to the SkeletonCDF program, the following encodings are valid: HOST, NETWORK, VAX, ALPHAVMSd, ALPHAVMSg, ALPHAVMSi, SUN, SGi, DECSTATION, ALPHAOSF1, IBMRS, HP, PC, MAC, and NeXT. When a skeleton table is created by SkeletonTable, all of the above encodings with the exception of HOST are possible. Data encoding is described in Section 2.2.8.

<variable-majority> The variable majority of the CDF. This may be either ROW or COLUMN. Variable majority is described in Section 2.3.15.

<cdf-format> The format of the CDF. This may be either SINGLE or MULTI. CDF formats are described in Section 2.2.7. Note that this line is optional. Skeleton tables created by SkeletonTable in CDF V2.0 did not have this line because the single-file option did not exist. To allow SkeletonCDF to read skeleton tables created with SkeletonTable in CDF V2.0, this line was made optional. If omitted, SkeletonCDF will create a CDF with the default format for your CDF distribution. Consult your system manager to determine this default. SkeletonTable (in CDF V2.1 and beyond) always generates this line regardless of the version of the CDF being read.

<rVars> The number of rVariables in the CDF. SkeletonTable always places the correct number here. However, when SkeletonCDF reads a skeleton table, this value is ignored (but a place holder is necessary). The number of rVariables created is determined by the number of rVariable definitions in the rVariable definitions section.

<zVars> The number of zVariables in the CDF. SkeletonTable always places the correct number here. However, when SkeletonCDF reads a skeleton table, this value is ignored (but a place holder is necessary). The number of zVariables created is determined by the number of zVariable definitions in the zVariable definitions section.

<gAttrs> The number of gAttributes in the CDF. SkeletonTable always places the correct number here. However, when SkeletonCDF reads a skeleton ta- ble, this value is ignored (but a place holder is necessary). The number of gAttributes created is determined by the number of definitions in the gAttributes section.

<vAttrs> The number of vAttributes in the CDF. SkeletonTable always places the correct number here. However, when SkeletonCDF reads a skeleton table, this value is ignored (but a place holder is necessary). The number of vAttributes created is determined by the number of definitions in the vAttributes section.

<n-recs> The (maximum) number of rVariable records in the CDF. SkeletonTable always places the correct number here. However, when SkeletonCDF reads a skeleton table, this value is ignored (but a place holder is necessary). The number of records written to the CDF depends on whether or not any values are specified for variables. NRV variables are described in Section 2.3.10.

<n-dims> The number of dimensions for the rVariables in the CDF.

<dim-sizes> The dimension sizes for the rVariables in the CDF - one value per dimension. If the rVariables have zero (0) dimensions, this field would be left blank.

An example header section for a CDF with 2-dimensional rVariables follows:

#header

CDF NAME: sample2

DATA ENCODING: NETWORK

MAJORITY: ROW

FORMAT: SINGLE

!	Variables	G.Attributes	V.Attributes	Records	Dims	Size
!	-----------	---------------	---------------	----------	-------	----------
	14/0	18	4	1/z	2	180 360

If the rVariables had zero dimensions, the header section would be as follows:

#header

CDF NAME: sample0

DATA ENCODING: NETWORK

MAJORITY: ROW

FORMAT: SINGLE

!	Variables	G.Attributes	V.Attributes	Records	Dims	Size
!	-----------	---------------	---------------	----------	-------	-----
	14/0	18	4	1/z	0

A.3 gAttributes Section

The gAttributes section contains the definition of each gAttribute as well as any gEntries for those gAttributes. The format of the gAttributes section is as follows:

#GLOBALattributes

[<global-scope-attribute-definition>

<global-scope-attribute-definition>

<global-scope-attribute-definition>]

Where <global-scope-attribute-definition>, needless to say, is a gAttribute definition.

Zero or more gAttribute definitions are allowed. (There is no limit on the number of attributes that a CDF may have.) The format of each gAttribute definition is as follows:

Attribute	Entry	Data
Name	Number	Type	Value
-----------	-----------	-------	--------

<attr-name>	[<entry-n>:	<data-type>	<value>
	<entry-n>:	[<data-type>]	<value>
	<entry-n>:	[<data-type>]	<value>
	.	.	.
	.	.	.
	.	.	.
	<entry-n>:	[<data-type>]	<value>].	! Note the “.”

The fields are defined as follows:

<attr-name> The name of the gAttribute. The name must be delimited with a character not appearing in the name itself (e.g., "TITLE" or 'History'). The delimiting characters are not part of the gAttribute name in the CDF.

<entry-n> The gEntry number. Zero or more gEntries may be specified for a gAttribute, and there are no restrictions on the gEntry numbers that may be used (except that they must be greater than zero).

<data-type> The data type for the gEntry. The data type must be one of the following: CDF_BYTE, CDF_INT1, CDF_UINT1, CDF_INT2, CDF_UINT2, CDF_INT4, CDF_UINT4, CDF_REAL4, CDF_FLOAT, CDF_REAL8, CDF_DOUBLE, CDF_EPOCH, CDF_CHAR, or CDF_UCHAR. The <data-type> field is optional for all but the first gEntry specified. If omitted, the data type of the previous gEntry is assumed.

<value> The value(s) for the gEntry. A period (.) follows the value(s) of the last gEntry for a gAttribute.

Attribute Entry Values

An attribute entry can have more than one element of the specified data type. For character data types (CDF_CHAR and CDF_UCHAR), each character is the element of a string. The character string must be delimited with a character not appearing in the string itself, and the entire delimited string must be enclosed in braces (e.g., { "The CDF title." }). If the string will not fit on one line, it may be continued on additional lines. The substrings are each delimited with a unique character, and a dash (-) is placed at the end (after the terminating delimiter) of each line except the last one. For example,

{ "This is a longer " –

"CDF title that will" -

" not fit on one line." }

For non-character data types, the elements are enclosed in braces and separated by commas (e.g., { 1, 2, 3 }). If the elements will not all fit on one line, they may be continued on additional lines. For example,

{ 1.0, 2.0, 3.0, 4.0, 5.0,

6.0, 7.0, 8.0, 9.0, 10.0 }

Note that an individual element value may not be split across lines.

The format of a value for the CDF_EPOCH data type (which is also considered a non-character data type) is defined in Section 2.5.4. A CDF_EPOCH value may not be split across two lines.

Several example gAttribute definitions follow:

#GLOBALattributes

Attribute	Entry	Data
Name	Number	Type	Value
-----------	-----------	-------	--------

"TITLEa"	1:	CDF_CHAR	{ "CDAW-9A; SABRE" }.
"TITLEb"	1:	CDF_CHAR	{ "CDAW-9A; SABRE " - "Backscatter Radar, 20s." }.
"History"	1: 2:	CDF_CHAR	{ "CDF created 02-Jan-1961" } { "CDF modified 23-Oct-1964" }.
"TIMES"	1: 2:	CDF_EPOCH.	{ 04-Jul-1976 12:00:00.000, 31-Oct-1976 00:00:00.000 } { 25-Dec-1976 01:10:00.000, 01-Jan-1977 01:10:30.000 }.
&Factors&	1: 2: 3: 4: 5:	CDF_REAL4	{ 12.5 } { 17.4 } { 8.5 } { 7 } { 12 }.

A.4 vAttributes Section

The vAttributes section contains the names of the vAttributes in the CDF. Any rEntries or zEntries for these vAttributes are defined in the rVariables/zVariables sections (following the definition of the corresponding variable). The format of the vAttributes section is as follows:

#VARIABLEattributes

[<attribute-name>

<attribute-name>

<attribute-name>]

Where <attribute-name> is a vAttribute name delimited with a character not appearing in the name itself (e.g., "VALIDMIN" or 'Units'). The delimiting characters are not part of the vAttribute name in the CDF. There may be zero or more vAttribute names. (There is no limit on the number of attributes that a CDF may have.)

An example vAttributes section follows:

#VARIABLEattributes

"FIELDNAM"

"VALIDMIN"

"Units"

A.5 rVariables Section

The rVariables section contains the definition of each rVariable in the CDF, the values for any vAttribute rEntries associated with each rVariable, and (optionally) data values for those rVariables. The format of the rVariables section is as follows:

#variables

[<variable-definition>

<variable-definition>

<variable-definition>]

Where <variable-definition> is an rVariable definition. The format of each rVariable definition is as follows:

! Variable Data Number Record Dimension

! Name Type Elements Variance Variances

! ----------- ------- ------------ ------------ ---------------

<var-name> <var-data-type> <n-elems> <rec-vary> <dim-varys>

! Attribute Data

! Name Type Value

! ----------- ------- --------

[<attr-name> <entry-data-type> <entry-value>

<attr-name> <entry-data-type> <entry-value>

. . .

<attr-name> <entry-data-type> <entry-value>]. ! Note the "."

[ [<rec-num>:]<indices> = <value>

[<rec-num>:]<indices> = <value>

. .

[<rec-num>:]<indices> = <value>]

Each field is defined as follows:

<var-name> The name of the rVariable. The name must be delimited with a character not appearing in the name itself (e.g., "EPOCH" or 'Temperature'). The delimiting characters are not part of the rVariable name in the CDF.

<var-data-type> The data type for the rVariable. The data type must be one of the following: CDF_BYTE, CDF_INT1, CDF_UINT1, CDF_INT2, CDF_UINT2, CDF_INT4, CDF_UINT4, CDF_REAL4, CDF_FLOAT, CDF_REAL8, CDF_DOUBLE, CDF_EPOCH, CDF_CHAR, or CDF_UCHAR.

<n-elems> The number of elements of the data type. For character data types (CDF_CHAR and CDF_UCHAR), this is the number of characters in each string. For non-character data types, this value must be one (1).

<rec-vary> The record variance of the rVariable. This must be either T (the values vary from record to record) or F (the values do not vary from record to record).

<dim-varys> The dimension variances of the rVariable. For each dimension there must be either a T (the values vary along that dimension) or F (the values do not vary along that dimension). Each dimension variance must be separated by at least one space. If the rVariables have zero dimensions, this field would be left blank.

<attr-name> The name of the vAttribute for which to specify an rEntry for this rVariable. The vAttribute must have been specified in the vAttributes section. The name must be delimited with a character not appearing in the name itself (e.g., "SCALEMAX" or 'range'). The delimiting characters are not part of the vAttribute name in the CDF.<entry-data-type> The data type for the vAttribute rEntry. The data type must be one of the following: CDF_BYTE, CDF_INT1, CDF_UINT1, CDF_INT2, CDF_UINT2, CDF_INT4, CDF_UINT4, CDF_REAL4, CDF_FLOAT, CDF_REAL8, CDF_DOUBLE, CDF_EPOCH, CDF_CHAR, or CDF_UCHAR.

<entry-value> The value(s) for the vAttribute rEntry. The format of attribute entry values is described in Section A.3.

NOTE: The last rEntry MUST be followed by a period (.). If no rEntries

are specified for an rVariable, the period must still be present.

<rec-num> The record number of an rVariable value. This will be present only for record-variant (RV) rVariables.

<indices> The indices of an rVariable value. The indices are enclosed in brackets and separated by commas (e.g., [23,1] or [1,80]). If the rVariables have zero dimensions, [] would be specified (the brackets are still required).

<value> The value at the given record/indices. For character data types (CDF_CHAR or CDF_UCHAR) the string must be delimited with a unique character and enclosed in braces ({...}) in the same manner as for an attribute entry for a character data type. For non-character data types the value is not enclosed in braces (the braces are not necessary because there can only be one element). The format for CDF_EPOCH values is described in Section 2.5.4.

The vAttribute rEntries are optional. If omitted, the terminating period is still required. The rVariable values are also optional.

Several sample rVariable definitions for a CDF with 2-dimensional rVariables follow:

! Variable Data Number Record Dimension

! Name Type Elements Variance Variances

! ----------- ------- ------------ ------------ ---------------

! “Latitude” CDF_REAL4 1 F F T

! Attribute Data

! Name Type Value

! ----------- ------- --------

“VALIDMIN” CDF_REAL4 { -90.0 }

“VALIDMAX” CDF_REAL4 { 90.0 }

“scale” CDF_REAL4 { -60.0, 60.0 }.

[1,1] = -60.0

[1,2] = -30.0

[1,3] = 0.0

[1,4] = 30.0

[1,5] = 60.0

! Variable Data Number Record Dimension

! Name Type Elements Variance Variances

! ----------- ------- ------------ ------------ ---------------

! “EPOCH” CDF_EPOCH 1 F F F

! Attribute Data

! Name Type Value

! ----------- ------- --------

“scale” CDF_REAL4 { 10-Oct-1991 00:00:00.000,

20-Oct-1991 23:59:59.999 }.

! Variable Data Number Record Dimension

! Name Type Elements Variance Variances

! ----------- ------- ------------ ------------ ---------------

! ‘Tmp’ CDF_INT2 1 T T T

! Attribute Data

! Name Type Value

! ----------- ------- --------

‘Fieldname’ CDF_CHAR { "Temperature (C)" }.

! Variable Data Number Record Dimension

! Name Type Elements Variance Variances

! ----------- ------- ------------ ------------ ---------------

! “pres_lv1” CDF_REAL4 1 T F F

! Attribute Data

! Name Type Value

! ----------- ------- --------

. ! no attribute entries

1:[1,1] = 1013.1

2:[1,1] = 1015.0

3:[1,1] = 1012.3

A sample variable definition for a CDF with 0-dimensional rVariables follows:

! Variable Data Number Record Dimension

! Name Type Elements Variance Variances

! ----------- ------- ------------ ------------ ---------------

! “Latitude” CDF_REAL4 1 F

! Attribute Data

! Name Type Value

! ----------- ------- --------

“VALIDMIN” CDF_REAL4 { -90.0 }

“VALIDMAX” CDF_REAL4 { 90.0 }.

[] = -12.3

A.6 zVariables Section

The optional zVariables section contains the definition of each zVariable in the CDF, the values for any vAttribute zEntries associated with each zVariable, and (optionally) data values for those zVariables. The format of the zVariables section is as follows:

#zVariables

[<variable-definition>

<variable-definition>

<variable-definition>]

Where <variable-definition> is a zVariable definition. The format of each zVariable definition is as follows:

! Variable Data Number Record Dimension

! Name Type Elements Dims Sizes Variance Variances

! ----------- ------- ------------- ------- ------- ------------ --------------

<var-name> <var-data-type> <n-elems> <dims> <sizes> <rec-vary> <dim-varys>

! Attribute Data

! Name Type Value

! ----------- ------- --------

[<attr-name> <entry-data-type> <entry-value>

<attr-name> <entry-data-type> <entry-value>

. . .

<attr-name> <entry-data-type> <entry-value>]. ! Note the "."

[ [<rec-num>:]<indices> = <value>

[<rec-num>:]<indices> = <value>

. .

[<rec-num>:]<indices> = <value>]

Each field is defined as follows:

<var-name> The name of the zVariable. The name must be delimited with a character not appearing in the name itself (e.g., "EPOCH" or 'Temperature'). The delimiting characters are not part of the zVariable name in the CDF.

<var-data-type> The data type for the zVariable. The data type must be one of the following: CDF_BYTE, CDF_INT1, CDF_UINT1, CDF_INT2, CDF_UINT2, CDF_INT4, CDF_UINT4, CDF_REAL4, CDF_FLOAT, CDF_REAL8, CDF_DOUBLE, CDF_EPOCH, CDF_CHAR, or CDF_UCHAR.

<n-elems> The number of elements of the data type. For character data types (CDF_CHAR and CDF_UCHAR) this is the number of characters in each string. For non-character data types this value must be one (1).

<dims> The number of dimensions for the zVariable.

<sizes> The dimension sizes - one value per dimension. If the zVariable has zero (0) dimensions, this field would be left blank.

<rec-vary> The record variance of the zVariable. This must be either T (the values vary from record to record) or F (the values do not vary from record to record).

<dim-varys> The dimension variances of the zVariable. For each dimension there must be either a T (the values vary along that dimension) or F (the values do not vary along that dimension). Each dimension variance must be separated by at least one space. If the zVariable has zero dimensions, this field would be left blank.

<attr-name> The name of the vAttribute for which to specify a zEntry for this zVariable. The vAttribute must have been specified in the vAttributes section. The name must be delimited with a character not appearing in the name itself (e.g., "SCALEMAX" or 'range'). The delimiting characters are not part of the vAttribute name in the CDF.

<entry-data-type> The data type for the vAttribute zEntry. The data type must be one of the following: CDF_BYTE, CDF_INT1, CDF_UINT1, CDF_INT2, CDF_UINT2, CDF_INT4, CDF_UINT4, CDF_REAL4, CDF_FLOAT, CDF_REAL8, CDF_DOUBLE, CDF_EPOCH, CDF_CHAR, or CDF_UCHAR.

<entry-value> The value(s) for the vAttribute zEntry. The format of attribute entry values is described in Section A.3.

NOTE: The last zEntry MUST be followed by a period (.). If no zEntries are specified for a zVariable, the period must still be present.

<rec-num> The record number of an zVariable value. This will be present only for record-variant (RV) zVariables.

<indices> The indices of an zVariable value. The indices are enclosed in brackets and separated by commas (e.g., [23,1] or [1,80]). If the zVariable has zero dimensions, [] would be specified (the brackets are still required).

The vAttribute zEntries are optional. If omitted, the terminating period is still required. The zVariables values are also optional.

Several sample zVariable definitions follow:

! Variable Data Number Record Dimension

! Name Type Elements Dims Sizes Variance Variances

! ----------- ------- ------------- ------- ------- ------------ --------------

“Instrument” CDF_CHAR 10 0 F

! Attribute Data

! Name Type Value

! ----------- ------- --------

“FIELDNAM” CDF_CHAR { "Measuring instrument" }.

[] = { "Gonkulator" }

! Variable Data Number Record Dimension

! Name Type Elements Dims Sizes Variance Variances

! ----------- ------- ------------- ------- ------- ------------ --------------

“Ticks” CDF_BYTE 1 1 3 T T

! Attribute Data

! Name Type Value

! ----------- ------- --------

. ! no attribute entries

1:[1] = 1

1:[2] = 2

1:[3] = 3

2:[1] = 3

2:[2] = 2

2:[3] = 1

! Variable Data Number Record Dimension

! Name Type Elements Dims Sizes Variance Variances

! ----------- ------- ------------- ------- ------- ------------ --------------

“WIND VELOCITY” CDF_REAL4 1 3 360 180 10 T T T T

! Attribute Data

! Name Type Value

! ----------- ------- --------

“FIELDNAM” CDF_CHAR { "Wind velocity." }

“VALIDMIN” CDF_REAL4 { 0.0 }

“VALIDMAX” CDF_REAL4 { 300.0 }

“UNITS” CDF_CHAR { "Knots" }

“FORMAT” CDF_CHAR { "F9.1" }.

A.7 End Section

This section simply consists of the keyword #end. This section is required.

A.8 Example Skeleton Table

An example skeleton table containing rVariables and zVariables follows:

! Skeleton table for the "example2" CDF.

! Generated: Thursday, 17-Nov-1994 14:07:58

! CDF created/modified by CDF V2.4.10

! Skeleton table created by CDF V2.5.0

#header

CDF NAME: example2

DATA ENCODING: NETWORK

MAJORITY: ROW

FORMAT: SINGLE

! Variables G.Attributes V.Attributes Records Dims Sizes

! --------- ------------ ------------ ------- ---- -----

4 1 7 1 2 11 7

#GLOBALattributes

! Attribute Entry Data

! Name Number Type Value

! --------- ------ ---- -----

"TITLE" 1: CDF_CHAR { "Title for example2 CDF." } .

#VARIABLEattributes

"FIELDNAM"

"VALIDMIN"

"VALIDMAX"

"SCALEMIN"

"SCALEMAX"

"UNITS"

"FORMAT"

#variables

! Variable Data Number Record Dimension

! Name Type Elements Variance Variances

! -------- ---- -------- -------- ---------

"EPOCH" CDF_EPOCH 1 T F F

! Attribute Data

! Name Type Value

! -------- ---- -----

"FIELDNAM" CDF_CHAR { "Time since 0 A.D. " }

"VALIDMIN" CDF_EPOCH { 01-Jan-0000 00:00:00.000 }

"VALIDMAX" CDF_EPOCH { 01-Jan-2089 00:00:00.000 }

"SCALEMIN" CDF_EPOCH { 01-Apr-1986 07:00:00.000 }

"SCALEMAX" CDF_EPOCH { 01-Apr-1986 23:00:00.000 }

"UNITS" CDF_CHAR { "milliseconds (UT) " }

"FORMAT" CDF_CHAR { "E14.0 " } .

! Variable Data Number Record Dimension

! Name Type Elements Variance Variances

! -------- ---- -------- -------- ---------

"LONGITUD" CDF_REAL4 1 F T F

! Attribute Data

! Name Type Value

! -------- ---- -----

"FIELDNAM" CDF_CHAR { "Longitude variable " }

"VALIDMIN" CDF_REAL4 { 0.0 }

"VALIDMAX" CDF_REAL4 { 180.0 }

"SCALEMIN" CDF_REAL4 { -50.0 }

"SCALEMAX" CDF_REAL4 { 50.0 }

"UNITS" CDF_CHAR { "Degrees " }

"FORMAT" CDF_CHAR { "F8.3 " } .

[1,1] = -50.0

[2,1] = -40.0

[3,1] = -30.0

[4,1] = -20.0

[5,1] = -10.0

[6,1] = 0.0

[7,1] = 10.0

[8,1] = 20.0

[9,1] = 30.0

[10,1] = 40.0

[11,1] = 50.0

! Variable Data Number Record Dimension

! Name Type Elements Variance Variances

! -------- ---- -------- -------- ---------

"LATITUDE" CDF_REAL4 1 F F T

! Attribute Data

! Name Type Value

! -------- ---- -----

"FIELDNAM" CDF_CHAR { "Latitude variable " }

"VALIDMIN" CDF_REAL4 { 0.0 }

"VALIDMAX" CDF_REAL4 { 90.0 }

"SCALEMIN" CDF_REAL4 { -30.0 }

"SCALEMAX" CDF_REAL4 { 30.0 }

"UNITS" CDF_CHAR { "Degrees " }

"FORMAT" CDF_CHAR { "F8.3 " } .

[1,1] = -30.0

[1,2] = -20.0

[1,3] = -10.0

[1,4] = 0.0

[1,5] = 10.0

[1,6] = 20.0

[1,7] = 30.0

! Variable Data Number Record Dimension

! Name Type Elements Variance Variances

! -------- ---- -------- -------- ---------

"TEMPERATURE" CDF_INT4 1 T T T

! Attribute Data

! Name Type Value

! -------- ---- -----

"FIELDNAM" CDF_CHAR { "Temperature " }

"VALIDMIN" CDF_INT4 { 0 }

"VALIDMAX" CDF_INT4 { 50 }

"SCALEMIN" CDF_INT4 { 0 }

"SCALEMAX" CDF_INT4 { 10 }

"UNITS" CDF_CHAR { "Deg C " }

"FORMAT" CDF_CHAR { "I2 " } .

#zVariables

! Variable Data Number Record Dimension

! Name Type Elements Dims Sizes Variance Variances

! -------- ---- -------- ---- ----- -------- ---------

"BIAS" CDF_INT4 1 0 T

! Attribute Data

! Name Type Value

! -------- ---- -----

"FIELDNAM" CDF_CHAR { "Correction bias for temperature" }

"VALIDMIN" CDF_INT4 { -5 }

"VALIDMAX" CDF_INT4 { 5 }

"UNITS " CDF_CHAR { "deg C " }

"FORMAT " CDF_CHAR { "I2 " } .

1:[] = 34

2:[] = 28

3:[] = 17

! Variable Data Number Record Dimension

! Name Type Elements Dims Sizes Variance Variances

! -------- ---- -------- ---- ----- -------- ---------

"Coefficients" CDF_REAL4 1 1 3 F T

! Attribute Data

! Name Type Value

! -------- ---- -----

"FIELDNAM" CDF_CHAR { "Temperature model coefficients." }

"FORMAT " CDF_CHAR { "F9.1 " } .

[1] = -0.0254

[2] = 14.2338

[3] = -9.9444

! Variable Data Number Record Dimension

! Name Type Elements Dims Sizes Variance Variances

! -------- ---- -------- ---- ------- -------- ---------

"TMP-model" CDF_REAL4 1 2 360 180 T T T

! Attribute Data

! Name Type Value

! -------- ---- -----

"FIELDNAM" CDF_CHAR { "Temperature model." }

"VALIDMIN" CDF_REAL4 { -20.0 }

"VALIDMAX" CDF_REAL4 { 50.0 }

"SCALEMIN" CDF_REAL4 { 0.0 }

"SCALEMAX" CDF_REAL4 { 30.0 }

"UNITS " CDF_CHAR { "deg C " }

"FORMAT " CDF_CHAR { "F9.6 " } .

#end

Appendix B

IDL Support

B.1 Introduction

The CDF distribution includes a set of IDL functions/procedures that allow access to the CDF library (hereafter referred to as the CDF/IDL interface). The functions/procedures are used in the same manner as the Standard and Internal Interfaces are used in programs written in C.[59] CDFs can be both read and written/modified.

Research Systems, Inc. (the developers of IDL) have also implemented an interface to CDF that is part of the IDL product. It differs from the interface provided with the CDF distribution in that it is intended more for the non-programmer (and is functionally similar to other interfaces they provide). Because IDL's CDF interface relies on a version of the CDF library being linked into the IDL executable, IDL's interface may lag behind the most recent CDF distribution. This can cause problems as new features are added to the CDF library (which IDL's interface will not know about).

CDF's interface relies on IDL's support of dynamic linking. IDL in turn relies on the operating system being used to support dynamic linking in a reasonable way. Currently, only the VAX (OpenVMS), DEC Alpha (OpenVMS & OSF/1), Sun (SunOS & SOLARIS), HP (HP-UX), SGi (IRIX 5.x & 6.x), and IBM RS6000 (AIX) support dynamic linking in a way that makes it possible to use CDF's interface in IDL. Because IDL's CDF interface is built into the IDL executable, it does not rely on dynamic linking and is therefore available on every machine on which IDL is supported (assuming CDF is also supported on that machine).

B.2 Using CDF's IDL Interface

This section assumes that you are using the "definitions" file provided with the CDF distribution (and that it has been properly configured and named by your system manager). The "definitions" file is a command file named DEFINITIONS.COM on VMS systems and a script file named definitions.<shell-type> on UNIX systems where <shell-type> is the type of shell being used: C for the C-shell (csh and tcsh), K for the Korn (ksh), BASH, and POSIX shells, and B for the Bourne shell (sh). The "definitions" file defines the logical name IDL STARTUP on VMS systems and the environment variable IDL STARTUP on UNIX systems to the full directory path of an IDL startup file provided with the CDF distribution. When IDL is started, this startup file is automatically executed (because IDL STARTUP is defined). The startup file performs the following functions. . .

1. Makes known to IDL the functions/procedures that are used to call the CDF library (and perform other utility operations).

2. Sets IDL's internal paths. These are used when searching for a batch file to be executed or when locating online help files.

3. Executes one or more batch files that creates a number of local variables necessary for calling CDF functions/procedures and then interpreting the results. Check with your system administrator to see which batch files are being executed.

A list of messages should be displayed indicating the CDF functions/procedures that have been compiled.

If you are already using your own startup file (pointed to by your definition of IDL STARTUP), you should remove the definition of IDL STARTUP from the CDF "definitions" file being used and do one of the following. . .

1. Add the contents of the CDF/IDL startup file to your own startup file.

2. Have your startup file execute the CDF/IDL startup file.

The definition of IDL STARTUP in the CDF "definitions" file being used points to the location of the CDF/IDL startup file.

B.3 CDF "Include" Files

A number of parameters (macro constants) are necessary when calling functions in the CDF library from a

C program. These parameters are defined in the cdf.h header file. In a Fortran application the cdf.inc

include file defines these parameters. There are three available methods for making these parameters known when calling CDF functions/procedures in IDL: constant structures, mapping functions, and individual local variables.

B.3.1 Constant Structures

A batch file,[60] cdf0x.pro, is available that creates a set of IDL structure variables that contain the CDF parameter values. Each structure variable contains one or more tags (fields) which are initialized to the proper value. The following structure variables are created by cdf0x.pro.[61]

Structure Variable	Contents
CDFx	General CDF constants
CDFdt	Data type constants
CDFen	Encoding constants
CDFde	Decoding constants
CDFic	Informational status code constants
CDFwc	Warning status code constants
CDFec	Error status code constants
CDFiif	Internal Interface function constants
CDFiix	General Internal Interface item constants
CDFiia	Internal Interface attribute item constants
CDFiie	Internal Interface entry item constants
CDFiir	Internal Interface rVariable item constants
CDFiiz	Internal Interface zVariable item constants

To display the contents of a particular structure variable, use the IDL help command with the /structures keyword. For example. . .

IDL> @cdf0x

IDL> help, /structures, cdfx

** Structure <40023808>, 52 tags, length=208, refs=1:

CDF_MIN_DIMS LONG 0

CDF_MAX_DIMS LONG 10

IDL>

The following example will show how the structure variables created by cdf0x.pro would be used.

IDL> @cdf0x

IDL> dimSizes = lonarr(CDFx.CDF_MAX_DIMS)

IDL> status = CDFcreate ('test1', 0L, dimSizes, CDFen.NETWORK_ENCODING, $

IDL> CDFx.ROW_MAJOR, id)

IDL> if (status lt CDFic.CDF_OK) ...

IDL> status = CDFattrCreate (id, 'TITLE', CDFx.GLOBAL_SCOPE, attrNum)

IDL> if (status lt CDFic.CDF_OK) ...

IDL> status = CDFattrPut (id, attrNum, 0L, CDFdt.CDF_CHAR, 6L, 'Test 1')

IDL> if (status lt CDFic.CDF_OK) ...

IDL> status = CDFclose (id)

IDL> if (status lt CDFic.CDF_OK) ...

B.3.2 Mapping Functions

Three mapping functions are available that take as an argument a string containing the name of a parameter and return the numerical value for that parameter as an IDL longword. These mapping function are made known to IDL in the CDF/IDL startup file.

Mapping Function	Purpose
MCP	Map general CDF parameters
MSC	Map status code constants
MII	Map Internal Interface constants

For example, the status code value for NO_SUCH_CDF would be retrieved as follows. . .

IDL> status = CDFopen ('test1', id)

IDL> if (status eq MSC('NO_SUCH_CDF')) print, "CDF not found..."

The use of these mapping functions will add execution overhead because of the number of string comparisons that must be performed by the functions to locate the proper parameter value.

B.3.3 Individual Local Variables

Three batch files are available that define a local variable for each CDF parameter that might be needed. Unfortunately, IDL limits the number of local variables that may be defined in any one function/procedure. This limit will almost certainly be reached if you have to include one or more of these batch files. For this reason one of the two previously described methods should be used to define the necessary CDF parameters.

NOTE: These batch files are maintained in the CDF distribution only in the event that IDL might raise the limit on local variables.

B.4 On-Line Help

IDL provides an on-line help facility to which help for user written procedures/functions can be added.[62] A specially formatted file is provided with the CDF distribution that contains on-line help for the procedures/functions in the CDF/IDL interface. This file is named cdf26cdfif.help and is located in the "help" directory of the CDF distribution. If you are using the appropriate "definitions" file, IDL will be able to locate this file when online help is requested. Choose the topic called CDF26CDFIF rather than CDF. (CDF provides online help for IDL's CDF interface - not the interface provided with the CDF distribution.)

B.5 Available Functions

The CDF functions/procedures available at the IDL command line exactly mirror the Standard and Internal Interface functions available for a program written in C.[63] The CDF C Reference Manual describes the functionality of each in detail. The syntax required when calling each function is as follows. . .

IDL> status = CDFlib (fnc1, ...)

IDL> status = CDFcreate (CDFpath, numDims, dimSizes, encoding, majority, id)

IDL> status = CDFopen (CDFpath, id)

IDL> status = CDFdoc (id, version, release, copyright)

IDL> status = CDFinquire (id, numDims, dimSizes, encoding, majority, $

IDL> maxRec, numVars, numAttrs)

IDL> status = CDFclose (id)

IDL> status = CDFdelete (id)

IDL> status = CDFerror (status, text)

IDL> status = CDFattrCreate (id, attrName, attrScope, attrNum)

IDL> status = CDFattrRename (id, attrNum, attrName)

IDL> status = CDFattrInquire (id, attrNum, attrName, attrScope, maxEntry)

IDL> status = CDFattrEntryInquire (id, attrNum, entryNum, dataType, numElems)

IDL> status = CDFattrPut (id, attrNum, entryNum, dataType, numElems, value)

IDL> status = CDFattrGet (id, attrNum, entryNum, value)

IDL> status = CDFvarCreate (id, varName, dataType, numElems, recVary, dimVarys, varNum)

IDL> status = CDFvarRename (id, varNum, varName)

IDL> status = CDFvarInquire (id, varNum, varName, dataType, numElems, recVary, dimVarys)

IDL> status = CDFvarPut (id, varNum, recNum, indices, value)

IDL> status = CDFvarGet (id, varNum, recNum, indices, value)

IDL> status = CDFvarHyperPut (id, varNum, recStart, recCount, recInterval, $

indices, counts, intervals, buffer)

IDL> status = CDFvarHyperGet (id, varNum, recStart, recCount, recInterval, $

IDL> indices, counts, intervals, buffer)

IDL> status = CDFvarClose (id, varNum)

IDL> attrNum = CDFattrNum (id, attrName)

IDL> varNum = CDFvarNum (id, varName)

IDL> epoch = computeEPOCH (year, month, day, hour, minute, second, millisecond)

IDL> EPOCHbreakdown, epoch, year, month, day, hour, minute, second, millisecond

IDL> epoch = parseEPOCH (epochString)

IDL> epoch = parseEPOCH1 (epochString)

IDL> epoch = parseEPOCH2 (epochString)

IDL> epoch = parseEPOCH3 (epochString)

IDL> encodeEPOCH, epoch, epochString

IDL> encodeEPOCH1, epoch, epochString

IDL> encodeEPOCH2, epoch, epochString

IDL> encodeEPOCH3, epoch, epochString

IDL> encodeEPOCHx, epoch, format, epochString

The IDL data types to use for integer arguments are always longwords or arrays of longwords using IDL's data type of TYP LONG.[64] Attribute entries and variable values should have the data types corresponding their CDF data types. CDF file names and variable/attribute names are IDL character strings. CDFid and CDFstatus are also longwords. The CDF C Reference Manual may be used as a guide (especially for CDFlib). Arguments passed to the CDF functions/procedures must obviously be created and initialized before the call. Arrays of longwords are necessary for dimension sizes, variances, etc.[65] Arguments returned by the CDF functions will be created to be of the proper data type and size (they do not have to be created before calling the CDF function).

Also provided are two functions, row to col and col to row, that may be used to change the majority of

an array (or arrays) of values. This function is necessary because CDF can store variable values in either row or column major order. The syntax of row to col is as follows. . .

IDL> status = row_to_col (inArray, outArray, numDims, dimSizes, numBytes, arrayCount)

where. . .

inArray The array (or arrays) of values to convert - row major ordering. Any valid IDL data type is allowed.

OutArray The converted array (or arrays) of values - column major ordering. This array will be created by row to col.

NumDims The number of dimensions in the array (or arrays). This value must be a longword.

DimSizes The size of each dimension. This must be an array of longwords - one longword per dimension.

NumBytes The number of bytes in each value. This value must be a longword.

ArrayCount The number of arrays to convert. The order of the arrays will not be affected. This value must be a longword.

Status Completion status code. This value will be a longword. The possible values are defined in cdf1.pro.

Multiple arrays (records) of CDF variable values should always be stored with the last dimension of the IDL array corresponding to the record number. For example, assume a CDF variable with two dimensions whose sizes are [180,360]. If 50 records are to be stored, an IDL array with three dimensions whose sizes are [180,360,50] should be used. If the CDF variables have row major ordering, row to col would be called with numDims set to 2, dimSizes set to [180,360], and arrayCount set to 50.

The syntax of col to row is as follows. . .

IDL> status = col_to_row (inArray, outArray, numDims, dimSizes, numBytes, arrayCount)

where. . .

inArray The array (or arrays) of values to convert - column major ordering. Any valid IDL data type is allowed.

OutArray The converted array (or arrays) of values - row major ordering. This array will be created by col to row.

NumDims The number of dimensions in the array (or arrays). This value must be a longword.

DimSizes The size of each dimension. This must be an array of longwords - one longword per dimension.

NumBytes The number of bytes in each value. This value must be a longword.

ArrayCount The number of arrays to convert. The order of the arrays will not be affected. This value must be a longword.

Status Completion status code. This value will be a longword. The possible values are defined in cdf1.pro.

Col_to_row would be used in those cases where an array of values created by IDL (in column-major ordering)

are to be written to a row-major CDF.

B.6 Example IDL Session

The following IDL session will open a CDF (unsuccessfully at first - typo), add an entry to the MODS gAttribute, and then close the CDF.

IDL> @cdf0x

IDL> status = CDFlib (CDFiif.OPEN_, CDFiix.CDF_, 'yrdy3', id, CDFiif.NULL_)

IDL> status = CDFerror (status, text)

IDL> print, text

NO_SUCH_CDF: The specified CDF does not exist.

IDL> status = CDFlib (CDFiif.OPEN_, CDFiix.CDF_, 'test2', id, CDFiif.NULL_)

IDL> status = CDFerror (status, text)

IDL> print, text

CDF_OK: Function completed successfully.

IDL> status = CDFlib (CDFiif.SELECT_, CDFiia.ATTR_NAME_, 'MODS', $

IDL> CDFiif.GET_, CDFiia.ATTR_MAXgENTRY_, maxEntry, $

IDL> CDFiif.NULL_)

IDL> status = CDFerror (status, text)

IDL> print, text

CDF_OK: Function completed successfully.

IDL> status = CDFlib (CDFiif.SELECT_, CDFiie.gENTRY_, maxEntry + 1, $

IDL> CDFiif.PUT_, CDFiie.gENTRY_DATA_, CDFdt.CDF_CHAR, 14L, $

IDL> 'Useless update', $

IDL> CDFiif.NULL_) IDL> status = CDFerror (status, text)

IDL> print, text

CDF_OK: Function completed successfully.

IDL> status = CDFclose (id)

IDL> status = CDFerror (status, text)

IDL> print,text

CDF_OK: Function completed successfully.

As you can see, checking the return status from each call to the CDF library can be fairly tedious. A procedure such as the following could be used to ease status code checking. . .

pro checkstatus, status

@cdf0x

if (status lt CDFic.CDF_OK) then begin

statusT = CDFerror (status, text)

print, text

endif

return

end

The first part of the sample IDL session could then be as follows. . .

IDL> .run checkstatus

IDL> @cdf0x

IDL> status = CDFlib (CDFiif.OPEN_, CDFiix.CDF_, 'yrdy3', id, $

IDL> CDFiif.NULL_)

IDL> checkstatus, status

NO_SUCH_CDF: The specified CDF does not exist.

IDL> checkstatus, CDFlib (CDFiif.OPEN_, CDFiix.CDF_, 'test2', id, $

IDL> CDFiif.NULL_)

As you can see, a call to a CDF function can be embedded in a call to checkstatus.

Appendix D

Sample Java and C Programs

D.1 Create CDFs

This program creates a couple of test CDF files. The first file, test.cdf, is filled with some global/variable attributes, entries and zVariables. Data values are put into variables and copied from one variable to another. The second file, test1.cdf, is created to hold two copied and duplicated variables from the first file.

import java.io.*;

import java.text.*;

import java.util.*;

import gsfc.nssdc.cdf.*;

import gsfc.nssdc.cdf.util.*;

/**

* This test program demonstrates how to create a single-file CDF

* called test.cdf. It also copies a variable along with data out of

* test.cdf and creates a new single-file CDF called test1.cdf.

* Thie program demonstrates the following techniques:

* - how to create a variable

* - how to create a global attribute

* - how to create a variable attribute

* - how to create a global variable attribute entry

* - how to create a variable attribute entry

* - how to add data to a variable

* - how to delete a variable attribute

* - how to rename a variable

* - how to rename a variable attribute

* - how to copy a variable with or without data

* - how to delete data (records) out of a variable

* - how to set options that are available with a CDF file and a variable

public class CreateCDF implements CDFConstants{

public static void main(String[] args) {

CDF cdf = null,

cdf1 = null;

try {

/******************************************************************/

/* If the file to be created is a multifile (not a single file), */

/* the following restrictions apply: */

/* */

/* - CDF file extension is not allowed (i.e. .cdf) */

/* - Compression and sparse records are not allowed */

/* - Deleting a variable is not allowed */

/******************************************************************/

File cdfFile = new File("test.cdf");

if (cdfFile.exists()) cdfFile.delete();

cdfFile = new File("test1.cdf");

if (cdfFile.exists()) cdfFile.delete();

cdf = CDF.create("test");

cdf1 = CDF.create("test1");

// Any write/put operation on a read-only file throws an exception.

// NOTE:

// If a file is open for creation, READONLYon flag is

// ignored. The READONLYon flag only works if a CDF file

// is opened with the open() method. Thus the READONLYon

// flag set below is ignored.

cdf.selectReadOnlyMode(READONLYon);

cdf.setFormat(SINGLE_FILE); // Set to signle-file CDF

/*************************************************/

/* Set the information/warning message flag */

/* - By default, this flag is turned off */

/* - setInfoWarningOn() turns on the flag */

/* - setInfoWarningOff() turns off the flag */

/*************************************************/

// cdf.setInfoWarningOn();

/*******************************************/

/* Create global and variable attributes */

/*******************************************/

Attribute

project = Attribute.create(cdf, "Project", GLOBAL_SCOPE),

pi = Attribute.create(cdf, "PI", GLOBAL_SCOPE),

test = Attribute.create(cdf, "Test", GLOBAL_SCOPE),

validMin = Attribute.create(cdf, "VALIDMIN", VARIABLE_SCOPE),

validMax = Attribute.create(cdf, "VALIDMAX", VARIABLE_SCOPE),

snafu = Attribute.create(cdf, "snafu", VARIABLE_SCOPE),

dummy = Attribute.create(cdf, "dummy", VARIABLE_SCOPE);

System.err.println("Created attributes.");

/**********************/

/* Create variables */

/**********************/

long numElements = 1,

numDims = 1,

dimVary[] = {VARY},

noDimVary[] = {NOVARY},

dimVariance1[] = {VARY, VARY},

dimVariance2[] = {VARY, NOVARY};

Variable

latitude = Variable.create(cdf, "Latitude",

CDF_INT1,

1, 1, new long [] {3},

NOVARY, /* recVary */

new long [] {VARY}),

latitude1 = Variable.create(cdf, "Latitude1",

CDF_UINT1,

1, 1, new long [] {3},

VARY,

new long [] {NOVARY}),

longitude = Variable.create(cdf, "Longitude",

CDF_INT2,

numElements, numDims,

new long [] {3}, /* dimSizes */

VARY, /* recVary */

new long [] {VARY}),

longitude1 = Variable.create(cdf, "Longitude1",

CDF_UINT2,

numElements, numDims,

new long [] {3}, /* dimSizes */

VARY, /* recVary */

dimVary), /* dimVary */

delta = Variable.create(cdf, "Delta",

CDF_INT4,

1, 2, new long [] {3,2},

VARY, dimVariance1),

time = Variable.create(cdf, "Time",

CDF_UINT4,

1, 2, new long [] {3,2},

VARY, dimVariance1),

dvar = Variable.create(cdf, "dvar", CDF_INT2,

1, 1, new long [] {3},

NOVARY,

new long [] {NOVARY}),

name = Variable.create(cdf, "Name",

CDF_CHAR,

10, 1, new long [] {2},

VARY,

new long [] {VARY}),

temp = Variable.create(cdf, "Temp", CDF_FLOAT,

1, 1, new long [] {3},

VARY,

new long [] {VARY}),

temp1 = Variable.create(cdf, "Temp1", CDF_REAL4,

1, 1, new long [] {3},

VARY,

new long [] {VARY}),

temp2 = Variable.create(cdf, "Temperature", CDF_FLOAT,

1, 0, new long [] {1},

VARY,

new long [] {NOVARY}),

temp3 = Variable.create(cdf, "Temperature1", CDF_FLOAT,

1, 1, new long [] {3},

NOVARY,

new long [] {VARY}),

temp4 = Variable.create(cdf, "Temperature2", CDF_FLOAT,

1, 0, new long [] {1},

NOVARY,

new long [] {NOVARY}),

dp = Variable.create(cdf, "dp", CDF_DOUBLE,

1, 1, new long [] {3},

VARY,

new long [] {VARY}),

ep = Variable.create(cdf, "ep", CDF_EPOCH,

1, 1, new long [] {2},

VARY,

new long [] {VARY}),

dummyVar = Variable.create(cdf, "DummyVar",

CDF_EPOCH,

1, 1, new long [] {2},

VARY,

new long [] {VARY});

System.err.println("Created variables.");

/*********************************/

/* Set miscelleneous settings. */

/*********************************/

cdf.setCompression(RLE_COMPRESSION, new long[] {0});

cdf.setMajority(ROW_MAJOR); /* Default is ROW_MAJOR */

// cdf.setEncoding(SUN_ENCODING);

cdf.selectNegtoPosfp0(NEGtoPOSfp0off);

cdf.selectCDFCacheSize(400L);

cdf.selectCompressCacheSize(500L);

cdf.selectStageCacheSize(600L);

System.err.println("Mode: "+

cdf.confirmzMode());

System.err.println("Neg -0.0 to 0.0: "+

cdf.confirmNegtoPosfp0());

System.err.println("CDF Cache size: "+

cdf.confirmCDFCacheSize());

System.err.println("Compression Cache Size: "+

cdf.confirmCompressCacheSize());

System.err.println("Stage Cache Size: "+

cdf.confirmStageCacheSize());

System.err.println("\nDefined CDF file options...");

dvar.setDimVariances (new long [] {VARY});

longitude.selectCacheSize(700L);

longitude.setCompression(GZIP_COMPRESSION, new long[] {9});

longitude.setPadValue(new Short((short) -99));

longitude.setBlockingFactor(130L);

longitude.setInitialRecords(20L);

// Only applicable to compressed z variables

longitude.selectReservePercent(15L);

System.err.println("Cache Size (longitude): "+

longitude.confirmCacheSize());

System.err.println("Reserver Percentage (longitude): "+

longitude.confirmReservePercent());

// temp.setSparseRecords(PAD_SPARSERECORDS);

// time.setSparseRecords(PAD_SPARSERECORDS);

// ep.setSparseRecords(PREV_SPARSERECORDS);

// Only applicable to uncompressed Z vars in a single-file CDF.

ep.allocateRecords(3L);

long firstRec = 9, lastRec = 20;

time.allocateBlock(firstRec, lastRec);

System.err.println ("time.getAllocatedFrom(4L): "+

time.getAllocatedFrom(4L));

System.err.println ("time.getAllocatedTo(13L): "+

time.getAllocatedFrom(13L));

/*******************************************/

/* Add entries to global attributes */

/* */

/* NOTE: entry value must be a Java object */

/*******************************************/

Double entryValue = new Double(5.3432);

System.err.println("Adding global attribute entries...");

Entry.create(project, 0, CDF_CHAR, "Using the CDFJava API");

Entry.create(pi, 3, CDF_CHAR, "Ernie Els");

System.err.println("\tchars completed.");

Entry.create(test, 0, CDF_DOUBLE, entryValue);

Entry.create(test, 1, CDF_DOUBLE, new double []{5.3, 2.3});

System.err.println("\tdoubles completed.");

Entry.create(test, 2, CDF_FLOAT, new Float(5.5));

Entry.create(test, 3, CDF_FLOAT,

new float [] {(float)5.5,(float)10.2});

System.err.println("\tfloats completed.");

Entry.create(test, 4, CDF_INT1, new Byte((byte)1));

Entry.create(test, 5, CDF_INT1,

new byte [] {(byte) 1, (byte)2, (byte)3});

System.err.println("\tbytes completed.");

Entry.create(test,6,CDF_INT2,new Short((short)-32768));

Entry.create(test, 7, CDF_INT2,

new short [] {(short)1,(short)2});

System.err.println("\tshorts completed.");

Entry.create(test, 8, CDF_INT4, new Integer(3));

Entry.create(test, 9, CDF_INT4, new int [] {4,5});

System.err.println("\tintegers completed.");

Entry.create(test, 10, CDF_CHAR, "This is a string");

System.err.println("\tString completed.");

Entry.create(test,11,CDF_UINT4, new Long(4294967295L));

Entry.create(test,12,CDF_UINT4,

new long[] {4294967295L,2147483648L});

System.err.println("\tUINT4 completed.");

Entry.create(test,13,CDF_UINT2,new Integer(65535));

Entry.create(test,14,CDF_UINT2,new int[]{65535,65534});

System.err.println("\tUINT2 completed.");

Entry.create(test,15,CDF_UINT1, new Short((short)255));

Entry.create(test,16,CDF_UINT1, new short[] {255,254});

System.err.println("\tUINT1 completed.");

/************************************/

/* Add variable attribute entries */

/************************************/

System.err.println("Adding variable attribute entries...");

Entry.create(validMin, longitude.getID(), CDF_INT2,

new Short((short)10));

latitude.putEntry(validMin, CDF_INT2, new Short((short)20));

System.err.println("\tadded VALIDMIN entries.");

longitude.putEntry(validMax, CDF_INT2, new Short((short)180));

latitude.putEntry(validMax, CDF_INT2, new Short((short)90));

System.err.println("\tadded VALIDMAX entries.");

longitude.putEntry(snafu, CDF_CHAR, "test1");

System.err.println("Added snafu for Longitude.");

longitude.putEntry(dummy, CDF_CHAR, "test2");

System.err.println("Added dummy for Longitude.");

/*************************/

/* Delete an attribute */

/*************************/

// dummy.delete();

/***********************/

/* Add variable data */

/***********************/

long recNum = 0,

recCount = 2,

recInterval = 1,

indicies[] = {0},

dimIndicies[] = {0},

dimCounts[] = {3},

dimIntervals[] = {1};

System.err.println("Adding variable data...");

/***************************/

/* Add data to longitude */

/***************************/

long status;

short [][] longitudeData = {{10, 20, 30},

{40, 32767, -32768}};

longitude.putSingleData(recNum, indicies, new Short((short)100));

status = cdf.getStatus();

if (status != CDF_OK) {

String statusText = CDF.getStatusText(status);

System.err.println (statusText);

}

longitude.putSingleData(0L, new long[] {1}, new Short((short)200));

longitude.putSingleData(0L, new long[] {2}, new Short((short)300));

System.err.println("\tAdded a single longitude variable data.");

recNum = 2;

longitude.putHyperData(recNum, recCount, recInterval,

dimIndicies, dimCounts, dimIntervals,

longitudeData);

System.err.println("\tAdded a hyperput longitude variable data.");

recNum = 10;

longitude.putRecord (recNum, new short[] {11, 22, 33});

System.err.println("\tAdded a single longitude variable data.");

/****************************/

/* Add data to longitude1 */

/****************************/

int [][] longitude1Data = {{21, 31},

{51, 61},

{32767, 65535}};

longitude1.putSingleData(0L, indicies, new Integer((int)101));

longitude1.putSingleData(0L, new long[] {1}, new Integer((int)201));

longitude1.putSingleData(0L, new long[] {2}, new Integer((int)301));

System.err.println("\tAdded a single longitude1 variable data.");

recNum = 1;

dimIntervals[0] = 2;

longitude1.putHyperData(recNum, 3, recInterval,

dimIndicies, new long[] {2},

dimIntervals,

longitude1Data);

System.err.println("\tAdded a hyperput longitude1 variable data.");

/**************************/

/* Add data to latitude */

/**************************/

byte [][] latitudeData = { {15, 25, 35},

{45, 127, -128} };

latitude.putSingleData(0L, indicies, new Byte((byte)1));

latitude.putSingleData(0L, new long[] {1}, new Byte((byte)2));

latitude.putSingleData(0L, new long[] {2}, new Byte((byte)3));

System.err.println("\tAdded a single latitude variable data.");

/***************************/

/* Add data to latitude1 */

/***************************/

short [][] latitude1Data = { {15, 25, 35},

{100, 128, 255} };

latitude1.putSingleData(0L, new long[] {2}, new Short((short)5));

System.err.println("\tAdded a single latitude1 variable data.");

// This record will overwrite the first record

recNum = 1;

recCount = 2;

latitude1.putHyperData(recNum, recCount, recInterval,

new long[] {0}, new long[] {3},

new long[] {1}, latitude1Data);

System.err.println("\tAdded a hyperput latitude1 variable data.");

/***********************/

/* Add data to Delta */

/***********************/

int [][][] deltaData = { {{10,20}, {40,50}, {7, 8}},

{{90,95},{96,97}, {32767, -32768}}

};

delta.putSingleData(0L, new long[] {0,0}, new Integer((int)110));

delta.putSingleData(0L, new long[] {0,1}, new Integer((int)210));

delta.putSingleData(0L, new long[] {1,0}, new Integer((int)310));

delta.putSingleData(0L, new long[] {1,1}, new Integer((int)410));

delta.putSingleData(0L, new long[] {2,0}, new Integer((int)510));

delta.putSingleData(0L, new long[] {2,1}, new Integer((int)610));

delta.putHyperData(1L, 2L, 1L, new long[] {0,0}, new long[] {3,2},

new long[] {1,1}, deltaData);

System.err.println("\tAdded delta data.");

/**********************/

/* Add data to Time */

/**********************/

long [][][] timeData = {{{10,20},{40,50},{70, 80}},

{{90,95},{96,97},{2147483648L,4294967295L}}

};

time.putSingleData(0L, new long[] {0,0}, new Long((long)100));

time.putSingleData(0L, new long[] {0,1}, new Long((long)200));

time.putSingleData(0L, new long[] {1,0}, new Long((long)300));

time.putSingleData(0L, new long[] {1,1}, new Long((long)400));

time.putSingleData(0L, new long[] {2,0}, new Long((long)500));

time.putSingleData(0L, new long[] {2,1}, new Long((long)600));

time.putHyperData(5L, 2L, 1L, new long[] {0,0}, new long[] {3,2},

new long[] {1,1}, timeData);

System.err.println("\tAdded time data.");

/**********************/

/* Add data to dvar */

/**********************/

short [][] dvarData = {{15, 25, 35},

{100, 128, 255} };

dvar.putSingleData(0L, new long[] {0}, new Short((short)5));

dvar.putSingleData(1L, new long[] {1}, new Short((short)6));

System.err.println("\tAdded a single dvar variable data.");

recNum = 1;

recCount = 2;

dimIntervals[0] = 1;

dvar.putHyperData(recNum, recCount, recInterval,

dimIndicies, dimCounts, dimIntervals,

dvarData);

System.err.println("\tAdded a hyperput latitude1 variable data.");

/*********************/

/* Add String data */

/*********************/

String [] ndata = new String[2];

ndata[0] = "abcd";

ndata[1] = "bcdefghij";

name.putSingleData(0L, new long[] {0}, new String("123456789"));

name.putSingleData(0L, new long[] {1}, new String("13579"));

System.err.println("\tAdded a single string data.");

name.putHyperData(1L, 1L, 1L,

new long[] {0}, new long[] {2}, new long[] {1},

ndata);

System.err.println("\tAdded hyperput name data.");

/*******************/

/* Add Temp data */

/*******************/

float [][] tempData = {{(float)96.5, (float)97.5, (float)98.5},

{(float)100.5, (float)110.6, (float)120.7},

{(float)200.5, (float)210.6, (float)220.7}};

temp.putSingleData(0L, new long[] {0}, new Float("55.5"));

temp.putSingleData(0L, new long[] {2}, new Float("66.6"));

System.err.println("\tAdded a single temp data.");

temp.putHyperData(1L, 3L, 1L,

new long[] {0}, new long[] {3}, new long[] {1},

tempData);

System.err.println("\tAdded hyperput temp data.");

/********************/

/* Add Temp1 data */

/********************/

float [][] temp1Data = {{(float)10.5, (float)10.6, (float)10.7},

{(float)20.5, (float)20.6, (float)20.7}};

temp1.putSingleData(0L, new long[] {0}, new Float(5.5));

temp1.putSingleData(0L, new long[] {1}, new Float(-0.0));

temp1.putSingleData(0L, new long[] {2}, new Float(6.6));

System.err.println("\tAdded a single temp1 data.");

float temp1Rec[] = {(float)9.5, (float)-0.0, (float)8.5};

temp1.putRecord(1L, temp1Rec);

temp1.putHyperData(2L, 2L, 1L,

new long[] {0}, new long[] {3}, new long[] {1},

temp1Data);

System.err.println("\tAdded hyperput temp1 data.");

/********************************************/

/* Add Temp2 data - scalar Record Varying */

/********************************************/

temp2.putScalarData(0L, new Float("55.55"));

temp2.putScalarData(1L, new Float("66.66"));

System.err.println("\tAdded a scalar temp2 data.");

/********************/

/* Add Temp3 data */

/********************/

temp3.putRecord(temp1Rec);

System.err.println("\tAdded a non-scalar temp3 data.");

/************************************************/

/* Add Temp4 data - scalar Non-Record Varying */

/************************************************/

temp4.putScalarData(new Float("77.77"));

System.err.println("\tAdded a scalar temp4 data.");

/*****************/

/* Add dp data */

/*****************/

double [][] dpData = {{(double)9.5, (double)7.5, (double)8.5},

{(double)10.5, (double)10.6, (double)10.7},

{(double)20.5, (double)20.6, (double)20.7}};

dp.putSingleData(1L, new long[] {0}, new Double("18888.8"));

dp.putSingleData(1L, new long[] {2}, new Double("19999.9"));

System.err.println("\tAdded a single dp data.");

dp.putHyperData(5L, 3L, 1L,

new long[] {0}, new long[] {3}, new long[] {1},

dpData);

System.err.println("\tAdded hyperput dp data.");

/*****************/

/* Add ep data */

/*****************/

double epData = Epoch.compute(1999, 3, 5, 5, 0, 0, 0),

epData1 = Epoch.compute(1998, 1, 2, 3, 0, 0, 0);

String e0 = Epoch.encode(epData1);

double p0 = Epoch.parse(e0);

ep.putSingleData(0L, new long[] {0}, new Double(epData));

ep.putSingleData(0L, new long[] {1}, new Double(p0));

/****************************************/

/* Rename a variable and an attribute */

/****************************************/

dvar.rename("foo");

System.err.println("Renamed a variable.");

validMin.rename("validmin");

System.err.println("Renamed an attribute.");

/**************************************/

/* Get the attribute name and scope */

/**************************************/

String scope;

if (project.getScope() == GLOBAL_SCOPE)

scope = "global";

else

scope = "variable";

System.err.println ("Attribute 'project': \n"+

"\tname: "+project.getName()+

"\n\tscope: "+scope);

/************************************************/

/* Copy a variable - this only copies metadata */

/************************************************/

// The current CDF file MUST be saved first (by calling the save()

// method) before 'copying/duplicating data records' operation is

// performed. Otherwise the program will either fail or produce

// undesired results.

cdf.save();

longitude.copy("longitude_copy");

System.err.println("Copied a variable.");

// Get the variable just copied and set its record variance.

Variable long_copy;

long_copy = cdf.getVariable("longitude_copy");

// long_copy.setRecVariance(NOVARY);

// Copy the 'longitude' variable to 'longitude_copy' and put

// 'longitude_copy" into test1.cdf.

longitude.copy(cdf1,"longitude_copy");

System.err.println("Copied a variable into another CDF.");

longitude.copyDataRecords(long_copy);

longitude.concatenateDataRecords(long_copy);

/***************************************************************/

/* Duplicate a variable */

/* - copies everything including metadata, data, and */

/* other settings such as blocking factor, compression, */

/* sparseness, and pad value */

/***************************************************************/

cdf.save();

longitude.duplicate("longitude_dup");

longitude.duplicate(cdf1, "longitude_dup");

/***********************/

/* Delete a variable */

/***********************/

dummyVar.delete();

System.err.println("Deleted a variable.");

/****************************************/

/* Delete a variable and global entry */

/****************************************/

validMin.deleteEntry(latitude);

System.err.println("Deleted a variable entry.");

long entryID = 1;

test.deleteEntry(entryID);

System.err.println("Deleted a global entry.");

/**********************************************************/

/* For variables with sparse and/or compressed records, */

/* the CDF file must be saved first before records can */

/* be properly deleted. */

/* */

/* NOTE: It's always safe to save a CDF file, before */

/* deleting any variable records. */

/**********************************************************/

cdf.save();

/**********************/

/* Delete record(s) */

/**********************/

firstRec = 1;

lastRec = 2;

time.deleteRecords(firstRec, lastRec);

/************************************/

/* This should throw an exception */

/************************************/

// Attribute badAttribute;

// badAttribute = Attribute.create(cdf, "Project", GLOBAL_SCOPE);

cdf.close();

cdf1.close();

System.err.println("** Tested successfully **");

} catch (Exception e) {

System.out.println("A bad thing happened on the way to the CDF.");

e.printStackTrace();

}

D.2 Read CDF

This program reads and displays the data contents of a CDF file (test.cdf) that was created by CreateCDF.java in D.1.

import java.io.*;

import java.text.*;

import java.util.*;

import java.lang.reflect.*;

import gsfc.nssdc.cdf.*;

import gsfc.nssdc.cdf.util.*;

/**

* This program demonstrates how to read the contents of test.cdf created

* by CreateCDF.java in this directory.

public class ReadCDF implements CDFConstants{

public static void main(String[] args) {

String fileName = "test";

int maxVarNameLength = 22;

try {

CDF cdf = null;

if (args.length == 0) {

cdf = CDF.open(fileName, READONLYoff);

}

else {

fileName = args[0];

cdf = CDF.open(fileName, READONLYoff);

}

/************************************************************/

/* If a decoding method is not specified when a CDF file is */

/* opened, the CDF libaray knows what encoding method was */

/* used to create the CDF file. */

/* */

/* Decoding method should be specified only if one needs */

/* to translate data from one platform to another. */

/************************************************************/

// cdf.selectDecoding(NETWORK_DECODING);

/**********************************/

/* Print out the file information */

/**********************************/

System.out.println("File Info\n"+

"=========================================");

if (cdf.confirmReadOnlyMode() == READONLYon)

System.out.println("CDF File: "+cdf+" (READONLYon)");

else {

System.out.println("CDF File: "+cdf+" (READONLYoff)");

}

System.out.println("Version: "+cdf.getVersion());

String cp = cdf.getCopyright();

System.out.println("Copyright: "+cp);

System.out.println("Format: "+CDFUtils.getStringFormat(cdf));

System.out.println("Encoding: "+

CDFUtils.getStringEncoding(cdf));

System.out.println("Decoding: "+

CDFUtils.getStringDecoding(cdf));

System.out.println("Majority: "+

CDFUtils.getStringMajority(cdf));

System.out.println("numRvars: "+cdf.getNumRvars());

System.out.println("numZvars: "+cdf.getNumZvars());

System.out.println("numAttrs: "+cdf.getNumAttrs()+

" ("+cdf.getNumGattrs()+" global, "+

cdf.getNumVattrs()+" variable)");

System.out.println("Compression: "+cdf.getCompression());

System.out.println("cPct: "+cdf.getCompressionPct());

System.out.println("Cache Size: "+cdf.confirmCDFCacheSize());

/**********************************************/

/* Print out the Global Attribute information */

/**********************************************/

Attribute a;

String attrName = null;

int i;

long n = cdf.getNumGattrs();

Vector ga = cdf.getGlobalAttributes();

System.out.println("\nGlobal Attributes ("+n+" attributes)\n"+

"=========================================");

i = 0;

for (Enumeration e = ga.elements() ; e.hasMoreElements() ;) {

a = (Attribute) e.nextElement();

n = a.getNumEntries();

if (i == 0) {

attrName = a.getName();

if (n <= 1)

System.out.println (attrName+" ("+n+" entry):");

else

System.out.println (attrName+" ("+n+" entries):");

}

else {

String currAttrName = a.getName();;

if (currAttrName != attrName) {

if (n <= 1)

System.out.println (currAttrName+" ("+n+" entry):");

else

System.out.println (currAttrName+" ("+n+" entries):");

}

i++;

Vector ent = a.getEntries();

for (Enumeration e1 =ent.elements() ; e1.hasMoreElements() ;) {

Entry entry = (Entry) e1.nextElement();

if (entry != null) {

if (entry.getID() == 11)

entry.delete();

else {

long eDataType = entry.getDataType();

System.out.print ("\t"+entry.getID()+" ("+

CDFUtils.getStringDataType(eDataType)+

"/"+entry.getNumElements()+

"): \t");

CDFUtils.printData (entry.getData());

System.out.println (" ");

}

System.out.println (" ");

}

/************************************************/

/* Print out the Variable Attribute information */

/************************************************/

attrName = null;

n = cdf.getNumVattrs();

Vector va = cdf.getVariableAttributes();

System.out.println("\nVariable Attributes ("+n+" attributes)\n"+

"=========================================");

i = 0;

for (Enumeration e = va.elements() ; e.hasMoreElements() ;) {

a = (Attribute) e.nextElement();

if (i == 0) {

attrName = a.getName();

System.out.println (attrName+":");

}

else {

String currAttrName = a.getName();;

if (currAttrName != attrName)

System.out.println (currAttrName+":");

}

i++;

Vector ent = a.getEntries();

for (Enumeration e1 =ent.elements() ; e1.hasMoreElements() ;) {

Entry entry = (Entry) e1.nextElement();

if (entry != null) {

long eDataType = entry.getDataType();

Variable v = cdf.getVariable(entry.getID());

System.out.print ("\t"+v.getName()+" ("+

CDFUtils.getStringDataType(eDataType)+

"/"+entry.getNumElements()+

"): ");

CDFUtils.printData (entry.getData());

System.out.println (" ");

}

System.out.println (" ");

}

/**************************************/

/* Print out the Variable information */

/**************************************/

String varName, dataType;

int noOfBlanks;

long numDims;

n = cdf.getNumVars();

Vector vars = cdf.getVariables();

System.out.println("\nVariable Information ("+n+" variables)\n"+

"=========================================");

for (Enumeration e = vars.elements() ; e.hasMoreElements() ;) {

Variable v = (Variable) e.nextElement();

varName = v.getName();

noOfBlanks = maxVarNameLength - varName.length();

for (i=0; i < noOfBlanks; i++)

varName = varName + " ";

long[] dimSizes = v.getDimSizes();

dataType = CDFUtils.getStringDataType(v.getDataType());

dataType = dataType + "/" + String.valueOf(v.getNumElements());

noOfBlanks = 14 - dataType.length();

for (i=0; i < noOfBlanks; i++)

dataType = dataType + " ";

numDims = v.getNumDims();

System.out.print (varName+dataType+ numDims+":[");

for (i=0; i < numDims; i++) {

if (i > 0) System.out.print (",");

System.out.print (dimSizes[i]);

}

System.out.print ("]\t");

// if (numDims == 1) System.out.print ("\t");

System.out.print((v.getRecVariance() ? "T" : "F")+"/");

long[] dimVariances = v.getDimVariances();

for (i=0; i < v.getNumDims(); i++)

System.out.print(

((dimVariances[i] == CDFConstants.VARY) ? "T" : "F"));

System.out.println (" ");

}

/**********************************************************/

/* Print out the Variable data (all variables in the CDF) */

/**********************************************************/

System.out.println("\n\nVariable Data ("+n+" variables)\n"+

"=========================================");

CDFData data = null;

long numRecs, maxRec;

long[] dimIndices = {0L};

long[] dimIntervals = {1L};

long[] dimSizes = {1L};

for (Enumeration e = vars.elements() ; e.hasMoreElements() ;) {

Variable v = (Variable) e.nextElement();

if (v.getNumDims() > 0) {

dimSizes = v.getDimSizes();

dimIntervals = new long[dimSizes.length];

dimIndices = new long[dimSizes.length];

for (i=0; i < dimSizes.length; i++) {

dimIntervals[i] = 1;

dimIndices[i] = 0;

}

maxRec = v.getMaxWrittenRecord();

numRecs = v.getNumWrittenRecords();

varName = v.getName();

System.out.println (varName);

for (i=0; i < varName.length(); i++)

System.out.print ("-");

System.out.println (" ");

if (v.getCompressionType() == NO_COMPRESSION)

System.out.println ("Compression: None");

else

System.out.println ("Compression: "+

v.getCompression()+" ("+

v.getCompressionPct()+"%)");

System.out.println ("Pad value: "+

v.getPadValue());

System.out.println ("Records: "+

numRecs+"n/"+maxRec+"x");

System.out.println ("Allocated: "+

v.getNumAllocatedRecords()+"n/"+

v.getMaxAllocatedRecord()+"x");

System.out.println ("Blocking Factor: "+

v.getBlockingFactor());

System.out.println ("Sparseness: "+

CDFUtils.getStringSparseRecord(v));

System.out.println (" ");

/********************************************************/

/* maxRec represents the last record number for this */

/* variable, not the number of records. */

/* */

/* NOTE: maxRec starts at 0, so if the value of maxRec */

/* is 2, the actual number of records is 3. */

/* If there are no records exists, the value of */

/* maxRec is -1. */

/********************************************************/

for (i=0; i <= maxRec; i++) {

System.out.println ("Record # "+i+":");

data = v.getHyperDataObject(i, 1, 1,

dimIndices,

dimSizes,

dimIntervals);

data.dumpData();

System.out.println(" ");

}

/**************************************************/

/* Print out a few individual variable data and */

/* attribute entries. */

/**************************************************/

if (fileName.equals("test")) {

System.out.println("\n\nIndividual Variable Data\n"+

"=================================");

Variable longitude = cdf.getVariable("Longitude"), /* T/T */

latitude = cdf.getVariable("Latitude"), /* F/T */

latitude1 = cdf.getVariable("Latitude1"), /* T/F */

time = cdf.getVariable("Time"), /* T/T */

foo = cdf.getVariable("foo"), /* F/F */

v = cdf.getVariable("longitude_dup");

System.out.println ("longDup.dumpData():");

System.out.println ("------------------");

if (v.getNumDims() > 0) {

dimSizes = v.getDimSizes();

dimIntervals = new long[dimSizes.length];

dimIndices = new long[dimSizes.length];

for (i=0; i < dimSizes.length; i++) {

dimIntervals[i] = 1;

dimIndices[i] = 0;

}

maxRec = v.getMaxWrittenRecord();

for (i=0; i <= maxRec; i++) {

System.out.println ("Record # "+i+":");

data = v.getHyperDataObject(i, 1, 1,

dimIndices,

dimSizes,

dimIntervals);

data.dumpData();

System.out.println(" ");

}

System.out.print ("Record #0 for latitude: ");

CDFUtils.printData (latitude.getRecord (0));

System.out.println ("");

System.out.print ("Record #1 for longitude: ");

CDFUtils.printData (longitude.getRecord (1));

System.out.println ("");

System.out.print ("Record #2 for latitude1: ");

CDFUtils.printData (latitude1.getRecord (2));

System.out.println ("");

System.out.print ("Record #0 for foo: ");

CDFUtils.printData (foo.getRecord (0));

System.out.println ("\n");

System.out.print ("1st element of record #0 for latitude: ");

CDFUtils.printData (latitude.getSingleData(0, new long [] {0}));

System.out.println ("");

System.out.print ("2nd element of record #1 for longitude: ");

CDFUtils.printData (longitude.getSingleData(1, new long [] {1}));

System.out.println ("");

System.out.print ("3rd element of record #2 for longitude: ");

CDFUtils.printData (latitude1.getSingleData(2, new long [] {2}));

System.out.println ("");

System.out.print ("1st element of record #0 for foo: ");

CDFUtils.printData (foo.getSingleData (0, new long [] {0}));

System.out.println ("\n");

CDFData dataRecord;

System.out.print ("(1,0)th element of record #0 for Time: ");

dataRecord = time.getSingleDataObject(0, new long[] {1,0});

dataRecord.dumpData();

System.out.print ("(1,1)th element of record #0 for Time: ");

Long tValue = (Long) time.getSingleData(0, new long[] {1,1});

System.out.println (tValue);

System.out.println ("Record #0 for Time: ");

dataRecord = time.getRecordObject(0L);

dataRecord.dumpData();

System.out.println ("\n");

System.out.println ("Record #0 for Time: ");

long[][] yy = (long [][]) time.getRecord(0L);

for (int x=0;x<3; x++)

for (int j=0;j<2;j++)

System.out.println("["+x+","+j+"] ="+yy[x][j]);

System.out.println ("\n");

Variable var;

var = cdf.getVariable("Temperature2");

System.out.print ("getScalarData for Temperature2: ");

CDFUtils.printData (var.getScalarData());

System.out.println ("\n");

System.out.print ("getScalarDataObject for Temperature2: ");

dataRecord = var.getScalarDataObject();

dataRecord.dumpData();

var = cdf.getVariable("Temperature");

System.out.print ("Record #0 for Temperature: ");

CDFUtils.printData (var.getScalarData(0L));

System.out.println ("\n");

System.out.print ("Record #1 for Temperature: ");

dataRecord = var.getScalarDataObject(1L);

dataRecord.dumpData();

var = cdf.getVariable("Delta");

System.out.println ("HyperGet for Delta: ");

int[][][] xx = (int [][][]) var.getHyperData (1L, 3L, 1L,

new long[] {1, 0},

new long[] {2, 2},

new long[] {1, 1});

for (int x=0;x<2; x++)

for (int j=0;j<2;j++)

for (int k=0;k<2;k++)

System.out.println("["+x+","+j+","+k+"] ="+xx[x][j][k]);

int[][] zz = (int [][]) var.getHyperData (0L, 3L, 1L,

new long[] {0, 1},

new long[] {3, 1},

new long[] {1, 1});

System.out.println(" ");

for (int x=0;x<3; x++)

for (int j=0;j<3;j++)

System.out.println("["+x+","+j+"] ="+zz[x][j]);

System.out.println ("\n");

System.out.println("\n\nVariable/Global Attribute Entries"+

"\n====================================");

Attribute test = cdf.getAttribute("Test"), /* global */

validMin = cdf.getAttribute("validmin"); /* var */

Entry tEntry = test.getEntry(15),

vEntry = validMin.getEntry(longitude);

long attrNum = test.getID();

Attribute test1 = cdf.getAttribute(attrNum);

System.out.print (test1.getName()+": \n\t");

CDFUtils.printData (tEntry.getData());

System.out.println ("");

System.out.print ("\nVALIDMIN: \n\tLongitude: ");

CDFUtils.printData (vEntry.getData());

System.out.println ("");

System.out.print ("\nVALIDMAX: \n\tLatitude: ");

var = cdf.getVariable("Latitude");

CDFUtils.printData (var.getEntryData("VALIDMAX"));

System.out.println ("");

}

cdf.close();

} catch (Exception e) {

System.out.println (e);

}

D.3 Quick Start Test Program (C standard interface)

/******************************************************************************

* NSSDC/CDF Quick Start Test Program (C standard interface).

******************************************************************************/

#include <stdlib.h>

#include <stdio.h>

#include <string.h>

#include "cdf.h"

#if defined(vms)

#include <ssdef>

#define EXIT_SUCCESS_ SS$_NORMAL

#define EXIT_FAILURE_ SS$_ABORT

#else

#define EXIT_SUCCESS_ 0

#define EXIT_FAILURE_ 1

#endif

/******************************************************************************

* Increased stack size for Borland C on IBM PC.

******************************************************************************/

#if defined(BORLANDC)

extern unsigned _stklen = 12000u;

#endif

/******************************************************************************

* Macros/prototypes.

******************************************************************************/

#define N_DIMS 2

#define DIM_0_SIZE 2

#define DIM_1_SIZE 3

void QuitCDF PROTOARGs((CDFstatus status, char *where, CDFid id));

void QuitEPOCH PROTOARGs((char *where));

/******************************************************************************

* Main.

******************************************************************************/

int main () {

CDFid id;

CDFstatus status;

int dim_n;

static long encoding = NETWORK_ENCODING;

static long actual_encoding = NETWORK_ENCODING;

static long majority = ROW_MAJOR;

static long numDims = N_DIMS;

static long dimSizes[N_DIMS] = { DIM_0_SIZE, DIM_1_SIZE };

static long varDataType = { CDF_INT2 };

long varDataType_out;

static long varNumElements = { 1 };

long varNumElements_out;

long varNum_out;

static short varValues[DIM_0_SIZE][DIM_1_SIZE] = {{1,2,3},{4,5,6}};

long indices[N_DIMS];

static long recNum = { 0 };

short varValue_out;

static long recStart = { 0 };

static long recCount = { 1 };

static long recInterval = { 1 };

static long counts[N_DIMS] = { DIM_0_SIZE, DIM_1_SIZE };

static long intervals[N_DIMS] = { 1, 1 };

short varBuffer_out[DIM_0_SIZE][DIM_1_SIZE];

long attrNum_out;

static long entryNum = { 2 };

long maxEntry_out;

static long attrScope = { GLOBAL_SCOPE };

long attrScope_out;

static long attrDataType = { CDF_INT2 };

long attrDataType_out;

static long attrNumElements = { 1 };

long attrNumElements_out;

static short attrValue = { 1 };

short attrValue_out;

long encoding_out;

long majority_out;

long numDims_out;

long dimSizes_out[N_DIMS];

long maxRec_out;

long numVars_out;

long numAttrs_out;

long version_out;

long release_out;

int x0, x1, x;

static long varRecVariance = { VARY };

long varRecVariance_out;

static long varDimVariances[N_DIMS] = { VARY, VARY };

long varDimVariances_out[N_DIMS];

static char varName[] = "VAR1";

static char new_varName[] = "VAR2";

char varName_out[CDF_VAR_NAME_LEN+1];

static char attrName[] = "ATTR1";

static char new_attrName[] = "ATTR2";

char attrName_out[CDF_ATTR_NAME_LEN];

char CopyRightText[CDF_COPYRIGHT_LEN+1];

char errorText[CDF_ERRTEXT_LEN+1];

long year = 1994;

long month = 10;

long day = 13;

long hour = 12;

long minute = 0;

long second = 0;

long msec = 0;

long yearOut, monthOut, dayOut,

hourOut, minuteOut, secondOut, msecOut;

double epoch, epochOut;

char epString[EPOCH_STRING_LEN+1];

char epString1[EPOCH1_STRING_LEN+1];

char epString2[EPOCH2_STRING_LEN+1];

char epString3[EPOCH3_STRING_LEN+1];

static char epStringTrue[EPOCH_STRING_LEN+1] = "13-Oct-1994 12:00:00.000";

static char epString1True[EPOCH1_STRING_LEN+1] = "19941013.5000000";

static char epString2True[EPOCH2_STRING_LEN+1] = "19941013120000";

static char epString3True[EPOCH3_STRING_LEN+1]="1994-10-13T12:00:00.000Z";

/******************************************************************************

* Display title.

******************************************************************************/

printf ("Testing Standard/C interface...\n");

/******************************************************************************

* Create CDF.

******************************************************************************/

status = CDFcreate ("TEST", numDims, dimSizes, encoding, majority, &id);

if (status < CDF_OK) {

if (status == CDF_EXISTS) {

status = CDFopen ("TEST", &id);

if (status < CDF_OK) QuitCDF (status, "1.0", id);

status = CDFdelete (id);

if (status < CDF_OK) QuitCDF (status, "1.1", id);

status = CDFcreate ("TEST", numDims, dimSizes, encoding, majority, &id);

if (status < CDF_OK) QuitCDF (status, "1.2", id);

}

else

QuitCDF (status, "1.3", id);

}

/******************************************************************************

* Create variable.

******************************************************************************/

status = CDFvarCreate (id, varName, varDataType, varNumElements,

varRecVariance, varDimVariances, &varNum_out);

if (status < CDF_OK) QuitCDF (status, "2.0", id);

/******************************************************************************

* Close CDF.

******************************************************************************/

status = CDFclose (id);

if (status < CDF_OK) QuitCDF (status, "3.0", id);

/******************************************************************************

* Reopen CDF.

******************************************************************************/

status = CDFopen ("TEST", &id);

if (status < CDF_OK) QuitCDF (status, "4.0", id);

/******************************************************************************

* Delete CDF.

******************************************************************************/

status = CDFdelete (id);

if (status < CDF_OK) QuitCDF (status, "5.0", id);

/******************************************************************************

* Create CDF again (previous delete will allow this).

******************************************************************************/

status = CDFcreate ("TEST", numDims, dimSizes, encoding, majority, &id);

if (status < CDF_OK) QuitCDF (status, "6.0", id);

/******************************************************************************

* Create variable.

******************************************************************************/

status = CDFvarCreate (id, varName, varDataType, varNumElements,

varRecVariance, varDimVariances, &varNum_out);

if (status < CDF_OK) QuitCDF (status, "7.0", id);

/******************************************************************************

* PUT to variable.

******************************************************************************/

for (x0 = 0; x0 < DIM_0_SIZE; x0++)

for (x1 = 0; x1 < DIM_1_SIZE; x1++) {

indices[0] = x0;

indices[1] = x1;

status = CDFvarPut (id, CDFvarNum(id,varName), recNum, indices,

&varValues[x0][x1]);

if (status < CDF_OK) QuitCDF (status, "8.0", id);

}

/******************************************************************************

* GET from the variable.

******************************************************************************/

for (x0 = 0; x0 < DIM_0_SIZE; x0++)

for (x1 = 0; x1 < DIM_1_SIZE; x1++) {

indices[0] = x0;

indices[1] = x1;

status = CDFvarGet (id, CDFvarNum(id,varName), recNum, indices,

&varValue_out);

if (status < CDF_OK) QuitCDF (status, "9.0", id);

if (varValue_out != varValues[x0][x1]) QuitCDF (status, "9.1", id);

}

/******************************************************************************

* HyperPUT to the variable.

******************************************************************************/

for (x0 = 0; x0 < DIM_0_SIZE; x0++)

for (x1 = 0; x1 < DIM_1_SIZE; x1++)

varValues[x0][x1] = -varValues[x0][x1];

indices[0] = 0;

indices[1] = 0;

status = CDFvarHyperPut (id, CDFvarNum(id,varName), recStart, recCount,

recInterval, indices, counts, intervals, varValues);

if (status < CDF_OK) QuitCDF (status, "10.0", id);

/******************************************************************************

* HyperGET from variable.

******************************************************************************/

status = CDFvarHyperGet (id, CDFvarNum(id,varName), recStart, recCount,

recInterval, indices, counts, intervals,

varBuffer_out);

if (status < CDF_OK) QuitCDF (status, "11.0", id);

for (x0 = 0; x0 < DIM_0_SIZE; x0++)

for (x1 = 0; x1 < DIM_1_SIZE; x1++)

if (varBuffer_out[x0][x1] != varValues[x0][x1]) QuitCDF (status,"11.1",id);

/******************************************************************************

* Create attribue.

******************************************************************************/

status = CDFattrCreate (id, attrName, attrScope, &attrNum_out);

if (status < CDF_OK) QuitCDF (status, "12.0", id);

/******************************************************************************

* PUT to attribute.

******************************************************************************/

status = CDFattrPut (id, CDFattrNum(id,attrName), entryNum, attrDataType,

attrNumElements, &attrValue);

if (status < CDF_OK) QuitCDF (status, "13.0", id);

/******************************************************************************

* GET from attribute.

******************************************************************************/

status = CDFattrGet (id, CDFattrNum(id,attrName), entryNum, &attrValue_out);

if (status < CDF_OK) QuitCDF (status, "14.0", id);

/******************************************************************************

* Get CDF documentation.

******************************************************************************/

status = CDFdoc (id, &version_out, &release_out, CopyRightText);

if (status < CDF_OK) QuitCDF (status, "15.0", id);

/******************************************************************************

* Inquire CDF.

******************************************************************************/

status = CDFinquire (id, &numDims_out, dimSizes_out, &encoding_out,

&majority_out, &maxRec_out, &numVars_out, &numAttrs_out);

if (status < CDF_OK) QuitCDF (status, "16.0", id);

if (numDims_out != numDims) QuitCDF (status, "16.1", id);

for (x = 0; x < N_DIMS; x++)

if (dimSizes_out[x] != dimSizes[x]) QuitCDF (status, "16.2", id);

if (encoding_out != actual_encoding) QuitCDF (status, "16.3", id);

if (majority_out != majority) QuitCDF (status, "16.4", id);

if (maxRec_out != 0) QuitCDF (status, "16.5", id);

if (numVars_out != 1) QuitCDF (status, "16.6", id);

if (numAttrs_out != 1) QuitCDF (status, "16.7", id);

/******************************************************************************

* Rename variable.

******************************************************************************/

status = CDFvarRename (id, CDFvarNum(id,varName), new_varName);

if (status < CDF_OK) QuitCDF (status, "17.0", id);

/******************************************************************************

* Inquire variable.

******************************************************************************/

status = CDFvarInquire (id, CDFvarNum(id,new_varName), varName_out,

&varDataType_out, &varNumElements_out,

&varRecVariance_out, varDimVariances_out);

if (status < CDF_OK) QuitCDF (status, "18.0", id);

if (strcmp(varName_out,new_varName) != 0) QuitCDF (status, "18.1", id);

if (varDataType_out != varDataType) QuitCDF (status, "18.2", id);

if (varNumElements_out != varNumElements) QuitCDF (status, "18.3", id);

if (varRecVariance_out != varRecVariance) QuitCDF (status, "18.4", id);

for (dim_n = 0; dim_n < numDims; dim_n++)

if (varDimVariances_out[dim_n] != varDimVariances[dim_n])

QuitCDF (status, "18.4", id);

/******************************************************************************

* Close variable.

******************************************************************************/

status = CDFvarClose (id, CDFvarNum(id,new_varName));

if (status < CDF_OK) QuitCDF (status, "19.0", id);

/******************************************************************************

* Rename attribute.

******************************************************************************/

status = CDFattrRename (id, CDFattrNum(id,attrName), new_attrName);

if (status < CDF_OK) QuitCDF (status, "20.0", id);

/******************************************************************************

* Inquire attribute.

******************************************************************************/

status = CDFattrInquire (id, CDFattrNum(id,new_attrName), attrName_out,

&attrScope_out, &maxEntry_out);

if (status < CDF_OK) QuitCDF (status, "22.0", id);

if (strcmp(attrName_out,new_attrName) != 0) QuitCDF (status, "22.1", id);

if (attrScope_out != attrScope) QuitCDF (status, "22.2", id);

if (maxEntry_out != entryNum) QuitCDF (status, "22.3", id);

/******************************************************************************

* Inquire attribute entry.

******************************************************************************/

status = CDFattrEntryInquire (id, CDFattrNum(id,new_attrName), entryNum,

&attrDataType_out, &attrNumElements_out);

if (status < CDF_OK) QuitCDF (status, "23.0", id);

if (attrDataType_out != attrDataType) QuitCDF (status, "23.1", id);

if (attrNumElements_out != attrNumElements) QuitCDF (status, "23.1", id);

/******************************************************************************

* Get error text.

******************************************************************************/

CDFerror (CDF_OK, errorText);

/******************************************************************************

* Close CDF.

******************************************************************************/

status = CDFclose (id);

if (status < CDF_OK) QuitCDF (status, "24.0", id);

/******************************************************************************

* Test EPOCH routines.

******************************************************************************/

epoch = computeEPOCH (year, month, day, hour, minute, second, msec);

encodeEPOCH (epoch, epString);

if (strcmp(epString,epStringTrue)) QuitEPOCH ("30.0");

epochOut = parseEPOCH (epString);

if (epochOut != epoch) QuitEPOCH ("31.1");

encodeEPOCH1 (epoch, epString1);

if (strcmp(epString1,epString1True)) QuitEPOCH ("30.2");

epochOut = parseEPOCH1 (epString1);

if (epochOut != epoch) QuitEPOCH ("31.3");

encodeEPOCH2 (epoch, epString2);

if (strcmp(epString2,epString2True)) QuitEPOCH ("30.4");

epochOut = parseEPOCH2 (epString2);

if (epochOut != epoch) QuitEPOCH ("31.5");

encodeEPOCH3 (epoch, epString3);

if (strcmp(epString3,epString3True)) QuitEPOCH ("30.6");

epochOut = parseEPOCH3 (epString3);

if (epochOut != epoch) QuitEPOCH ("31.7");

EPOCHbreakdown (epoch, &yearOut, &monthOut, &dayOut, &hourOut, &minuteOut,

&secondOut, &msecOut);

if (yearOut != year) QuitEPOCH ("32.1");

if (monthOut != month) QuitEPOCH ("32.2");

if (dayOut != day) QuitEPOCH ("32.3");

if (hourOut != hour) QuitEPOCH ("32.4");

if (minuteOut != minute) QuitEPOCH ("32.5");

if (secondOut != second) QuitEPOCH ("32.6");

if (msecOut != msec) QuitEPOCH ("32.7");

/******************************************************************************

* Successful completion.

******************************************************************************/

return EXIT_SUCCESS_;

}

/******************************************************************************

* QuitCDF.

******************************************************************************/

void QuitCDF (status, where, id)

CDFstatus status;

char *where;

CDFid id;

{

char text[CDF_STATUSTEXT_LEN+1];

printf ("Aborting at %s...\n", where);

if (status < CDF_OK) {

CDFerror (status, text);

printf ("%s\n", text);

}

CDFclose (id);

printf ("...test aborted.\n");

exit (EXIT_FAILURE_);

}

/******************************************************************************

* QuitEPOCH.

******************************************************************************/

void QuitEPOCH (where)

char *where;

{

printf ("Aborting at %s...test aborted.\n", where);

exit (EXIT_FAILURE_);

}

D.4 Quick Start Test Program (C internal interface)

/******************************************************************************

* NSSDC/CDF Quick Start Test Program (C internal interface).

* This program is an CDF internal interface version of the standard

* interface program in this appendix.

******************************************************************************/

#include <stdlib.h>

#include <stdio.h>

#include <string.h>

#include "cdf.h"

#if defined(vms)

#include <ssdef>

#define EXIT_SUCCESS_ SS$_NORMAL

#define EXIT_FAILURE_ SS$_ABORT

#else

#define EXIT_SUCCESS_ 0

#define EXIT_FAILURE_ 1

#endif

/******************************************************************************

* Increased stack size for Borland C on IBM PC.

******************************************************************************/

#if defined(BORLANDC)

extern unsigned _stklen = 12000u;

#endif

/******************************************************************************

* Macros/prototypes.

******************************************************************************/

#define N_DIMS 2

#define DIM_0_SIZE 2

#define DIM_1_SIZE 3

#define zN_DIMSa 1

#define zDIM_0_SIZEa 5

#define zNUM_ELEMSa 8

void QuitCDF PROTOARGs((char *where, CDFstatus status));

/******************************************************************************

* Main.

******************************************************************************/

int main () {

CDFid id;

CDFstatus status;

int dim_n;

static long encoding = NETWORK_ENCODING;

static long actual_encoding = NETWORK_ENCODING;

static long majority = ROW_MAJOR;

static long numDims = N_DIMS;

static long dimSizes[N_DIMS] = { DIM_0_SIZE, DIM_1_SIZE };

static long zNumDimsA = zN_DIMSa;

static long zDimSizesA[zN_DIMSa] = { zDIM_0_SIZEa };

static long var1DataType = { CDF_INT2 };

static long var1DataTypeNew = { CDF_UINT2 };

static long var2DataType = { CDF_REAL4 };

static long zVarAdataType = { CDF_CHAR };

static long zVarAdataTypeNew = { CDF_UCHAR };

long var1DataType_out, var2DataType_out, zVarAdataType_out;

static long var1NumElements = { 1 };

static long var1NumElementsNew = { 1 };

static long var2NumElements = { 1 };

static long zVarAnumElements = { zNUM_ELEMSa };

static long zVarAnumElementsNew = { zNUM_ELEMSa };

long var1NumElements_out, var2NumElements_out, zVarAnumElements_out;

long var1Num_out, var2Num_out, zVarAnum_out, varNum_out1, varNum_out2;

static short var1Values[DIM_0_SIZE][DIM_1_SIZE] = {{1,2,3},{4,5,6}};

static float var2Values[DIM_0_SIZE][DIM_1_SIZE] = {{1.,2.,3.},{4.,5.,6.}};

static char zVarAvalues[zDIM_0_SIZEa][zNUM_ELEMSa] = {

{'1','1','1','1','1','1','1','1'},

{'2','2','2','2','2','2','2','2'},

{'3','3','3','3','3','3','3','3'},

{'4','4','4','4','4','4','4','4'},

{'5','5','5','5','5','5','5','5'}

};

short var1Value_out;

float var2Value_out;

static char zVarAvalue_out[zNUM_ELEMSa];

static long recNum = { 0 };

static long recStart = { 0 };

static long recCount = { 1 };

static long recInterval = { 1 };

long indices[N_DIMS];

static long counts[N_DIMS] = { DIM_0_SIZE, DIM_1_SIZE };

static long intervals[N_DIMS] = { 1, 1 };

static long zRecNum = { 0 };

static long zRecStart = { 0 };

static long zRecCount = { 1 };

static long zRecInterval = { 1 };

long zIndicesA[zN_DIMSa];

static long zCounts[zN_DIMSa] = { zDIM_0_SIZEa };

static long zIntervals[N_DIMS] = { 1 };

short var1Buffer_out[DIM_0_SIZE][DIM_1_SIZE];

float var2Buffer_out[DIM_0_SIZE][DIM_1_SIZE];

char zVarAbuffer_out[zDIM_0_SIZEa][zNUM_ELEMSa];

long attrNum_out;

static long entryNum = { 2 };

long maxEntry_out;

static long attrScope = { GLOBAL_SCOPE };

static long attrScope2 = { VARIABLE_SCOPE };

static long attrScope3 = { VARIABLE_SCOPE };

long attrScope_out;

static long entryDataType = { CDF_INT2 };

static long entryDataTypeNew = { CDF_UINT2 };

long entryDataType_out;

static long entryNumElems = { 1 };

long entryNumElems_out;

static short entryValue = { 1 };

short entryValue_out;

long encoding_out;

long majority_out;

long numDims_out;

long dimSizes_out[N_DIMS];

long zNumDimsA_out;

long zDimSizesA_out[zN_DIMSa];

long maxRec_out;

long numAttrs_out;

long version_out;

long release_out;

long increment_out;

char subincrement_out;

int i, x0, x1, x;

static long var1RecVariance = { VARY };

static long var1RecVarianceNew = { NOVARY };

static long var2RecVariance = { VARY };

static long zVarArecVariance = { VARY };

static long zVarArecVarianceNew = { NOVARY };

long var1RecVariance_out, var2RecVariance_out, zVarArecVariance_out;

static long var1DimVariances[N_DIMS] = { VARY, VARY };

static long var1DimVariancesNew[N_DIMS] = { NOVARY, NOVARY };

static long var2DimVariances[N_DIMS] = { VARY, VARY };

static long zVarAdimVariances[zN_DIMSa] = { VARY };

static long zVarAdimVariancesNew[zN_DIMSa] = { NOVARY };

long var1DimVariances_out[N_DIMS],

var2DimVariances_out[N_DIMS],

zVarAdimVariances_out[zN_DIMSa];

static char var1Name[] = "VAR1a";

static char var2Name[] = "VAR2a";

static char zVarAname[] = "zVARa1";

static char new_var1Name[] = "VAR1b";

static char new_var2Name[] = "VAR2b";

static char new_zVarAname[] = "zVARa2";

char var1Name_out[CDF_VAR_NAME_LEN+1],

var2Name_out[CDF_VAR_NAME_LEN+1],

zVarAname_out[CDF_VAR_NAME_LEN+1];

static char attrName[] = "ATTR1";

static char attrName2[] = "ATTR2";

static char attrName3[] = "ATTR3";

static char new_attrName[] = "ATTR1a";

char attrName_out[CDF_ATTR_NAME_LEN];

char CopyRightText[CDF_COPYRIGHT_LEN+1];

char errorText[CDF_STATUSTEXT_LEN+1];

static char rEntryValue = { 4 };

char rEntryValueOut;

static double zEntryValue = { 4.0 };

double zEntryValueOut;

long numRvars, numZvars, maxGentry, numGentries, maxRentry, numRentries,

maxZentry, numZentries, numGattrs, numVattrs;

long cacheOut1, cacheOut2, cacheOut3;

static short pad1 = { -999 };

static float pad2 = { -8.0 };

static char pad3[zNUM_ELEMSa+1] = { "********" };

short pad1out;

float pad2out;

static char pad3out[zNUM_ELEMSa+1] = { " " };

static long blockingfactor1 = 3;

static long blockingfactor2 = 4;

static long blockingfactor3 = 5;

long blockingfactorOut1, blockingfactorOut2, blockingfactorOut3;

long recStartOut, recCountOut, recIntervalOut, recNumOut;

long indicesOut[CDF_MAX_DIMS],

countsOut[CDF_MAX_DIMS],

intervalsOut[CDF_MAX_DIMS];

int dimN;

long entryNumOut1, entryNumOut2, entryNumOut3;

long formatOut;

long maxAllocOut1, maxAllocOut2, maxAllocOut3;

long maxRecOut1, maxRecOut2, maxRecOut3, maxRecOut;

long nIndexRecsOut1, nIndexRecsOut2, nIndexRecsOut3;

long nIndexEntriesOut1, nIndexEntriesOut2, nIndexEntriesOut3;

static long allocRecs1 = { 10 };

static long allocRecs2 = { 15 };

static long allocRecs3 = { 8 };

static long nRvars = { 2 };

static long rVarNs[2] = { 1, 0 };

static char rVarsRecBuffer[DIM_0_SIZE][DIM_1_SIZE][6] = {

{{0,0,0,0,0,0},{0,0,0,0,0,0},{0,0,0,0,0,0}},

{{0,0,0,0,0,0},{0,0,0,0,0,0},{0,0,0,0,0,0}}

};

static char rVarsRecBufferOut[DIM_0_SIZE][DIM_1_SIZE][6];

static long nZvars = { 1 };

static long zVarNs[1] = { 0 };

static char zVarsRecBuffer[zDIM_0_SIZEa][zNUM_ELEMSa] = {

{'%','%','%','%','%','%','%','%'},

{'%','%','%','%','%','%','%','%'}

};

static char zVarsRecBufferOut[zDIM_0_SIZEa][zNUM_ELEMSa];

/******************************************************************************

* Display title.

******************************************************************************/

printf ("Testing Internal/C interface...\n");

/******************************************************************************

* Create CDF.

******************************************************************************/

status = CDFlib (CREATE_, CDF_, "TEST", numDims, dimSizes, &id,

PUT_, CDF_ENCODING_, encoding,

CDF_MAJORITY_, majority,

CDF_FORMAT_, MULTI_FILE,

NULL_);

if (status < CDF_OK) {

if (status == CDF_EXISTS) {

status = CDFlib (OPEN_, CDF_, "TEST", &id,

NULL_);

if (status < CDF_OK) QuitCDF ("1.0", status);

status = CDFlib (DELETE_, CDF_,

NULL_);

if (status < CDF_OK) QuitCDF ("1.1", status);

status = CDFlib (CREATE_, CDF_, "TEST", numDims, dimSizes, &id,

PUT_, CDF_ENCODING_, encoding,

CDF_MAJORITY_, majority,

CDF_FORMAT_, MULTI_FILE,

NULL_);

if (status < CDF_OK) QuitCDF ("1.2", status);

}

else

QuitCDF ("1.3", status);

}

/******************************************************************************

* Create variables and set/confirm cache sizes, etc.

******************************************************************************/

status = CDFlib (CREATE_, rVAR_, var1Name, var1DataType, var1NumElements,

var1RecVariance, var1DimVariances,

&var1Num_out,

NULL_);

if (status < CDF_OK) QuitCDF ("2.0aa", status);

status = CDFlib (PUT_, rVAR_PADVALUE_, &pad1,

NULL_);

if (status < CDF_OK) QuitCDF ("2.0ab", status);

status = CDFlib (CREATE_, rVAR_, var2Name, var2DataType, var2NumElements,

var2RecVariance, var2DimVariances,

&var2Num_out,

PUT_, rVAR_PADVALUE_, &pad2,

NULL_);

if (status < CDF_OK) QuitCDF ("2.0b", status);

status = CDFlib (CREATE_, zVAR_, zVarAname, zVarAdataType, zVarAnumElements,

zNumDimsA, zDimSizesA, zVarArecVariance,

zVarAdimVariances, &zVarAnum_out,

PUT_, zVAR_PADVALUE_, pad3,

NULL_);

if (status < CDF_OK) QuitCDF ("2.0c", status);

status = CDFlib (SELECT_, rVARs_CACHESIZE_, 5L,

zVARs_CACHESIZE_, 6L,

NULL_);

if (status < CDF_OK) QuitCDF ("2.0d", status);

status = CDFlib (SELECT_, CDF_, id,

rVAR_, 0L,

CONFIRM_, rVAR_CACHESIZE_, &cacheOut1,

GET_, rVAR_PADVALUE_, &pad1out,

SELECT_, rVAR_, 1L,

CONFIRM_, rVAR_CACHESIZE_, &cacheOut2,

GET_, rVAR_PADVALUE_, &pad2out,

SELECT_, zVAR_, 0L,

CONFIRM_, zVAR_CACHESIZE_, &cacheOut3,

GET_, zVAR_PADVALUE_, pad3out,

NULL_);

if (status < CDF_OK) QuitCDF ("2a.0", status);

if (cacheOut1 != 5) QuitCDF ("2a.1", status);

if (cacheOut2 != 5) QuitCDF ("2a.2", status);

if (cacheOut3 != 6) QuitCDF ("2a.3", status);

if (pad1out != pad1) QuitCDF ("2a.3a", status);

if (pad2out != pad2) QuitCDF ("2a.3b", status);

if (strcmp(pad3out,pad3)) QuitCDF ("2a.3c", status);

status = CDFlib (SELECT_, rVAR_, 0L,

rVAR_CACHESIZE_, 4L,

zVAR_, 0L,

zVAR_CACHESIZE_, 8L,

NULL_);

if (status < CDF_OK) QuitCDF ("2a.4", status);

status = CDFlib (SELECT_, rVAR_, 0L,

CONFIRM_, rVAR_CACHESIZE_, &cacheOut1,

SELECT_, rVAR_, 1L,

CONFIRM_, rVAR_CACHESIZE_, &cacheOut2,

SELECT_, zVAR_, 0L,

CONFIRM_, zVAR_CACHESIZE_, &cacheOut3,

NULL_);

if (status < CDF_OK) QuitCDF ("2a.0", status);

if (cacheOut1 != 4) QuitCDF ("2a.1", status);

if (cacheOut2 != 5) QuitCDF ("2a.2", status);

if (cacheOut3 != 8) QuitCDF ("2a.3", status);

/******************************************************************************

* Modify variables.

******************************************************************************/

status = CDFlib (SELECT_, rVAR_, 0L,

PUT_, rVAR_DATASPEC_, var1DataTypeNew, var1NumElementsNew,

rVAR_RECVARY_, var1RecVarianceNew,

rVAR_DIMVARYS_, var1DimVariancesNew,

rVAR_INITIALRECS_, 1L,

SELECT_, zVAR_, 0L,

PUT_, zVAR_DATASPEC_, zVarAdataTypeNew, zVarAnumElementsNew,

zVAR_RECVARY_, zVarArecVarianceNew,

zVAR_DIMVARYS_, zVarAdimVariancesNew,

zVAR_INITIALRECS_, 1L,

NULL_);

if (status < CDF_OK) QuitCDF ("2b.0", status);

/******************************************************************************

* Close CDF.

******************************************************************************/

status = CDFlib (CLOSE_, CDF_,

NULL_);

if (status < CDF_OK) QuitCDF ("3.0", status);

/******************************************************************************

* Reopen CDF.

******************************************************************************/

status = CDFlib (OPEN_, CDF_, "TEST", &id,

SELECT_, CDF_DECODING_, HOST_DECODING,

NULL_);

if (status < CDF_OK) QuitCDF ("4.0", status);

/******************************************************************************

* Delete CDF.

******************************************************************************/

status = CDFlib (DELETE_, CDF_,

NULL_);

if (status < CDF_OK) QuitCDF ("5.0", status);

/******************************************************************************

* Create CDF again (previous delete will allow this).

******************************************************************************/

status = CDFlib (CREATE_, CDF_, "TEST", numDims, dimSizes, &id,

PUT_, CDF_ENCODING_, encoding,

CDF_MAJORITY_, majority,

CDF_FORMAT_, SINGLE_FILE,

SELECT_, CDF_DECODING_, HOST_DECODING,

NULL_);

if (status < CDF_OK) QuitCDF ("6.0", status);

/******************************************************************************

* Create variables.

******************************************************************************/

status = CDFlib (CREATE_, rVAR_, var1Name, var1DataType, var1NumElements,

var1RecVariance, var1DimVariances,

&var1Num_out,

PUT_, rVAR_ALLOCATERECS_, allocRecs1,

rVAR_BLOCKINGFACTOR_, blockingfactor1,

NULL_);

if (status < CDF_OK) QuitCDF ("7.0a", status);

status = CDFlib (CREATE_, rVAR_, var2Name, var2DataType, var2NumElements,

var2RecVariance, var2DimVariances,

&var2Num_out,

PUT_, rVAR_ALLOCATERECS_, allocRecs2,

rVAR_BLOCKINGFACTOR_, blockingfactor2,

NULL_);

if (status < CDF_OK) QuitCDF ("7.0b", status);

status = CDFlib (CREATE_, zVAR_, zVarAname, zVarAdataType, zVarAnumElements,

zNumDimsA, zDimSizesA, zVarArecVariance,

zVarAdimVariances, &zVarAnum_out,

PUT_, zVAR_ALLOCATERECS_, allocRecs3,

zVAR_BLOCKINGFACTOR_, blockingfactor3,

NULL_);

if (status < CDF_OK) QuitCDF ("7.0c", status);

/******************************************************************************

* PUT to variables.

******************************************************************************/

status = CDFlib (SELECT_, rVARs_RECNUMBER_, recNum,

NULL_);

if (status < CDF_OK) QuitCDF ("8.0", status);

for (x0 = 0; x0 < DIM_0_SIZE; x0++)

for (x1 = 0; x1 < DIM_1_SIZE; x1++) {

indices[0] = x0;

indices[1] = x1;

status = CDFlib (SELECT_, rVARs_DIMINDICES_, indices,

rVAR_, var1Num_out,

PUT_, rVAR_DATA_, &var1Values[x0][x1],

SELECT_, rVAR_, var2Num_out,

PUT_, rVAR_DATA_, &var2Values[x0][x1],

NULL_);

if (status < CDF_OK) QuitCDF ("8.1", status);

}

status = CDFlib (SELECT_, zVAR_, zVarAnum_out,

zVAR_RECNUMBER_, zRecNum,

NULL_);

if (status < CDF_OK) QuitCDF ("8.0z", status);

for (x0 = 0; x0 < zDIM_0_SIZEa; x0++) {

zIndicesA[0] = x0;

status = CDFlib (SELECT_, zVAR_DIMINDICES_, zIndicesA,

PUT_, zVAR_DATA_, zVarAvalues[x0],

NULL_);

if (status < CDF_OK) QuitCDF ("8.1z", status);

}

/******************************************************************************

* GET from the variables.

******************************************************************************/

for (x0 = 0; x0 < DIM_0_SIZE; x0++)

for (x1 = 0; x1 < DIM_1_SIZE; x1++) {

indices[0] = x0;

indices[1] = x1;

status = CDFlib (SELECT_, rVARs_DIMINDICES_, indices,

rVAR_, var1Num_out,

GET_, rVAR_DATA_, &var1Value_out,

SELECT_, rVAR_, var2Num_out,

GET_, rVAR_DATA_, &var2Value_out,

NULL_);

if (status < CDF_OK) QuitCDF ("9.0", status);

if (var1Value_out != var1Values[x0][x1]) QuitCDF ("9.1", status);

if (var2Value_out != var2Values[x0][x1]) QuitCDF ("9.2", status);

}

for (x0 = 0; x0 < zDIM_0_SIZEa; x0++) {

zIndicesA[0] = x0;

status = CDFlib (SELECT_, zVAR_DIMINDICES_, zIndicesA,

GET_, zVAR_DATA_, zVarAvalue_out,

NULL_);

if (status < CDF_OK) QuitCDF ("9.1z", status);

for (i = 0; i < zNUM_ELEMSa; i++) {

if (zVarAvalue_out[i] != zVarAvalues[x0][i]) QuitCDF ("9.2z", status);

}

/******************************************************************************

* HyperPUT to the variables.

******************************************************************************/

for (x0 = 0; x0 < DIM_0_SIZE; x0++)

for (x1 = 0; x1 < DIM_1_SIZE; x1++) {

var1Values[x0][x1] = -var1Values[x0][x1];

var2Values[x0][x1] = -var2Values[x0][x1];

}

indices[0] = 0;

indices[1] = 0;

status = CDFlib (SELECT_, rVARs_RECNUMBER_, recStart,

rVARs_RECCOUNT_, recCount,

rVARs_RECINTERVAL_, recInterval,

rVARs_DIMINDICES_, indices,

rVARs_DIMCOUNTS_, counts,

rVARs_DIMINTERVALS_, intervals,

rVAR_, var1Num_out,

PUT_, rVAR_HYPERDATA_, var1Values,

SELECT_, rVAR_, var2Num_out,

PUT_, rVAR_HYPERDATA_, var2Values,

NULL_);

if (status < CDF_OK) QuitCDF ("10.0", status);

for (x0 = 0; x0 < zDIM_0_SIZEa; x0++)

for (i = 0; i < zNUM_ELEMSa; i++) {

zVarAvalues[x0][i]++;

}

zIndicesA[0] = 0;

status = CDFlib (SELECT_, zVAR_RECNUMBER_, zRecStart,

zVAR_RECCOUNT_, zRecCount,

zVAR_RECINTERVAL_, zRecInterval,

zVAR_DIMINDICES_, zIndicesA,

zVAR_DIMCOUNTS_, zCounts,

zVAR_DIMINTERVALS_, zIntervals,

PUT_, zVAR_HYPERDATA_, zVarAvalues,

NULL_);

if (status < CDF_OK) QuitCDF ("10.0z", status);

/******************************************************************************

* HyperGET from variables.

******************************************************************************/

status = CDFlib (SELECT_, rVARs_RECNUMBER_, recStart,

rVARs_RECCOUNT_, recCount,

rVARs_RECINTERVAL_, recInterval,

rVARs_DIMINDICES_, indices,

rVARs_DIMCOUNTS_, counts,

rVARs_DIMINTERVALS_, intervals,

rVAR_, var1Num_out,

GET_, rVAR_HYPERDATA_, var1Buffer_out,

SELECT_, rVAR_, var2Num_out,

GET_, rVAR_HYPERDATA_, var2Buffer_out,

NULL_);

if (status < CDF_OK) QuitCDF ("11.0", status);

for (x0 = 0; x0 < DIM_0_SIZE; x0++)

for (x1 = 0; x1 < DIM_1_SIZE; x1++) {

if (var1Buffer_out[x0][x1] != var1Values[x0][x1])

QuitCDF ("11.1", status);

if (var2Buffer_out[x0][x1] != var2Values[x0][x1])

QuitCDF ("11.2", status);

}

status = CDFlib (GET_, zVAR_HYPERDATA_, zVarAbuffer_out,

NULL_);

if (status < CDF_OK) QuitCDF ("11.0z", status);

for (x0 = 0; x0 < zDIM_0_SIZEa; x0++)

for (i = 0; i < zNUM_ELEMSa; i++) {

if (zVarAbuffer_out[x0][i] != zVarAvalues[x0][i])

QuitCDF ("11.1z", status);

}

/******************************************************************************

* Confirm hyper parameters for a zVariable.

******************************************************************************/

status = CDFlib (CONFIRM_, zVAR_RECNUMBER_, &recStartOut,

zVAR_RECCOUNT_, &recCountOut,

zVAR_RECINTERVAL_, &recIntervalOut,

zVAR_DIMINDICES_, indicesOut,

zVAR_DIMCOUNTS_, countsOut,

zVAR_DIMINTERVALS_, intervalsOut,

NULL_);

if (status < CDF_OK) QuitCDF ("11a.0", status);

if (recStartOut != zRecStart) QuitCDF ("11a.1", status);

if (recCountOut != zRecCount) QuitCDF ("11a.2", status);

if (recIntervalOut != zRecInterval) QuitCDF ("11a.3", status);

for (dimN = 0; dimN < zN_DIMSa; dimN++) {

if (indicesOut[dimN] != zIndicesA[dimN]) QuitCDF ("11a.4", status);

if (countsOut[dimN] != zCounts[dimN]) QuitCDF ("11a.5", status);

if (intervalsOut[dimN] != zIntervals[dimN]) QuitCDF ("11a.6", status);

}

/******************************************************************************

* Set/confirm sequential access position for a zVariable (and read/write a

* value).

******************************************************************************/

status = CDFlib (SELECT_, zVAR_SEQPOS_, zRecStart, zIndicesA,

GET_, zVAR_SEQDATA_, zVarAvalue_out,

PUT_, zVAR_SEQDATA_, zVarAvalue_out,

CONFIRM_, zVAR_SEQPOS_, &recNumOut, indicesOut,

NULL_);

if (status < CDF_OK) QuitCDF ("11b.0", status);

if (recNumOut != zRecStart) QuitCDF ("11b.1", status);

if (indicesOut[0] != zIndicesA[0] + 2) QuitCDF ("11b.2", status);

/******************************************************************************

* Create attributes.

******************************************************************************/

status = CDFlib (CREATE_, ATTR_, attrName, attrScope, &attrNum_out,

ATTR_, attrName2, attrScope2, &attrNum_out,

ATTR_, attrName3, attrScope3, &attrNum_out,

NULL_);

if (status < CDF_OK) QuitCDF ("12.0", status);

/******************************************************************************

* PUT to attributes.

******************************************************************************/

status = CDFlib (SELECT_, ATTR_, 0L,

gENTRY_, entryNum,

PUT_, gENTRY_DATA_, entryDataType, entryNumElems,

&entryValue,

SELECT_, ATTR_, 1L,

rENTRY_NAME_, var2Name,

PUT_, rENTRY_DATA_, CDF_BYTE, 1L, &rEntryValue,

SELECT_, ATTR_, 2L,

zENTRY_NAME_, zVarAname,

PUT_, zENTRY_DATA_, CDF_REAL8, 1L, &zEntryValue,

NULL_);

if (status < CDF_OK) QuitCDF ("13.0", status);

/******************************************************************************

* Confirm entry numbers.

******************************************************************************/

status = CDFlib (CONFIRM_, gENTRY_, &entryNumOut1,

rENTRY_, &entryNumOut2,

zENTRY_, &entryNumOut3,

NULL_);

if (status < CDF_OK) QuitCDF ("13a.0", status);

if (entryNumOut1 != 1) QuitCDF ("13a.1", status);

if (entryNumOut2 != 1) QuitCDF ("13a.2", status);

if (entryNumOut3 != 0) QuitCDF ("13a.3", status);

/******************************************************************************

* GET from attributes.

******************************************************************************/

status = CDFlib (SELECT_, ATTR_, 0L,

gENTRY_, entryNum,

CONFIRM_, CURgENTRY_EXISTENCE_,

GET_, gENTRY_DATA_, &entryValue_out,

NULL_);

if (status < CDF_OK) QuitCDF ("14.0.1", status);

status = CDFlib (SELECT_, ATTR_, 1L,

rENTRY_, 1L,

CONFIRM_, CURrENTRY_EXISTENCE_,

GET_, rENTRY_DATA_, &rEntryValueOut,

NULL_);

if (status < CDF_OK) QuitCDF ("14.0.2", status);

status = CDFlib (SELECT_, ATTR_, 2L,

zENTRY_, 0L,

CONFIRM_, CURzENTRY_EXISTENCE_,

GET_, zENTRY_DATA_, &zEntryValueOut,

NULL_);

if (status < CDF_OK) QuitCDF ("14.0.3", status);

if (entryValue_out != entryValue) QuitCDF ("14.1", status);

if (rEntryValue != rEntryValueOut) QuitCDF ("14.2", status);

if (zEntryValue != zEntryValueOut) QuitCDF ("14.3", status);

/******************************************************************************

* Confirm existence of variables/attributes/entries.

******************************************************************************/

status = CDFlib (CONFIRM_, zVAR_EXISTENCE_, zVarAname,

rVAR_EXISTENCE_, var1Name,

ATTR_EXISTENCE_, attrName3,

NULL_);

if (status < CDF_OK) QuitCDF ("14a.0", status);

status = CDFlib (SELECT_, ATTR_, 0L,

CONFIRM_, gENTRY_EXISTENCE_, entryNum,

SELECT_, ATTR_, 1L,

CONFIRM_, rENTRY_EXISTENCE_, 1L,

SELECT_, ATTR_, 2L,

CONFIRM_, zENTRY_EXISTENCE_, 0L,

NULL_);

if (status < CDF_OK) QuitCDF ("14a.1", status);

/******************************************************************************

* Get CDF documentation.

******************************************************************************/

status = CDFlib (GET_, LIB_VERSION_, &version_out,

LIB_RELEASE_, &release_out,

LIB_INCREMENT_, &increment_out,

LIB_subINCREMENT_, &subincrement_out,

LIB_COPYRIGHT_, CopyRightText,

NULL_);

if (status < CDF_OK) QuitCDF ("15.0", status);

/******************************************************************************

* Inquire CDF.

******************************************************************************/

status = CDFlib (GET_, CDF_FORMAT_, &formatOut,

rVARs_NUMDIMS_, &numDims_out,

rVARs_DIMSIZES_, dimSizes_out,

CDF_ENCODING_, &encoding_out,

CDF_MAJORITY_, &majority_out,

rVARs_MAXREC_, &maxRec_out,

CDF_NUMrVARS_, &numRvars,

CDF_NUMzVARS_, &numZvars,

CDF_NUMATTRS_, &numAttrs_out,

NULL_);

if (status < CDF_OK) QuitCDF ("16.0", status);

if (formatOut != SINGLE_FILE) QuitCDF ("16.1o", status);

if (numDims_out != numDims) QuitCDF ("16.1", status);

for (x = 0; x < N_DIMS; x++)

if (dimSizes_out[x] != dimSizes[x]) QuitCDF ("16.2", status);

if (encoding_out != actual_encoding) QuitCDF ("16.3", status);

if (majority_out != majority) QuitCDF ("16.4", status);

if (maxRec_out != 0) QuitCDF ("16.5", status);

if (numRvars != 2) QuitCDF ("16.6", status);

if (numZvars != 1) QuitCDF ("16.6z", status);

if (numAttrs_out != 3) QuitCDF ("16.7", status);

/******************************************************************************

* Inquire numbers.

******************************************************************************/

status = CDFlib (GET_, ATTR_NUMBER_, attrName3, &attrNum_out,

rVAR_NUMBER_, var2Name, &varNum_out1,

zVAR_NUMBER_, zVarAname, &varNum_out2,

NULL_);

if (status < CDF_OK) QuitCDF ("16a.0", status);

if (attrNum_out != 2) QuitCDF ("16a.1", status);

if (varNum_out1 != 1) QuitCDF ("16a.2", status);

if (varNum_out2 != 0) QuitCDF ("16a.3", status);

/******************************************************************************

* Rename variables.

******************************************************************************/

status = CDFlib (SELECT_, rVAR_NAME_, var1Name,

PUT_, rVAR_NAME_, new_var1Name,

NULL_);

if (status < CDF_OK) QuitCDF ("17.0a", status);

status = CDFlib (SELECT_, rVAR_NAME_, var2Name,

PUT_, rVAR_NAME_, new_var2Name,

NULL_);

if (status < CDF_OK) QuitCDF ("17.0b", status);

status = CDFlib (SELECT_, zVAR_NAME_, zVarAname,

PUT_, zVAR_NAME_, new_zVarAname,

NULL_);

if (status < CDF_OK) QuitCDF ("17.0c", status);

/******************************************************************************

* Read/write multiple variable data.

******************************************************************************/

status = CDFlib (SELECT_, rVARs_RECNUMBER_, 2L,

PUT_, rVARs_RECDATA_, nRvars, rVarNs, rVarsRecBuffer,

SELECT_, zVARs_RECNUMBER_, 2L,

PUT_, zVARs_RECDATA_, nZvars, zVarNs, zVarsRecBuffer,

NULL_);

if (status < CDF_OK) QuitCDF ("17.0d", status);

status = CDFlib (GET_, rVARs_RECDATA_, nRvars, rVarNs, rVarsRecBufferOut,

GET_, zVARs_RECDATA_, nZvars, zVarNs, zVarsRecBufferOut,

NULL_);

if (status < CDF_OK) QuitCDF ("17.0e", status);

if (memcmp(rVarsRecBufferOut,rVarsRecBuffer,

sizeof(rVarsRecBuffer))) QuitCDF ("17.0f", status);

if (memcmp(zVarsRecBufferOut,zVarsRecBuffer,

sizeof(zVarsRecBuffer))) QuitCDF ("17.0g", status);

/******************************************************************************

* Inquire variables.

******************************************************************************/

status = CDFlib (SELECT_, rVAR_, var1Num_out,

GET_, rVAR_NAME_, var1Name_out,

rVAR_DATATYPE_, &var1DataType_out,

rVAR_NUMELEMS_, &var1NumElements_out,

rVAR_RECVARY_, &var1RecVariance_out,

rVAR_DIMVARYS_, var1DimVariances_out,

rVAR_BLOCKINGFACTOR_, &blockingfactorOut1,

rVAR_MAXallocREC_, &maxAllocOut1,

rVAR_MAXREC_, &maxRecOut1,

rVAR_nINDEXRECORDS_, &nIndexRecsOut1,

rVAR_nINDEXENTRIES_, &nIndexEntriesOut1,

CONFIRM_, rVAR_, &var1Num_out,

NULL_);

if (status < CDF_OK) QuitCDF ("18.0a", status);

if (strcmp(var1Name_out,new_var1Name) != 0) QuitCDF ("18.11", status);

if (var1DataType_out != var1DataType) QuitCDF ("18.12", status);

if (var1NumElements_out != var1NumElements) QuitCDF ("18.13", status);

if (var1RecVariance_out != var1RecVariance) QuitCDF ("18.14", status);

if (var1Num_out != 0L) QuitCDF ("18.14a", status);

if (blockingfactorOut1 != blockingfactor1) QuitCDF ("18.14b", status);

if (maxAllocOut1 + 1 != allocRecs1) QuitCDF ("18.14c", status);

if (maxRecOut1 != 2L) QuitCDF ("18.14d", status);

for (dim_n = 0; dim_n < numDims; dim_n++) {

if (var1DimVariances_out[dim_n] != var1DimVariances[dim_n]) {

QuitCDF ("18.14", status);

}

status = CDFlib (SELECT_, rVAR_, var2Num_out,

GET_, rVAR_NAME_, var2Name_out,

rVAR_DATATYPE_, &var2DataType_out,

rVAR_NUMELEMS_, &var2NumElements_out,

rVAR_RECVARY_, &var2RecVariance_out,

rVAR_DIMVARYS_, var2DimVariances_out,

rVAR_BLOCKINGFACTOR_, &blockingfactorOut2,

rVAR_MAXallocREC_, &maxAllocOut2,

rVAR_MAXREC_, &maxRecOut2,

rVAR_nINDEXRECORDS_, &nIndexRecsOut2,

rVAR_nINDEXENTRIES_, &nIndexEntriesOut2,

CONFIRM_, rVAR_, &var2Num_out,

NULL_);

if (status < CDF_OK) QuitCDF ("18.0b", status);

if (strcmp(var2Name_out,new_var2Name) != 0) QuitCDF ("18.21", status);

if (var2DataType_out != var2DataType) QuitCDF ("18.22", status);

if (var2NumElements_out != var2NumElements) QuitCDF ("18.23", status);

if (var2RecVariance_out != var2RecVariance) QuitCDF ("18.24", status);

if (var2Num_out != 1L) QuitCDF ("18.24a", status);

if (blockingfactorOut2 != blockingfactor2) QuitCDF ("18.24b", status);

if (maxAllocOut2 + 1 != allocRecs2) QuitCDF ("18.24c", status);

if (maxRecOut2 != 2L) QuitCDF ("18.24d", status);

for (dim_n = 0; dim_n < numDims; dim_n++) {

if (var2DimVariances_out[dim_n] != var2DimVariances[dim_n]) {

QuitCDF ("18.25", status);

}

status = CDFlib (SELECT_, zVAR_, zVarAnum_out,

GET_, zVAR_NAME_, zVarAname_out,

zVAR_DATATYPE_, &zVarAdataType_out,

zVAR_NUMELEMS_, &zVarAnumElements_out,

zVAR_RECVARY_, &zVarArecVariance_out,

zVAR_DIMVARYS_, zVarAdimVariances_out,

zVAR_NUMDIMS_, &zNumDimsA_out,

zVAR_DIMSIZES_, zDimSizesA_out,

zVAR_BLOCKINGFACTOR_, &blockingfactorOut3,

zVAR_MAXallocREC_, &maxAllocOut3,

zVAR_MAXREC_, &maxRecOut3,

zVAR_nINDEXRECORDS_, &nIndexRecsOut3,

zVAR_nINDEXENTRIES_, &nIndexEntriesOut3,

NULL_);

if (status < CDF_OK) QuitCDF ("18.0c1", status);

status = CDFlib (CONFIRM_, zVAR_, &zVarAnum_out,

NULL_);

if (status < CDF_OK) QuitCDF ("18.0c2", status);

if (strcmp(zVarAname_out,new_zVarAname) != 0) QuitCDF ("18.21z", status);

if (zVarAdataType_out != zVarAdataType) QuitCDF ("18.22z", status);

if (zVarAnumElements_out != zVarAnumElements) QuitCDF ("18.23z", status);

if (zVarArecVariance_out != zVarArecVariance) QuitCDF ("18.24z", status);

if (zNumDimsA_out != zNumDimsA) QuitCDF ("18.25z", status);

if (zVarAnum_out != 0L) QuitCDF ("18.26z", status);

if (blockingfactorOut3 != blockingfactor3) QuitCDF ("18.26z1", status);

if (maxAllocOut3 + 1 != allocRecs3) QuitCDF ("18.26z2", status);

if (maxRecOut3 != 2L) QuitCDF ("18.26z3", status);

for (dim_n = 0; dim_n < zNumDimsA; dim_n++) {

if (zDimSizesA_out[dim_n] != zDimSizesA[dim_n]) {

QuitCDF ("18.27z", status);

}

if (zVarAdimVariances_out[dim_n] != zVarAdimVariances[dim_n]) {

QuitCDF ("18.28z", status);

}

/******************************************************************************

* Rename attribute.

******************************************************************************/

status = CDFlib (SELECT_, ATTR_NAME_, attrName,

PUT_, ATTR_NAME_, new_attrName,

NULL_);

if (status < CDF_OK) QuitCDF ("20.0", status);

/******************************************************************************

* Inquire attribute.

******************************************************************************/

status = CDFlib (GET_, ATTR_NAME_, attrName_out,

ATTR_SCOPE_, &attrScope_out,

ATTR_MAXgENTRY_, &maxEntry_out,

CONFIRM_, ATTR_, &attrNum_out,

NULL_);

if (status < CDF_OK) QuitCDF ("22.0", status);

if (strcmp(attrName_out,new_attrName) != 0) QuitCDF ("22.1", status);

if (attrScope_out != attrScope) QuitCDF ("22.2", status);

if (maxEntry_out != entryNum) QuitCDF ("22.3", status);

if (attrNum_out != 0L) QuitCDF ("22.4", status);

/******************************************************************************

* Inquire attribute entries.

******************************************************************************/

status = CDFlib (SELECT_, ATTR_, 0L,

gENTRY_, entryNum,

GET_, gENTRY_DATATYPE_, &entryDataType_out,

gENTRY_NUMELEMS_, &entryNumElems_out,

NULL_);

if (status < CDF_OK) QuitCDF ("23.0", status);

if (entryDataType_out != entryDataType) QuitCDF ("23.1", status);

if (entryNumElems_out != entryNumElems) QuitCDF ("23.1", status);

status = CDFlib (SELECT_, ATTR_, 1L,

rENTRY_, 1L,

GET_, rENTRY_DATATYPE_, &entryDataType_out,

rENTRY_NUMELEMS_, &entryNumElems_out,

NULL_);

if (status < CDF_OK) QuitCDF ("23a.0", status);

if (entryDataType_out != CDF_BYTE) QuitCDF ("23a.1", status);

if (entryNumElems_out != 1L) QuitCDF ("23a.1", status);

status = CDFlib (SELECT_, ATTR_, 2L,

zENTRY_, 0L,

GET_, zENTRY_DATATYPE_, &entryDataType_out,

zENTRY_NUMELEMS_, &entryNumElems_out,

NULL_);

if (status < CDF_OK) QuitCDF ("23b.0", status);

if (entryDataType_out != CDF_REAL8) QuitCDF ("23b.1", status);

if (entryNumElems_out != 1L) QuitCDF ("23b.1", status);

/******************************************************************************

* Get error text.

******************************************************************************/

status = CDFlib (SELECT_, CDF_STATUS_, CDF_OK,

GET_, STATUS_TEXT_, errorText,

NULL_);

if (status < CDF_OK) QuitCDF ("24.0", status);

/******************************************************************************

* Select zMode and inquire CDF.

******************************************************************************/

status = CDFlib (SELECT_, CDF_zMODE_, zMODEon2,

NULL_);

if (status < CDF_OK) QuitCDF ("25.0a", status);

status = CDFlib (SELECT_, ATTR_, 0L,

GET_, CDF_NUMgATTRS_, &numGattrs,

CDF_NUMvATTRS_, &numVattrs,

CDF_NUMrVARS_, &numRvars,

CDF_NUMzVARS_, &numZvars,

ATTR_MAXgENTRY_, &maxGentry,

ATTR_NUMgENTRIES_, &numGentries,

zVARs_MAXREC_, &maxRecOut,

NULL_);

if (status < CDF_OK) QuitCDF ("25.0b", status);

status = CDFlib (SELECT_, ATTR_, 1L,

GET_, ATTR_MAXrENTRY_, &maxRentry,

ATTR_NUMrENTRIES_, &numRentries,

ATTR_MAXzENTRY_, &maxZentry,

ATTR_NUMzENTRIES_, &numZentries,

NULL_);

if (status < CDF_OK) QuitCDF ("25.0c", status);

status = CDFlib (SELECT_, CDF_zMODE_, zMODEoff,

NULL_);

if (status < CDF_OK) QuitCDF ("25.0d", status);

if (numGattrs != 1) QuitCDF ("25.1", status);

if (numVattrs != 2) QuitCDF ("25.1a", status);

if (numRvars != 0) QuitCDF ("25.1b", status);

if (numZvars != 3) QuitCDF ("25.2", status);

if (maxGentry != entryNum) QuitCDF ("25.3", status);

if (numGentries != 1) QuitCDF ("25.4", status);

if (maxRentry != -1) QuitCDF ("25.5", status);

if (numRentries != 0) QuitCDF ("25.6", status);

if (maxZentry != 1) QuitCDF ("25.7", status);

if (numZentries != 1) QuitCDF ("25.8", status);

if (maxRecOut != 2L) QuitCDF ("25.9", status);

/******************************************************************************

* Attempt to close variables.

******************************************************************************/

status = CDFlib (SELECT_, rVAR_, 0L,

CLOSE_, rVAR_,

NULL_);

if (status != SINGLE_FILE_FORMAT) QuitCDF ("26.0", status);

status = CDFlib (SELECT_, zVAR_, 0L,

CLOSE_, zVAR_,

NULL_);

if (status != SINGLE_FILE_FORMAT) QuitCDF ("26.1", status);

/******************************************************************************

* Modify entries/attribute.

******************************************************************************/

status = CDFlib (SELECT_, ATTR_, 0L,

gENTRY_, entryNum,

PUT_, gENTRY_DATASPEC_, entryDataTypeNew, entryNumElems,

NULL_);

if (status < CDF_OK) QuitCDF ("26a.0a", status);

status = CDFlib (SELECT_, ATTR_, 1L,

rENTRY_, 1L,

PUT_, rENTRY_DATASPEC_, CDF_UINT1, 1L,

NULL_);

if (status < CDF_OK) QuitCDF ("26a.0b", status);

status = CDFlib (SELECT_, ATTR_, 2L,

zENTRY_, 0L,

PUT_, zENTRY_DATASPEC_, CDF_EPOCH, 1L,

NULL_);

if (status < CDF_OK) QuitCDF ("26a.0c", status);

status = CDFlib (SELECT_, ATTR_, 0L,

PUT_, ATTR_SCOPE_, VARIABLE_SCOPE,

ATTR_SCOPE_, GLOBAL_SCOPE,

NULL_);

if (status < CDF_OK) QuitCDF ("26a.0d", status);

/******************************************************************************

* Delete entries/attribute/variables.

******************************************************************************/

status = CDFlib (SELECT_, ATTR_, 0L,

gENTRY_, entryNum,

DELETE_, gENTRY_,

SELECT_, ATTR_, 1L,

rENTRY_, 1L,

DELETE_, rENTRY_,

SELECT_, ATTR_, 2L,

zENTRY_, 0L,

DELETE_, zENTRY_,

NULL_);

if (status < CDF_OK) QuitCDF ("25a.0.1", status);

status = CDFlib (SELECT_, ATTR_, 0L,

DELETE_, ATTR_,

SELECT_, rVAR_, 0L,

DELETE_, rVAR_,

SELECT_, zVAR_, 0L,

DELETE_, zVAR_,

NULL_);

if (status < CDF_OK) QuitCDF ("25a.0.2", status);

/******************************************************************************

* Close CDF.

******************************************************************************/

status = CDFlib (CLOSE_, CDF_,

NULL_);

if (status < CDF_OK) QuitCDF ("26.2", status);

/******************************************************************************

* Successful completion.

******************************************************************************/

return EXIT_SUCCESS_;

}

/******************************************************************************

* QuitCDF.

******************************************************************************/

void QuitCDF (where, status)

char *where;

CDFstatus status;

{

char text[CDF_STATUSTEXT_LEN+1];

printf ("Aborting at %s...\n", where);

if (status < CDF_OK) {

CDFlib (SELECT_, CDF_STATUS_, status,

GET_, STATUS_TEXT_, text,

NULL_);

printf ("%s\n", text);

}

CDFlib (CLOSE_, CDF_,

NULL_);

printf ("...test aborted.\n");

exit (EXIT_FAILURE_);

}

[1] Programming reference manuals for C and Fortran users are provided as separate documents.

[2] The “r” stands for “regular.” rVariables are the type of variables that CDF has always supported. Perhaps “traditional” would have been a better term.

[3] The “z” doesn’t stand for anything special. We just like the letter “z.”

[4] This is generally not recommended. In those situations where z variables are necessary it is best to use all zVariables than a mixture of rVariables and zVariables.

[6] These features are covered in the following sections.

[7] Although rVariables are described here first, the trend among CDF users is toward CDFs containing only zVariables (since zVariables can do everything rVariables can do and more). zVariables are described in the next section.

[8] The notation for dimensionality used here is <num-dims>:[<dim-sizes>] where <num-dims> is the number of dimensions and <dim-sizes> is zero or more dimension sizes separated by commas.

[9] The notation for variances used here is <rec-vary>/<dim-varys> where <rec-vary> is the record variance, T (TRUE) or F (false), and <dim-varys> is zero or more dimension variances.

[10] CDFedit has replaced CDFbrowse. The alias/symbol CDFbrowse still exists in the "definitions" file on UNIX/VMS systems but now executes CDFedit in a browse-only mode.

[11] CDFexport has replaced CDFlist and CDFwalk.

[12] SkeletonCDF was previously named CDFskeleton

[13] PC running CYGWIN or Mac OS X can be considered a UNIX box while running the CDF tool programs.

[14] This notation is used to specify a function to be performed on an item. The syntax is <function_,item_>.

[15] There are actually two types of zMode – read on.

[16] In a future release of CDF, support for rVariables will be eliminated. zMode is provided to ease the transition from rVariables to the more exible zVariables. rVariables are essentially a subset of zVariables.

[17] This notation is used throughout this document. In this case there are two dimensions whose sizes are 180 and 360. Adimensionality of zero is represented as 0:[].

[18] This notation is also used throughout this document. The record variance is before the slash and the dimension variances.

[19] This alos applies to the uncompressed CDF that is maintained as a scratch file.

[20] 6The file of a CDF having an extension of .cdf is referred to as the dotCDF file.

[21] Actually, the CDF library will check several possible extensions: .cdf, .cdf;1, .CDF, and .CDF;1. These extensions are checked because some CD-ROM drivers (primarily on UNIX machines) do peculiar things when making the files (e.g., CDFs) on a CD-ROM visible.

[24] This notation is used when an operation exists for both rVariables and zVariables. In this case, the actual operations are <GET_,zVAR_nINDEXLEVELS_> and <GET_,rVAR_nINDEXLEVELS_>.

[25] This is a change from previous releases of CDF.

[26] Compression is not allowed with multi-file CDFs.

[27] Previous releases of CDF limited the number of variables a CDF could contain. That limit has been eliminated except for multi-file CDFs on an PC because of the 8.3 naming convention.

[28] The letters "r" and "z" don't stand for anything in particular. "r" sort of stands for "regular" since rVariables have always been supported by CDF. However, for Java APIs, only zVariables are supported.

[29] It is required that an application close a CDF before exiting.

[30] Variables may not currently be deleted from a multi-file CDF.

[31] Sparse records are not allowed for a variable in a multi-file CDF.

[32] There is no reason to allocate records for a variable in a multi-file CDF.

[33] The use of allocated records would in most cases be more efficient than specifying initial records.

[34] A variable’s blocking factor was previously called its “extend records.”

[35] Variable records may be deleted from a multi-file CDF.

[36] Note that variable compression is not allowed in a multi-file CDF.

[37] Since an application knows how it will be accessing a variable, it knows best how to optimize the caching scheme used. See Section 2.1.5 for details on how an application can control the CDF library caching scheme.

[38] This notation is used throughout this document. The data type is before the slash and the number of elements is after the slash. In this case the data type is (CDF INT2) and the number of elements is one (1).

[39]These were previously known as fill values but were renamed to avoid confusion with the FILLVAL attribute.

[40] These default pad values can be changed by your system manager when the CDF distribution is built.

[41] This was not necessarily the case in previous releases of CDF. These new restrictions should not, however, cause any conicts with existing applications.

[42] I know what you're thinking. The year 0 AD never existed. If it makes you feel better, think of the epoch year as 1 BC (or simply year 0) rather than 0 AD. Also, year 0 is considered to be a leap year.

[43] OPTIMAL ENCODING TREES causes each buffer of data to be scanned for the best possible compression. An alternative method would be to scan the first buffer being compressed and then use the same byte value frequencies for subsequent buffers.

[44] CDFedit and CDFexport are not yet available. You can still use the Curses-based tools from the distribution.

[45] Macintosh folders are equivalent to the directories discussed here.

[46] These special attributes originated as part of the NSSDC standard for CDFs. The NSSDC standard is no longer used.

[47] Note that the FILLVAL attribute is not the same as the pad value for a variable although their values will often be the same.The pad value is used by the CDF library. The FILLVAL attribute is optionally used by a CDF toolkit program or by your applications.

[48] Running CDFedit in a browse-only mode provides the same functionality as CDFbrowse once did.

[49] It is our intention that the use of CDFedit be as intuitive as possible. You may not even need the online help. We're sure you'll let us know.

[50] On MS-DOS systems the executable is named CDFXP.EXE.

[51] On MS-DOS systems the executable is named CDFCVT.EXE.

[52] On MS-DOS systems the executable is named CDFCMP.EXE.

[53] On MS-DOS systems the executable is named CDF2SKT.EXE.

[54] This program was originally named CDFskeleton. It has been renamed to ease the confusion caused some users. Now, SkeletonCDF is used to create skeleton CDFs and SkeletonTable is used to create skeleton tables.

[55] On MS-DOS systems the executable is named SKT2CDF.EXE.

[56] On MS-DOS systems the executable is named CDFINQ.EXE.

[57] CDFdir is not available on Macintosh or Windows NT/95/98 systems. It is also not available from Java/UNIX.

[58] The alias/symbol for CDFbrowse still exists in the "definitions" file on UNIX/VMS systems but now executes CDFedit in a browse-only mode.

[59] 1In previous CDF releases, when using the Internal Interface it was required that the current CDF be selected in each call to CDFlib. This is no longer necessary. The current CDF is now maintained from one call to the next of CDFlib (as is the current status code).

[60] Batch files are also known as include files.

[61] The batch file cdf0.pro is also available that serves the same purpose. The only difference is that its structure variable names are longer.

[62] At least this used to be the case. IDL seems to be using a new online help facility that does not recognize user supplied help files.

[63] With the exception of the multiple variable access operations available via the Internal Interface (<GET_,rVARs_RECDATA_>, <PUT_,rVARs_RECDATA_>, <GET_,zVARs_RECDATA_>, and <PUT_,zVARs_RECDATA_>). Because these operations deal with variables having different data types, the use of structures to store the values would be the logical method to use. Unfortunately, IDL does not currently support the manipulation of structures from within a C application (which is how CDF's IDL interface is implemented). Support of these operations will hopefully be added in the future.

[64] On DEC Alpha's running OSF/1, don't confuse the C data type of long with IDL's data type of TYP LONG. The C long is eight bytes while IDL's TYP LONG is four bytes.

[65] If an array in a call to a CDF function won't be used because a variable is 0-dimensional, a dummy array must still be passed to avoid an error from the CDF library. Note that embedding a call to lonarr [such as lonarr(1)] in the call to the CDF function will work but will result in a memory leak because the allocated array will not be freed.

[66] The status code BAD BLOCKING FACTOR was previously named BAD_EXTEND RECS.

Record	rVariables
Number	Time	Longitude	Latitude	Temperature

1	0000 – 0000 \| \| 0000 – 0000	-165 – -150 \| \| -165 – -150	+40 – +40 \| \| +30 – +30	20.0 – 19.2 \| \| 21.7 – 20.7

2	0100 – 0000 \| \| 0000 – 0000	-165 – -150 \| \| -165 – -150	+40 – +40 \| \| +30 – +30	18.2 – 22.0 \| \| 19.3 – 19.2

3	0200 – 0000 \| \| 0000 – 0000	-165 – -150 \| \| -165 – -150	+40 – +40 \| \| +30 – +30	19.9 – 19.6 \| \| 19.3 – 19.0
.
.
.

6	2300 – 0000 \| \| 0000 – 0000	-165 – -150 \| \| -165 – -150	+40 – +40 \| \| +30 – +30	21.0 – 18.4 \| \| 19.5 – 22.0