CDF C PROGRAMMING REFERENCE FILE: CDFcRef.doc RELEASE: CDF version 2.0 AUTHOR: D. Grogan DATE: 11 February 1991 Table of Contents *- Abstract *- Naming Conventions *- Pre-Defined Constants and Types *-- Defined Types *-- CDFstatus Threshold Constants *-- CDF Datatypes *-- Limits of Names and Other Character Strings *-- Other Limits *-- Miscellaneous Parameters *- Function Reference *-- Global CDF Access Functions CDFcreate() CDFopen() CDFdoc() CDFinquire() CDFclose() CDFdelete() CDFerror() *-- Attribute Access Functions CDFattrCreate() CDFattrNum() CDFattrRename() CDFattrInquire() CDFattrEntryInquire() CDFattrPut() CDFattrGet() CDFattrCorrectScope() *-- Variable Access Functions CDFvarCreate() CDFvarNum() CDFvarRename() CDFvarInquire() CDFvarPut() CDFvarGet() CDFvarHyperPut() CDFvarHyperGet() *- Interface Summary: ANSI Function Prototypes *- Rules for Testing A CDFstatus Value *- Appendix A CDF Version 2.0 status codes *- Abstract This document provides a reference for using the CDF version 2 library from C language applications. A separate reference exists for writing applications in Fortran. CDF version 2 function protocols have been revised significantly from version 1. If you must continue to use existing CDF applications or if you need to upgrade an existing version 1 application, please see the Release Notes for CDF Version 2 first. *- Naming Conventions Function and argument names correspond closely to those of version 1 with these rules applied: 1) "CDF" prefixes all function names (as before, in version 1). 2) Underscores have been removed from function names to distinguish the C interface from the Fortran interface. Underscores have also been removed from argument names. Where possible, we have kept the argument names similar to those of version 1. 3) For easy visual recognition, an uppercase letter fills the previous role of underscores. A meaningful word in a function- or argument-name is introduced by a capital letter unless that word begins a name or immediately follows another capital. Thus, for instance, CDF_var_create becomes CDFvarCreate, and num_dims becomes numDims. Argument names are usually conjunctions of abbreviated phrases indicating both their usage and meaning. These abbreviations are applied: attr -- always refers to a CDF attribute. var -- always refers to a CDF variable. num -- means "number of" objects when preceding another name, or "object-number" when following another name. dim -- abbreviates "dimension". rec -- abbreviates "record", meaning a CDF record. Where appropriate, the names of array arguments have been made plural to indicate that an argument is an array type. For instance, an index vector, which is an array of integers, is always referred to as "indices". Likewise, dimVariances indicates an array of dimension variance flags. CDF constants, defined in cdf.h, are written in all uppercase, some with and some without underscores. *- Pre-Defined Constants and Types The following constants and types are defined for use by all CDF applications programs. Use this header file: #include "cdf.h" *-- Defined Types CDFstatus All CDF functions except CDFvarNum() and CDFattrNum() are of type CDFstatus; they return a status code indicating the condition of the function. A CDFstatus value of CDF_OK is the normal condition for all functions returning a CDFstatus. Any value of CDFstatus < CDF_OK indicates a non-normal condition occurring in a function. CDFerror() can be used to look up the meaning of any CDFstatus value. CDFid An identifier (or handle) for a CDF, which must be used in all CDF function references. A new CDFid is established whenever a CDF is created or opened, establishing a connection to a CDF file set named on a disk. The CDFid is used in all subsequent operations on a particular CDF. A CDFid variable must not be altered by an application. *-- CDFstatus Threshold Constants CDF_OK A threshold constant indicating a normal condition of a CDF function. CDF_WARN Threshold constant for testing severity of non-normal CDF status values. See the section below on CDFstatus Codes and Messages for all non-normal conditions. *-- CDF Datatypes All CDF datatypes are based on an 8-bit byte except on those machines which do not operate on an 8-bit boundary (i.e. CRAY). One of the following constants must be used in any place requiring a CDF datatype. CDF_BYTE 1-byte, signed integer. CDF_CHAR " (a "string" datatype) CDF_INT1 " CDF_UCHAR 1-byte, unsigned integer. (a "string" datatype) CDF_UINT1 " CDF_INT2 2-byte, signed integer. CDF_UINT2 2-byte, unsigned integer. CDF_INT4 4-byte, signed integer. CDF_UINT4 4-byte, unsigned integer. CDF_REAL4 4-byte, real number. CDF_FLOAT " CDF_REAL8 8-byte, real number. CDF_DOUBLE " *-- Limits of Names and Other Character Strings CDF_PATHNAME_LEN Maximum length of a CDF name, not counting a null terminator or the ".cdf" or ".vnn" appended to the CDF name to construct filenames. A CDF name may contain disk and directory specifications that conform to your system's rules for pathnames. CDF_VAR_NAME_LEN Maximum length of a variable name, excluding the null. CDF_ATTR_NAME_LEN Maximum length of an attribute name, excluding null. (Any of the three types of names above will be truncated when they are too long.) CDF_DOCUMENT_LEN Length of the text string written by CDFdoc(), excluding the null. CDF_ERRTEXT_LEN Length of the text string written by CDFerror(), excluding the null. *-- Other Limits CDF_MAX_DIMS Maximum number of dimensions for any CDF. CDF_MAX_VARS Maximum number of variables for any CDF. CDF_MAX_CDFS Maximum number of CDFs that may be open at one time. (The CDF library imposes no limit on the number of attributes that a CDF may have.) *-- Miscellaneous Parameters HOST_ENCODING Indicates native machine data representation. NETWORK_ENCODING Indicates transportable data representation (XDR). VAX_ENCODING Indicates VAX data representation. SUN_ENCODING Indicates SUN representation. ROW_MAJOR C-like array ordering for variable storage. COL_MAJOR Fortran-like array ordering for variable storage. VARY TRUE record- or dimension-variance flag. NOVARY FALSE record- or dimension-variance flag. The next four constants are used to define an attribute's scope. The first two scopes are called the definite scopes of an attribute; the second two are indefinite scopes provided to bridge between version 1 and version 2 CDFs. (See also notes to the function CDFattrCorrectScope.) GLOBAL_SCOPE Indicates that an attribute's scope is global (applies to the CDF as a whole). VARIABLE_SCOPE Indicates that an attribute's scope is not global (applies to each variable individually). GLOBAL_SCOPE_ASSUMED Indicates an attribute's scope is assumed global. VARIABLE_SCOPE_ASSUMED Indicates an attribute's scope is assumed not global. *- Function Reference There are 23 CDF functions in 3 categories -- 7 for top-level CDF management, 8 for using CDF attributes, and 8 for using CDF variables. All operations on a CDF require a handle of type CDFid to identify the CDF. A CDFid is used in CDF functions similar to the way a file pointer is used in C for file operations. A CDFid variable is initialized only by a successful CDFcreate() or CDFopen(); all other CDF functions require a properly initialized CDFid as their first argument. Like file pointers, you should not alter a CDFid variable directly. Unlike file pointers, there is never a need to examine or compare a CDFid, since the return status of CDF functions will indicate problems that arise. Also, remember that the CDFid does not refer to just one file, but is a handle to a set of files that comprise any particular CDF. *-- Global CDF Access Functions These seven functions provide the basic operations on CDFs: CDFstatus CDFcreate(); CDFstatus CDFopen(); CDFstatus CDFdoc(); CDFstatus CDFinquire(); CDFstatus CDFclose(); CDFstatus CDFdelete(); CDFstatus CDFerror(); CDFstatus CDFcreate( char *CDFname, /* in -- CDF path name (external name) */ long numDims, /* in -- number of dims, 0..CDF_MAX_DIMS */ long dimSizes[], /* in -- size for each declared dimension */ long encoding, /* in -- HOST_ENCODING, NETWORK_ENCODING */ long majority, /* in -- ROW_MAJOR, COL_MAJOR vectors */ CDFid *id); /* out-- CDF id */ Function description: Create a CDF as defined by the arguments. The name is given by the first argument. The string ".cdf" is appended to the CDFname to create a CDF header file, "CDFname.cdf". Thus, CDFname must be a legitimate pathname for files on your system. You cannot create a CDF that already exists. If you wish to re-create a particular CDF, you should first open it with CDFopen(), delete it with CDFdelete(), and then re-create it with CDFcreate(). If it is impossible to open or delete it successfully through the CDF library, you must delete the CDF header file (CDFname.cdf) and all its variable files (CDFname.vnn) from your system's command level. Arguments 2 through 5 will determine fixed characteristics of the CDF that cannot be changed without re-creating it. numDims specifies the dimensionality of the CDF and dimSizes[0] through dimSizes[numDims-1] specifies, respectively, the size of each dimension. The encoding argument determines what internal data representation will be used for the CDF. Use NETWORK_ENCODING when you must be able to transfer CDFs between machines with a different data representation, as between VAXes and Suns. However, performance will be optimal when encoding is HOST_ENCODING and should be used whenever inter-machine transfer is unimportant. Unless you have a compelling reason to do otherwise, use ROW_MAJOR for the majority argument to correspond to C's own array ordering scheme. If CDF creation is successful, the CDFid is initialized for use in all subsequent operations on the CDF. After CDFcreate(), the CDF is open for update access, that is, for writing or reading, or both. CDFstatus CDFopen( char *CDFname, /* in -- CDF path name (external name) */ CDFid *id); /* out-- CDF id */ Function description: Open the named CDF, initializing the id when successful. The CDFid is used in all subsequent operations on the CDF. After a CDF has been opened, you may read from it or write to it, or both, depending upon the read-write privileges that you have to the CDF's files, according to your system's rules. CDFstatus CDFdoc( CDFid id, /* in -- CDF id */ long *version, /* out-- software version number */ long *release, /* out-- software release number */ char text[CDF_DOCUMENT_LEN+1]); /* out-- copyright information */ Function description: CDFdoc is used to gather documentary information that is stored within a CDF header. The version and release arguments tell you what version of the CDF library created a particular CDF. The text array, which gives copyright and other information, is a null-terminated string with several newline characters embedded so that it may be printed easily. For example, if (CDFdoc( id, &ver, &rel, text) == CDF_OK) printf ("%s\n", text); CDFstatus CDFinquire( CDFid id, /* in -- CDF id */ long *numDims, /* out-- number of dims, 0..CDF_MAX_DIMS */ long dimSizes[], /* out-- size of each dimension */ long *encoding, /* out-- { HOST_ENCODING, NETWORK_ENCODING } */ long *majority, /* out-- { ROW_MAJOR or COL_MAJOR } */ long *maxRec, /* out -- maximum record number used */ long *numVars, /* out-- current number of variables */ long *numAttrs); /* out-- current number of attributes */ Function description: Find out the basic characteristics of a CDF. The first four outputs of the function tell you the fixed characteristics of the CDF that were determined at CDFcreate(). You will need to know numDims and the corresponding dimSizes[] vector for most operations on CDF variables. Some applications will need to know the encoding and the majority structure of the CDF as well. (For instance, you may want the majority variable in order to optimize throughput in an application.) The last three outputs of the function can increase (but never decrease) through the life of a CDF as new records, variables, or attributes are written. (CDF version 2 does not support the ability to delete records, variables, or attributes once they have been written or created.) CDFstatus CDFclose( CDFid id); /* in -- CDF id */ Function description: Close the identified CDF. The CDF's data buffers are flushed, all of the CDF's open files are closed, and the CDFid is released. *IMPORTANT NOTE*: You must close a CDF with CDFclose() to guarantee that all writes that you have issued will actually be written to the CDF's files. If your program exits, normally or otherwise, without normal completion of CDFclose, the CDF's data buffers are left un-flushed. If you have only read from a CDF, and not written to it, failure to close it is of no consequence. Of course, it is always good practice to close your CDFs before ending your application. CDFstatus CDFdelete( CDFid id); /* in -- CDF id */ Function description: Deletes the identified CDF (or, more precisely, the CDF's set of files). A CDF file set includes a CDF header file, "CDFname.cdf", and all its variable files, "CDFname.v0" through "CDFname.vNN", where NN+1 is the number of CDF variables. You must open a CDF before you are allowed to deleted it. And, of course, if you have no privilege to delete the CDF files, according to your system's rules, they will not be deleted. In the CDF is corrupted and cannot be opened, the CDF (all associated files) must be deleted at the command line. CDFstatus CDFerror( CDFstatus stat, /* in -- a CDFstatus value returned from any CDF function of type CDFstatus */ char message[CDF_ERRTEXT_LEN+1]); /* out-- CDF message text corresponding to the value of stat. */ Function description: Look up the meaning of a CDFstatus code. This function uses the CDFstatus value input to look up the corresponding message text in a catalog of CDF messages. The text is a null- terminated string, no greater than CDF_ERRTEXT_LEN in length, and is output to the address of the message argument. See CDFstatus Codes and Messages for exact wording of messages, and for elaboration of meanings. When the input status value is not in the catalog, you'll receive the BAD_CDFSTATUS code and message. Message values: When, stat > CDF_OK : information message (function completed successfully). stat = CDF_OK : function completed successfully. stat < CDF_OK : warning or error message. *-- Attribute Access Functions These eight functions provide for operations on CDF attributes: CDFstatus CDFattrCreate(); long CDFattrNum(); CDFstatus CDFattrRename(); CDFstatus CDFattrInquire(); CDFstatus CDFattrEntryInquire(); CDFstatus CDFattrPut(); CDFstatus CDFattrGet(); CDFstatus CDFattrCorrectScope(); CDFstatus CDFattrCreate( CDFid id, /* in -- CDF id */ char *attrName, /* in -- attribute name */ long attrScope, /* in -- scope of attribute */ long *attrNum); /* out -- attribute number */ Function description: Create an attribute as specified by the arguments. The attrName must be a null-terminated string, no longer than CDF_ATTR_NAME_LEN, naming the attribute. Letter-case is respected. attrScope must be GLOBAL_SCOPE or VARIABLE_SCOPE. (The indefinite scopes are also allowed in Version 2.0; see notes to CDFattrCorrectScope.) If attribute creation is successful, the attrNum is set for use in all subsequent accesses to this attribute. Attributes are given index numbers starting from zero in the order in which they are created. long CDFattrNum( CDFid id, /* in -- CDF id */ char *attrName); /* in -- attribute name */ Function description: Look up the attribute named and return its index number for subsequent access to that attribute. The attrName must be a null-terminated string. CDFstatus CDFattrRename( CDFid id, /* in -- CDF id */ long attrNum, /* in -- attribute to rename 0..nAttributes-1*/ char *attrName); /* in -- new name for attribute */ Function description: Rename an existing attribute. The attribute indexed by attrNum will be changed to the name given by attrName, which must be a null-terminated string. CDFstatus CDFattrInquire( CDFid id, /* in -- CDF id */ long attrNum, /* in -- attribute number, 0..nAttributes-1 */ char *attrName, /* out -- attribute name, NULL-terminated */ long *attrScope, /* out -- scope of attribute */ long *maxEntry); /* out -- maximum entry number that exists for this attribute */ Function description: Find out about the attribute identified by attrNum -- first level of inquiry. This function tells name of the attribute, its scope, and the maximum entry (attribute value) currently on hand. The name is returned as a null- terminated string. For a Version 2.0 CDF, the scope will be either GLOBAL_SCOPE, VARIABLE_SCOPE, GLOBAL_SCOPE_ASSUMED, or VARIABLE_SCOPE_ASSUMED. A Version 1 CDF has no attribute scope. When reading a Version 1 CDF, CDFattrInquire will return GLOBAL_SCOPE_ASSUMED if the maximum entry number is zero; otherwise, VARIABLE_SCOPE_ASSUMED. (See also CDFattrEntryInquire). CDFstatus CDFattrEntryInquire( CDFid id, /* in -- CDF id */ long attrNum, /* in -- attribute number, 0..nAttributes-1 */ long entryNum, /* in -- entry number if GLOBAL scope attribute, entryNum >= 0. -- variable number if VARIABLE scope attribute, 0..nVariables-1 */ long *dataType, /* out -- data type of this attribute entry */ long *numElements); /* out -- number of elements of the data type */ Function description: Find out about an entry of the attribute identified by attrNum -- second level of attribute inquiry. This functions tells how to interpret attribute entries correctly by giving you the CDF datatype and number of elements for the attribute's entry. Unlike version 1 of CDF, the datatype and number of elements for entries can vary from one entry to the next for a given attribute. How you use that information also depends upon the scope of an attribute, which can be gotten only from CDFattrInquire. The entryNum input argument can have two different meanings in CDFattrEntryInquire(). If an attribute is GLOBAL_SCOPE, then the entryNum argument means simply the entryNum-th one in a set of global-scope entries. The numbering of those entries can be arbitrary. Here entryNum equal 7 would mean, simply, "tell me about entry 7 for this attribute." However, if an attribute is VARIABLE_SCOPE, the entryNum argument refers to the attribute entry corresponding to a particular variable. When entryNum equals 7, it means "tell me about the attribute entry for variable 7". In either case, the datatype and number-of-elements are output by the function when conditions are normal. (See also CDFattrInquire and CDFattrPut). CDFstatus CDFattrPut( CDFid id, /* in -- CDF id */ long attrNum, /* in -- attribute number, 0..nAttributes-1 */ long entryNum, /* in -- entry number if GLOBAL attribute, entryNum >= 0. -- variable number if VARIABLE attribute, 0..nVariables-1 */ long dataType, /* in -- data type of this attribute entry */ long numElements, /* in -- number of elements of the data type */ void *value); /* in -- attribute entry value */ Function description: Write an entry for the attribute specified by attrNum. If the attribute is GLOBAL_SCOPE, the entryNum has no special meaning. It refers to an arbitrary global entry. If the attribute is VARIABLE_SCOPE, the entryNum corresponds to a particular variable number. Thus, if scope is variable and entryNum == 7, you are writing an attribute entry for variable 7. The dataType argument can be any of the CDF datatypes, and the numElements is the number of those types you wish to write to the entry. The value argument is the address of your buffer where the value (or values) for the entry begin. CDFattrPut() will take numElements items of the given datatype from that buffer and write them to the CDF. For instance, if you wish to put a single 4-byte integer, use dataType=CDF_INT4 and numElements=1. If you wish to put a 60-character string, use dataType=CDF_CHAR and numElements=60. (See also CDFattrEntryInquire) CDFstatus CDFattrGet( CDFid id, /* in -- CDF id */ long attrNum, /* in -- attribute number, 0..nAttributes-1 */ long entryNum, /* in -- entry number if GLOBAL attribute, entryNum >= 0. -- variable number if VARIABLE attribute, 0..nVariables-1 */ void *value); /* out -- attribute entry value */ Function description: Read an entry for the attribute specified by attrNum. If the attribute is GLOBAL_SCOPE, the entryNum has no special meaning. It refers to an arbitrary global entry. If the attribute is VARIABLE_SCOPE the entryNum corresponds to a particular variable number. Thus, if scope is variable and entryNum == 7, you are reading an attribute entry for variable 7. The dataType argument output can be any of the CDF datatypes, and the numElements is the number of those types that were written to the entry. The value argument is the address of your buffer where the value (or values) for the entry will be placed. Therefore, before calling CDFattrGet() you must know an entry's dataType and numElements, by calling CDFattrEntryInquire(). CDFattrGet() will put numElements items of the given datatype into your value buffer, reading them from the CDF. For instance, if the entry is a single 4-byte integer, one CDF_INT4 will be output to the buffer. If the entry is a 60-character string, 60 CDF_CHARs will be output. (See also CDFattrEntryInquire) CDFstatus CDFattrCorrectScope( CDFid id, /* in -- CDF id */ long attrNum, /* in -- attribute number, 0..nAttributes-1 */ long attrScope) /* in -- new scope of attribute (one of 4) */ Function description: *IMPORTANT NOTE* This function is not a permanent one; it will be deleted from version 3 of the CDF library. You should need this function only after you have used the CDF Toolkit utility program, CDFconvert, to convert version 1 CDFs to version 2 CDF format. And perhaps not even then. The version 1 CDF library did not provide a mechanism for declaring the scope of an attribute. That gave rise to ambiguities that cannot be resolved by a program without knowledge of a dataset's meaning. Therefore, CDF version 2 applies a heuristic to the conversion process. When it cannot determine the intended scope for an attribute, it makes a best-guess and marks the attribute as either GLOBAL_SCOPE_ASSUMED or VARIABLE_SCOPE_ASSUMED. So, use this function only when you must, to change an indefinite scope to a definite scope. The scope of the identified attribute will be changed as specified by attrScope, which must be one of the two definite scopes, GLOBAL_SCOPE or VARIABLE_SCOPE. See documentation on CDFconvert for further details. *-- Variable Access Functions These nine functions provide for operations on CDF variables: CDFstatus CDFvarCreate(); long CDFvarNum(); CDFstatus CDFvarRename(); CDFstatus CDFvarInquire(); CDFstatus CDFvarPut(); CDFstatus CDFvarGet(); CDFstatus CDFvarHyperGet(); CDFstatus CDFvarHyperPut(); CDFstatus CDFvarCreate( CDFid id, /* in -- CDF id */ char *VarName, /* in -- variable name */ long dataType, /* in -- CDF datatype */ long numElements, /* in -- number of elements of the specified data type. For the CDF_CHAR and CDF_UCHAR data types this is the size of the string. For all other data types this must be set to 1 */ long recVariance, /* in -- record variance { VARY, NOVARY} */ long dimVariances[], /* in -- dimension vector [{VARY, NOVARY},,,] */ long *varNum); /* out -- attribute number */ Function description: Create the variable as specified by the arguments. long CDFvarNum( CDFid id, /* in -- CDF id */ char *varName); /* in -- variable name */ Function description: Look up the variable named and return its index number for subsequent access to that variable. The varName must be a null-terminated string. CDFstatus CDFvarRename( CDFid id, /* in -- CDF id */ long varNum, /* in -- variable to rename 0..nVariables-1 */ char *varName); /* in -- new name for variable */ Function description: Rename an existing variable. The variable indexed by varNum will be changed to the name given by varName, which must be a null-terminated string. CDFstatus CDFvarInquire( CDFid id, /* in -- CDF id */ long varNum, /* in -- variable number, 0..nVariables-1 */ char *VarName, /* out -- name of variable, null-terminated */ long *dataType, /* out -- CDF datatype */ long *numElements, /* out -- number of elements of the data type */ long *recVariance, /* out -- record variance {VARY,NOVARY} (T/F) */ long dimVariances[]);/* out -- dimension vector [{VARY, NOVARY},,,]*/ Function description: Find out the characteristics of the identified variable. CDFstatus CDFvarPut( CDFid id, /* in -- CDF id */ long varNum, /* in -- variable number, 0..nVariables-1 */ long recNum, /* in -- record number, >= 0 */ long indices[], /* in -- indices of item, CDF dimensionality */ void *value); /* in -- buffer containing variable datum */ Function description: Write a single instance of a variable to the CDF. CDFstatus CDFvarGet( CDFid id, /* in -- CDF id */ long varNum, /* in -- variable number, 0..nVariables-1 */ long recNum, /* in -- record number, 0..nRecords-1 */ long indices[], /* in -- indices of item, CDF dimensionality */ void *value); /* out-- buffer to place variable datum */ Function description: Read a single instance of a variable from the CDF. CDFstatus CDFvarHyperPut( CDFid id, /* in -- CDF id */ long varNum, /* in -- variable number, 0..nVariables-1 */ long recStart, /* in -- starting record, 0..nRecords-1*/ long recCount, /* in -- number of records */ long recInterval, /* in -- record subsampling interval */ long indices[], /* in -- starting indices, CDF dimensionality */ long counts[], /* in -- items to get in each dimension */ long intervals[], /* in -- dimension subsampling intervals */ void *buffer); /* in -- buffer to read from */ Function description: Transfer a hyperplane of variable values from the buffer to the CDF. CDFvarHyperPut() will take data from the buffer in the order that matches the structure of the CDF, either ROW_MAJOR or COL_MAJOR. The majority order of the CDF was determined when the CDF was created and cannot be changed. Use the CDFinquire() function within a program or run the CDFbrowse utility to learn the majority of a CDF. CDFstatus CDFvarHyperGet( CDFid id, /* in -- CDF id */ long varNum, /* in -- variable number, 0..nVariables-1 */ long recStart, /* in -- starting record, 0..nRecords-1 */ long recCount, /* in -- number of records */ long recInterval, /* in -- record subsample interval */ long indices[], /* in -- starting indices, CDF dimensionality */ long counts[], /* in -- items to get in each dimension */ long intervals[], /* in -- dimension subsampling intervals */ void *buffer); /* out-- buffer to write to */ Function description: Transfer a hyperplane of variable values from the CDF to the buffer. CDFvarHyperGet() will order its output to the buffer as the CDF is ordered, either ROW_MAJOR or COL_MAJOR. The majority order of the CDF was determined when the CDF was created and cannot be changed. The *buffer array must be pre- allocated by the user. Use the CDFinquire() function within a program or run the CDFbrowse utility to learn the majority of a CDF. *- Interface Summary: ANSI Function Prototypes Below is a summary of the CDF interface written as a functions prototype in the ANSI style. It will be useful for quick recollection of the required protocols as you increase your experience with the CDF. All information in the summary is given in greater detail in the Function Reference above. CDFstatus CDFcreate( char *CDFname, /* in */ long numDims, /* in */ long dimSizes[], /* in */ long encoding, /* in */ long majority, /* in */ CDFid *id); /* out*/ CDFstatus CDFopen( char *CDFname, /* in */ CDFid *id); /* out*/ CDFstatus CDFdoc( CDFid id, /* in */ long *version, /* out*/ long *release, /* out*/ char text[CDF_DOCUMENT_LEN+1]);/* out*/ CDFstatus CDFinquire( CDFid id, /* in */ long *numDims, /* out*/ long dimSizes[], /* out*/ long *encoding, /* out*/ long *majority); /* out*/ long *maxRec, /* out*/ long *numVars, /* out*/ long *numAttrs); /* out*/ CDFstatus CDFclose( CDFid id); /* in */ CDFstatus CDFdelete( CDFid id); /* in */ CDFstatus CDFerror( CDFstatus stat, /* in */ char message[CDF_ERRTEXT_LEN+1]); /* out*/ CDFstatus CDFattrCreate( CDFid id, /* in */ char *attrName, /* in */ long attrScope, /* in */ long *attrNum); /* out*/ long CDFattrNum( CDFid id, /* in */ char *attrName); /* in */ CDFstatus CDFattrRename( CDFid id, /* in */ long attrNum, /* in */ char *attrName); /* in */ CDFstatus CDFattrInquire( CDFid id, /* in */ long attrNum, /* in */ char *attrName, /* out*/ long *attrScope, /* out*/ long *maxEntry); /* out*/ CDFstatus CDFattrEntryInquire( CDFid id, /* in */ long attrNum, /* in */ long entryNum, /* in */ long *dataType, /* out*/ long *numElements); /* out*/ CDFstatus CDFattrPut( CDFid id, /* in */ long attrNum, /* in */ long entryNum, /* in */ long dataType, /* in */ long numElements, /* in */ void *value); /* in */ CDFstatus CDFattrGet( CDFid id, /* in */ long attrNum, /* in */ long entryNum, /* in */ void *value); /* out*/ CDFstatus CDFattrCorrectScope( CDFid id, /* in */ long attrNum, /* in */ long attrScope) /* in */ CDFstatus CDFvarCreate( CDFid id, /* in */ char *VarName, /* in */ long dataType, /* in */ long numElements, /* in */ long recVariance, /* in */ long dimVariances[], /* in */ long *varNum); /* out*/ long CDFvarNum( CDFid id, /* in */ char *varName); /* in */ CDFstatus CDFvarRename( CDFid id, /* in */ long varNum, /* in */ char *varName); /* in */ CDFstatus CDFvarInquire( CDFid id, /* in */ long varNum, /* in */ char *VarName, /* out*/ long *dataType, /* out*/ long *numElements, /* out*/ long *recVariance, /* out*/ long dimVariances[]);/* out*/ CDFstatus CDFvarPut( CDFid id, /* in */ long varNum, /* in */ long recNum, /* in */ long indices[], /* in */ void *value); /* in */ CDFstatus CDFvarGet( CDFid id, /* in */ long varNum, /* in */ long recNum, /* in */ long indices[], /* in */ void *value); /* out*/ CDFstatus CDFvarHyperPut( CDFid id, /* in */ long varNum, /* in */ long recStart, /* in */ long recCount, /* in */ long recInterval, /* in */ long indices[], /* in */ long counts[], /* in */ long intervals[], /* in */ void *buffer); /* in */ CDFstatus CDFvarHyperGet( CDFid id, /* in */ long varNum, /* in */ long recStart, /* in */ long recCount, /* in */ long recInterval, /* in */ long indices[], /* in */ long counts[], /* in */ long intervals[], /* in */ void *buffer); /* out*/ *- Rules for Testing A CDFstatus Value All CDF functions but two return a CDFstatus type, which in CDF version 2.0 is defined as an integer value. The symbolic names are all defined in cdf.h and should be used in programs instead of the true numeric values. For testing the return values from CDF functions, the following rules apply to CDFstatus values and are guaranteed for all future versions of the CDF: 1) CDF_OK indicates a normal condition 2) CDFstatus > CDF_OK indicates a normal condition but provides some additional information 3) CDFstatus < CDF_OK indicates a non-normal condition When a condition is non-normal, the next two rules may be applied by your programs to determine the severity of a condition. These rules will be in effect for all future versions of the CDF. However, the actual numeric thresholds may change; therefore, use only the symbolic names in conditional tests. 4) CDF_OK > CDFstatus > CDF_WARN indicates warning condition 5) CDF_WARN > CDFstatus indicates error condition. Therefore, in all your CDF applications we recommend that you use statements like these to screen for non-normal conditions of CDF functions: CDFstatus stat; ... stat = CDFfunction(); /* any CDF function except CDFerror() */ if (stat != CDF_OK) yourOwnErrorHandler( stat, ...); In your own error handler you can take whatever action is appropriate to the application based on a set of if-else statements, such as this: #include #include "cdf.h" void yourOwnErrorHandler( CDFstatus status) { char message[CDF_ERRTEXT_LEN]; if ( status < CDF_WARN) { fprintf( stderr, "\nSomething's just not right. Let's halt."); CDFerror( status, message)); fprintf( stderr, "\n%s", message); exit( (int) status); } else if ( status < CDF_OK) { fprintf( stderr, "\nThis looks funny, and might be bad news:"); CDFerror( status, message)); fprintf( stderr, "\n%s", message); } else if ( status > CDF_OK) { fprintf( stderr, "\nNo big deal. Please be advised:"); CDFerror( status, message)); fprintf( stderr, "\n%s", message); } else ; /* the status value indicates a normal condition */ return; } All messages in Appendix A, whether information, warning, or error, are available to your program through the function CDFerror(). CDFerror() simply does a lookup of the CDFstatus value in an array of text. It will return the first line of text shown below for each CDFstatus value. The message will have a null-terminator and any tabs or redundant blanks removed. Thus, if you reference CDFerror( status=ATTR_EXISTS, message), you will receive this message string: "ATTR_EXISTS : Named attribute already exists; cannot create it." Appendix A CDF Version 2.0 status codes CDF_INFO -- Information Codes and Messages Informational codes are normal but provide some additional information. CDFstatus : "Message"... Explanation ___________________________________________________________ VIRTUAL_RECORD_DATA : One or more of the records are virtual (never PUT to the CDF). READ_ONLY_ACCESS : Read-only access is allowed on the CDF (no writing or deleting). VERSION_1_CDF : This is a Version 1 CDF, some restrictions may apply. CDF_OK : Function completed. CDF_WARN -- Warning Codes and Messages Warning codes are considered non-normal and indicate a potential problem that may lead to errors in program operation or errors of data interpretation. CDFstatus : "Message"... Explanation ___________________________________________________________ ATTR_NAME_TRUNC : Attribute name truncated to CDF_ATTR_NAME_LEN characters. CDF_NAME_TRUNC : CDF path name truncated to CDF_PATHNAME_LEN characters. VAR_NAME_TRUNC : Variable name truncated to CDF_VAR_NAME_LEN characters. CDF_INCOMPATIBLE : Certain operations on Version 2 CDFs are incompatible with the OBSOLETE interface. VAR_ALREADY_CLOSED : The specified variable is already closed. CDF_ERROR -- Error Codes and Messages These codes are severe errors. The application should take corrective action or halt. CDFstatus : Message ... Explanation ___________________________________________________________ ATTR_EXISTS : Named attribute already exists, cannot create it. BAD_CDF_ID : CDF identifier is unknown or invalid, or CDF was not opened. BAD_DATATYPE : Unknown datatype specified. BAD_DIM_SIZE : One or more CDF dimension sizes specified as 0 or less. BAD_DIM_INDEX : One or more dimension index is out-of-range. BAD_ENCODING : Unknown or unsupported data representation. BAD_MAJORITY : Majority argument must be ROW_MAJOR or COL_MAJOR. BAD_NUM_DIMS : CDF supports 0 to CDF_MAX_DIMS dimensions. BAD_REC_NUM : Record number is negative or out-of-range. BAD_SCOPE : Unrecognized scope for attribute creation. BAD_VAR_NUM_ELEM : Number of elements of the data type is illegal. CANNOT_ACCESS_CDF : Cannot open, create, read, or write CDF as specified. Most common causes: 1) CDF name is incorrectly specified. 2) You have insufficient privileges to access the CDF file set or its directory for the operation specified; you need read-privileges for CDF_open, and write-privileges for CDF_create. You need write privileges to alter variables or attributes. 3) Required member of the CDF file-set has been deleted, renamed, or protected. Check to see that the header and vector files exist. CDF_EXISTS : The CDF named already exists; cannot create it. CDF_create will not operate on a CDF that already exists. To re-create a CDF, use CDFopen followed by CDFdelete to first remove the CDF. Then, call CDFcreate. BAD_ITEMTYPE : Unknown item type specified. NO_ATTR_READ : Failed to read attribute as requested. NO_ATTR_WRITTEN : Failed to write attribute as requested. NO_SUCH_ATTR : Attribute not found in this CDF. NO_SUCH_ENTRY : No such entry for specified attribute. NO_SUCH_VAR : Variable not found in this CDF. NO_VAR_READ : Failed to read variable as requested. NO_VAR_WRITTEN : Failed to write variable as requested. TOO_MANY_CDFS : CDF_MAX_CDFS are already open. TOO_MANY_FILES : Too many files are already open; system limit reached. TOO_MANY_VARS : Attempt to create more than CDF_MAX_VARS variables. VAR_EXISTS : Named variable already exists; cannot create it. BAD_MALLOC : Unable to allocate dynamic memory; system limit reached. NOT_A_CDF : Named CDF is not a CDF or is corrupted. BAD_CDFHDR : Named CDF is not a CDF or is corrupted. CANNOT_ACCESS_VAR : Cannot access variable as requested. BAD_CDFGHDR : Named CDF is not a CDF or is corrupted. BAD_CDFADR : Named CDF is not a CDF or is corrupted. BAD_CDFADVR : Named CDF is not a CDF or is corrupted. BAD_CDFVDR : Named CDF is not a CDF or is corrupted. BAD_CDFSTATUS : Unknown CDFstatus value received. NO_WRITE_ACCESS : Writing is not allowed (read-only access). NO_DELETE_ACCESS : Deleting is not allowed (read-only access). BAD_REC_COUNT : Illegal record count specified, extends beyond last CDF record. BAD_REC_INTERVAL : Illegal record interval specified. BAD_DIM_COUNT : Illegal dimension count specified, extends beyond extent of dimension. BAD_DIM_INTERVAL : Illegal dimension interval specified. BAD_VAR_NUM : Illegal variable number specified. BAD_ATTR_NUM : Illegal attribute number specified. BAD_ENTRY_NUM : Illegal attribute entry number specified. BAD_ATTR_NAME : Illegal attribute name specified. BAD_VAR_NAME : Illegal variable name specified. NO_ATTR_SELECTED : An attribute has not yet been selected. NO_ENTRY_SELECTED : An attribute entry has not yet been selected. NO_VAR_SELECTED : A variable has not yet been selected. BAD_CDF_NAME : Illegal CDF name specified. BAD_ATTR_NUM_ELEM : Illegal number of elements specified for the attribute entry. CANNOT_CHANGE : Because of dependencies on the value, it cannot be changed. NO_STATUS_SELECTED : A CDFstatus has not yet been selected. NO_CDF_SELECTED : A CDF has not yet been selected. NO_RECORDS_EXIST : No records exist in the CDF. CDF_CLOSE_ERROR : Error detected while trying to close CDF header file. VAR_CLOSE_ERROR : Error detected while trying to close a variable (vector) file. BAD_V1_ATTR_ENTRY : This Version 1 CDF is corrupted. ILLEGAL_ON_V1_CDF : The specified operation is not allowed on Version 1 CDFs.