CDF FORTRAN Programmer's Reference FILE: CDFFORTRANREF.doc RELEASE:CDF version 2.0 AUTHOR: J. Love DATE: 11 February 1991 Table of Contents 1.0 General 1.1 Include files 1.2 Object referencing 1.3 Data Types 1.4 Attribute Scopes 1.5 Encodings 1.6 Majorities 1.7 Argument passing 1.8 Status Codes 2.0 Syntax 2.1 CDF_create 2.2 CDF_open 2.3 CDF_doc 2.4 CDF_inquire 2.5 CDF_close 2.6 CDF_delete 2.7 CDF_error 2.8 CDF_attr_create 2.9 CDF_attr_num 2.10 CDF_attr_rename 2.11 CDF_attr_inquire 2.12 CDF_attr_entry_inquire 2.13 CDF_attr_put 2.14 CDF_attr_get 2.15 CDF_attr_correct_scope 2.16 CDF_var_create 2.17 CDF_var_num 2.18 CDF_var_rename 2.19 CDF_var_inquire 2.20 CDF_var_put 2.21 CDF_var_get 2.22 CDF_var_hyper_put 2.23 CDF_var_hyper_get Appendix A CDF Version 2.0 status codes 1.0 General 1.1 Include files. The CDF.INC include file defines all the parameter constants which will be needed to access Version 2.0 CDFs. 1.2 Object referencing. All CDF objects are referenced beginning at one (1). These include attributes, attribute entries, variables, records, and dimension indices. 1.3 Data Types. The following data types are supported in CDF Version 2.0 (all data types assume an 8-bit byte). CDF_BYTE 1-byte signed integer. CDF_INT1 1-byte signed integer. CDF_INT2 2-byte signed integer. CDF_INT4 4-byte signed integer CDF_UINT1 1-byte unsigned integer. CDF_UINT2 2-byte unsigned integer. CDF_UINT4 4-byte unsigned integer. CDF_REAL4 4-byte floating point. CDF_FLOAT 4-byte floating point. CDF_REAL8 8-byte floating point. CDF_DOUBLE 8-byte floating point. CDF_CHAR 1-byte character/integer. CDF_UCHAR 1-byte unsigned character/integer. The CDF_CHAR and CDF_UCHAR data types are intended for use with character string data (in attributes and variables). For byte arrays, use the CDF_BYTE, CDF_INT1, or CDF_UINT1 data types. 1.4 Attribute Scopes. The following attribute scopes are supported in CDF Version 2.0. GLOBAL_SCOPE The attribute applies to the CDF as a whole. VARIABLE_SCOPE The attribute applies to each variable individually (describing some aspect of each variable). GLOBAL_SCOPE_ASSUMED It is assumed that the attribute is GLOBAL in scope. VARIABLE_SCOPE_ASSUMED It is assumed that the attribute is VARIABLE in scope. The scopes GLOBAL_SCOPE_ASSUMED and VARIABLE_SCOPE_ASSUMED are only necessary because of the ambiguity which existed regarding attributes in CDF Version 1. 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. 1.5 Encodings. The following variable data encodings are supported in CDF Version 2.0. HOST_ENCODING The machine's native encoding. NETWORK_ENCODING The XDR encoding so as to be portable between machines using the XDR library. VAX_ENCODING VAX machine encoding. SUN_ENCODING SUN machine encoding. When creating a CDF, if NETWORK_ENCODING is specified, all variable data values are stored in the XDR format. When the CDF is inquired, NETWORK_ENCODING will be returned as the encoding type. When creating a CDF, if HOST_ENCODING is specified, the CDF library determines the host machine type (VAX or SUN) and that encoding is used. When the CDF is inquired, the specific encoding (VAX_ENCODING or SUN_ENCODING) will be returned as the encoding type. 1.6 Majorities. The following record dimension majorities are supported in CDF Version 2.0. ROW_MAJOR Row major which is the convention in the C programming language. Dimension 1 varies the slowest in a CDF record on disk and in the buffers used with the variable HYPER functions. COL_MAJOR Column major which is the convention in the FORTRAN programming language. Dimension 1 varies the fastest in a CDF record on disk and in the buffers used with the variable HYPER functions. When using the variable HYPER functions, the buffer (array) being read from/written to must have the same majority as that which was specified when the CDF was created. 1.7 Argument passing. 1.7.1 On VMS systems. By default (as imposed by the FORTRAN compiler), all numeric values are passed by reference and all character strings are passed by descriptor. These defaults should be used except in one case. When passing character strings as values to and from variables of type CDF_CHAR or CDF_UCHAR, passing by reference must be used. This will require enclosing the value, either an embedded string (e.g., 'ABC') or a symbol (e.g., VAR_VALUE where VAR_VALUE was declared as CHARACTER*5) within the built-in function %REF (e.g., %REF('ABC') or %REF(VAR_VALUE)). Note that this is not necessary for attributes of type CDF_CHAR or CDF_UCHAR when passing values in or out. 1.7.2 On UNIX systems. By default, all numeric values and character strings are passed by reference as is required by the CDF FORTRAN interface so no special action is necessary. 1.8 Status Codes. Every function except CDF_attr_num, CDF_var_num, and CDF_error returns a status code. Status codes may be one of the following types: status code > CDF_OK Indicates success but provides some additional information which may be of interest. status code = CDF_OK Indicates success. CDF_OK > status code > CDF_WARN Indicates a warning condition which may be acceptable. CDF_WARN > status code Indicates an error condition which must be corrected. Appendix A lists the possible status codes with an explanation of each. 2.0 Syntax 2.1 CDF_create. Used to create a new CDF. The CDF remains open for all types of access. On both VMS and UNIX systems, it is illegal to create a CDF if it already exists. If a new version of the CDF is desired, the existing version must be opened and deleted first. CALL CDF_create (CDF_name, num_dims, dim_sizes, encoding, majority, CDF_id, status) CDF_name: CHARACTER*(*), input. The pathname (complete file specification except for the file type, e.g., .CDF) of the CDF to be created. This may have at most CDF_PATHNAME_LEN characters. num_dims: INTEGER*4, input. The number of dimensions the CDF is to have. This may have a maximum of CDF_MAX_DIMS. dim_sizes: INTEGER*4 (*), input. An array of dimension sizes. The number of sizes should be consistent with the number of dimensions. Each dimension size must be at least one. encoding: INTEGER*4, input. The encoding to be used for attribute and variable values. This may be either HOST_ENCODING or NETWORK_ENCODING. This is specified only when the CDF is created and cannot be changed. majority: INTEGER*4, input. The ordering of variable values in the CDF. This may be either ROW_MAJOR or COL_MAJOR. This is specified only when the CDF is created and cannot be changed. Use this only when specifically needed; should be left as default (column major) otherwise. CDF_id: INTEGER*4, output. The identifier to be used when referring to this CDF in subsequent calls. A different identifier value will be assigned to each CDF which is open (via CDF_create or CDF_open). status: INTEGER*4, output. The status code returned for this CDF function. CDF_OK indicates success. Appendix A lists and explains the possible status codes. 2.2 CDF_open. Used to open a CDF for all types of access, depending on the user's privileges. If the CDF does not exist, an error is returned. Use CDF_create to create a CDF. CALL CDF_open (CDF_name, CDF_id, status) CDF_name: CHARACTER*(*), input. The pathname (complete file specification except for the file type, e.g., .CDF) of the CDF to be created. This may have at most CDF_PATHNAME_LEN characters. CDF_id: INTEGER*4, output. The identifier to be used when referring to this CDF in subsequent calls. A different identifier value will be assigned to each CDF which is open (via CDF_create or CDF_open). status: INTEGER*4, output. The status code returned for this CDF function. CDF_OK indicates success. Appendix A lists and explains the possible status codes. 2.3 CDF_doc. Used to get documentation type information about a CDF and the CDF library used to create it. CALL CDF_doc (CDF_id, version, release, text, status) CDF_id: INTEGER*4, input. The identifier of the CDF to be accessed. version: INTEGER*4, output. The version number of the CDF library which created the CDF. release: INTEGER*4, output. The release number of the CDF library which created the CDF. text: CHARACTER*(CDF_DOCUMENT_LEN), output. Several lines of text describing the CDF software. A linefeed character separates each line and follows the last line of the text. status: INTEGER*4, output. The status code returned for this CDF function. CDF_OK indicates success. Appendix A lists and explains the possible status codes. 2.4 CDF_inquire. Used to inquire a CDF's structure and size. This would be used to determine how to access an unknown CDF's attribute and variable data. CALL CDF_inquire (CDF_id, num_dims, dim_sizes, encoding, majority, max_rec, num_vars, num_attrs, status) CDF_id: INTEGER*4, input. The identifier of the CDF to be inquired. num_dims: INTEGER*4, output. The number of dimensions the CDF has. dim_sizes: INTEGER*4 (*), output. The size of each dimension. The size of the array to receive these values must be consistent with the number of dimensions. encoding: INTEGER*4, output. The encoding used for attribute and variable values. This will be VAX_ENCODING, SUN_ENCODING, or NETWORK_ENCODING. majority: INTEGER*4, output. The ordering of variable values in the CDF records. This will be ROW_MAJOR or COLUMN_MAJOR. max_rec: INTEGER*4, output. Maximum record number in the CDF. num_vars: INTEGER*4, output. The number of variables in the CDF. num_attrs: INTEGER*4, output. The number of attributes in the CDF. status: INTEGER*4, output. The status code returned for this CDF function. CDF_OK indicates success. Appendix A lists and explains the possible status codes. 2.5 CDF_close. Used to close a CDF from all further access. Once closed, no functions may be performed on a CDF. Note that if a CDF is modified, it must be closed to ensure the new values are actually written to disk. Closing a CDF flushes the buffers associated with each file and properly closes each file. If an application terminates before closing a CDF, that CDF may be corrupted. CALL CDF_close (CDF_id, status) CDF_id: INTEGER*4, input. The identifier of the CDF to be closed. status: INTEGER*4, output. The status code returned for this CDF function. CDF_OK indicates success. Appendix A lists and explains the possible status codes. 2.6 CDF_delete. Used to delete a CDF from the system. The CDF must be open to delete it (via CDF_open or CDF_create if the CDF was used for temporary storage). Note that once a CDF is deleted it is also considered closed. If the CDF is corrupted and cannot be opened, the CDF (all associated files) must be deleted at the command line. CALL CDF_delete (CDF_id, status) CDF_id: INTEGER*4, input. The identifier of the CDF to be deleted. status: INTEGER*4, output. The status code returned for this CDF function. CDF_OK indicates success. Appendix A lists and explains the possible status codes. 2.7 CDF_error. Used to determine the text description for a status code which could then be displayed. CALL CDF_error (status, text) status: INTEGER*4, input. The status code for which a text description is requested. text: CHARACTER*(CDF_ERRTEXT_LEN), output. The text description of the error that occurred. 2.8 CDF_attr_create. Used to create a new attribute. Each attribute name in a CDF must be unique. CALL CDF_attr_create (CDF_id, attr_name, attr_scope, attr_num, status) CDF_id: INTEGER*4, input. The identifier of the CDF to be affected. attr_name: CHARACTER*(*), input. The name of the new attribute. This name may have at most CDF_ATTR_NAME_LEN characters. attr_scope: INTEGER*4, input. The scope of the attribute. This may be of the type GLOBAL_SCOPE, VARIABLE_SCOPE, GLOBAL_SCOPE_ASSUMED or VARIABLE_SCOPE_ASSUMED. See Section 1.4 for a discussion of the use of the assumed scopes. attr_num: INTEGER*4, output. The number assigned to the attribute. This number will be used in subsequent calls to refer to this attribute. status: INTEGER*4, output. The status code returned for this CDF function. CDF_OK indicates success. Appendix A lists and explains the possible status codes. 2.9 CDF_attr_num. Used to determine an attribute number given an attribute name. This function may be embedded in other function calls which require an attribute number. This function returns an INTEGER*4 attribute number. CDF_attr_num (CDF_id, attr_name) CDF_id: INTEGER*4, input. The identifier of the CDF to be accessed. attr_name: CHARACTER*(*), input. The attribute name whose number is to be returned. 2.10 CDF_attr_rename. Used to rename an attribute. The new name cannot be that of an already existing attribute. CALL CDF_attr_rename (CDF_id, attr_num, attr_name, status) CDF_id: INTEGER*4, input. The identifier of the CDF to be affected. attr_num: INTEGER*4, input. The number of the attribute to be renamed. attr_name: CHARACTER*(*), input. The new name of the attribute. This name may have at most CDF_ATTR_NAME_LEN characters. status: INTEGER*4, output. The status code returned for this CDF function. CDF_OK indicates success. Appendix A lists and explains the possible status codes. 2.11 CDF_attr_inquire. Used to inquire about a particular attribute. Note that the number of entries for an attribute may be less than the largest entry number actually used because attribute entries may be put randomly and not all entries must receive a value. CALL CDF_attr_inquire (CDF_id, attr_num, attr_name, attr_scope, max_entry, status) CDF_id: INTEGER*4, input. The identifier of the CDF to be accessed. attr_num: INTEGER*4, input. The number of the attribute to be inquired. attr_name: CHARACTER*(CDF_ATTR_NAME_LEN), output. The name of the attribute padded on the right with blanks if necessary. attr_scope: INTEGER*4, output. The scope of the attribute. For a Version 2.0 CDF, this 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, CDF_attr_inquire will return GLOBAL_SCOPE_ASSUMED if the number of attribute entries is one; otherwise, VARIABLE_SCOPE_ASSUMED. max_entry: INTEGER*4, output. The maximum entry number which exists for this attribute. status: INTEGER*4, output. The status code returned for this CDF function. CDF_OK indicates success. Appendix A lists and explains the possible status codes. 2.12 CDF_attr_entry_inquire. Used to inquire about a particular attribute entry. This function is usually used immediately preceding CDF_attr_get to determine how large a buffer will be necessary to receive the value(s). CALL CDF_attr_entry_inquire (CDF_id, attr_num, entry_num, data_type,num_elements, status) CDF_id: INTEGER*4, input. The identifier of the CDF to be accessed. attr_num: INTEGER*4, input. The number of the attribute to be inquired. entry_num: INTEGER*4, input. The number of the attribute entry to inquire. If the scope of this attribute is GLOBAL_SCOPE, this simply refers to the global entry. If the scope of this attribute is VARIABLE_SCOPE, this refers to the variable (by number) for which this attribute is to be inquired. data_type: INTEGER*4, output. The data type for this particular entry. num_elements: INTEGER*4, output. The number of elements of the indicated data type for this entry. status: INTEGER*4, output. The status code returned for this CDF function. CDF_OK indicates success. Appendix A lists and explains the possible status codes. 2.13 CDF_attr_put. Used to put a value to an attribute entry. CALL CDF_attr_put (CDF_id, attr_num, entry_num, data_type, num_elements, value, status) CDF_id: INTEGER*4, input. The identifier of the CDF to be affected. attr_num: INTEGER*4, input. The number of the attribute to be put to. entry_num: INTEGER*4, input. The number of the attribute entry to put. If the scope of this attribute is GLOBAL_SCOPE, this simply refers to the global entry. If the scope of this attribute is VARIABLE_SCOPE, this refers to the variable (by number) for which this attribute is to be put. data_type: INTEGER*4, input. The data type for this particular entry. The data type may vary from one entry to another for a particular attribute. num_elements: INTEGER*4, input. The number of elements of the indicated data type for this entry. This must be at least one (1). The number of elements may vary from one entry to another for a particular attribute. value: (Depends on data type), input. The value(s) to be put for this attribute entry. status: INTEGER*4, output. The status code returned for this CDF function. CDF_OK indicates success. Appendix A lists and explains the possible status codes. 2.14 CDF_attr_get. Used to get a value from an attribute entry. The function CDF_attr_entry_inquire would usually be used first to ensure that the buffer to receive the value(s) is large enough. CALL CDF_attr_get (CDF_id, attr_num, entry_num, value, status) CDF_id: INTEGER*4, input. The identifier of the CDF to be accessed. attr_num: INTEGER*4, input. The attribute number to be referenced. entry_num: INTEGER*4, input. The number of the attribute entry to put. If the scope of this attribute is GLOBAL_SCOPE, this simply refers to the global entry. If the scope of this attribute is VARIABLE_SCOPE, this refers to the variable (by number) for which this attribute represents. value: (Depends on data type), output. The value(s) to be gotten for this attribute entry. This buffer must be large enough to hold the number of elements of the given data type. status: INTEGER*4, output. The status code returned for this CDF function. CDF_OK indicates success. Appendix A lists and explains the possible status codes. 2.15 CDF_attr_correct_scope. Used to correct the scope of an attribute. This function would be used to change an attribute's scope from one of the assumed types to one of the definite types when the scope has been correctly determined. CALL CDF_attr_correct_scope (CDF_id, attr_num, attr_scope, status) CDF_id: INTEGER*4, input. The identifier of the CDF to be affected. attr_num: INTEGER*4, input. The number of the attribute to be changed. attr_scope: INTEGER*4, input. The corrected scope of the attribute. This may be either GLOBAL_SCOPE or VARIABLE_SCOPE. status: INTEGER*4, output. The status code returned for this CDF function. CDF_OK indicates success. Appendix A lists and explains the possible status codes. This function would be necessary after converting a Version 1 CDF to a Version 2.0 CDF (as the CDFconvert utility does). The attribute scopes in the new Version 2.0 CDF would likely be the assumed scopes and should be corrected (hopefully the correct scope is obvious). It is recommended that any assumed scope be corrected as this function will NOT be supported in Version 3 of the CDF library. 2.16 CDF_var_create. Used to create a new variable. Each variable name in a CDF must be unique. CALL CDF_var_create (CDF_id, var_name, data_type, num_elements, rec_variance, dim_variances, var_num, status) CDF_id: INTEGER*4, input. The identifier of the CDF to be affected. var_name: CHARACTER*(*), input. The name of the new variable. This name may have at most CDF_VAR_NAME_LEN characters. data_type: INTEGER*4, input. The data type for this variable. num_elements: INTEGER*4, input. The 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 1. rec_variance: INTEGER*4, input. The record variance for this variable. This may be either VARY or NOVARY. This is specified only when the variable is created and cannot be changed. dim_variances: INTEGER*4 (*), input. An array of dimension variances. The number of variances should be consistent with the number of dimensions in the CDF. Each dimension variance may be either VARY or NOVARY. These are specified only when the variable is created and cannot be changed. var_num: INTEGER*4, output. The number assigned to this variable. This number will be used in subsequent calls to refer to this variable. status: INTEGER*4, output. The status code returned for this CDF function. CDF_OK indicates success. Appendix A lists and explains the possible status codes. 2.17 CDF_var_num. Used to determine a variable's number given its name. This function may be embedded in other function calls which require a variable number. This function returns an INTEGER*4 variable number. CDF_var_num (CDF_id, var_name) CDF_id: INTEGER*4, input. The identifier of the CDF to be accessed. var_name: CHARACTER*(*), input. The variable name whose number is to be returned. 2.18 CDF_var_rename. Used to rename a variable. The new name cannot be that of an already existing variable. CALL CDF_var_rename (CDF_id, var_num, var_name, status) CDF_id: INTEGER*4, input. The identifier of the CDF to be affected. var_num: INTEGER*4, input. The number of the variable to be renamed. var_name: CHARACTER*(*), input. The new name of the variable. This name may have at most CDF_VAR_NAME_LEN characters. status: INTEGER*4, output. The status code returned for this CDF function. CDF_OK indicates success. Appendix A lists and explains the possible status codes. 2.19 CDF_var_inquire. Used to inquire about a particular variable. This function would usually be used prior to CDF_var_get and CDF_var_hyper_get to determine the size of the buffers necessary to receive the value(s). CALL CDF_var_inquire (CDF_id, var_num, var_name, data_type, num_elements, rec_variance, dim_variances, status) CDF_id: INTEGER*4, input. The identifier of the CDF to be accessed. var_num: INTEGER*4, input. The number of the variable to be inquired. var_name: CHARACTER*(CDF_VAR_NAME_LEN), output. The name of the variable padded on the right with blanks if necessary. data_type: INTEGER*4, output. The data type for this variable. num_elements: INTEGER*4, output. The number of elements of the data type. rec_variance: INTEGER*4, output. The record variance for this variable. This will be either VARY or NOVARY. dim_variances: INTEGER*4 (*), output. The dimension variances for this variable. The size of array to receive these variances must be consistent with the number of dimensions in the CDF. These will be either VARY or NOVARY. status: INTEGER*4, output. The status code returned for this CDF function. CDF_OK indicates success. Appendix A lists and explains the possible status codes. 2.20 CDF_var_put. Used to put a value to a variable. This function puts only one value, use CDF_var_hyper_put to put multiple values. CALL CDF_var_put (CDF_id, var_num, rec_num, indices, value, status) CDF_id: INTEGER*4, input. The identifier of the CDF to be affected. var_num: INTEGER*4, input. The number of the variable to be put to. rec_num: INTEGER*4, input. The record number at which to put the value. indices: INTEGER*4 (*), input. An array of dimension indices at which the value is to be put. The number of indices should be consistent with the number of dimensions in the CDF. value: (Depends on data type), input. The value to be put. This value must be passed by reference. On a VMS system, if it is a character string, enclose it in the built-in function %REF(). This is not necessary on a UNIX system. status: INTEGER*4, output. The status code returned for this CDF function. CDF_OK indicates success. Appendix A lists and explains the possible status codes. 2.21 CDF_var_get. Used to get a variable's value. The buffer to receive the value must be large enough to hold it. Usually CDF_var_inquire would be called first to determine the size of the buffer necessary. CALL CDF_var_get (CDF_id, var_num, rec_num, indices, value, status) CDF_id: INTEGER*4, input. The identifier of the CDF to be accessed. var_num: INTEGER*4, input. The variable number to be referenced. rec_num: INTEGER*4, input. The record number from which to access the value. indices: INTEGER*4 (*), input. An array of dimension indices specifying the location of the value within the CDF structure. The number of indices should be consistent with the number of dimensions in the CDF. value: (Depends on data type), output. The value to be gotten. This buffer must be large enough to hold the value. This buffer must also be passed by reference. On a VMS system, if it is a character string, enclose it in the built-in function %REF(). This is not necessary on a UNIX system. status: INTEGER*4, output. The status code returned for this CDF function. CDF_OK indicates success. Appendix A lists and explains the possible status codes. 2.22 CDF_var_hyper_put. Used to put multiple values to a variable. Using this function is more efficient that using CDF_var_put for each value. CALL CDF_var_hyper_put (CDF_id, var_num, rec_start, rec_count, rec_interval, indices, counts, intervals, values, status) CDF_id: INTEGER*4, input. The identifier of the CDF to be accessed. var_num: INTEGER*4, input. The variable identification number. rec_start: INTEGER*4, input. The record number at which the put should start. rec_count: INTEGER*4, input. The number of records which should be put to. rec_interval: INTEGER*4, input. The interval between records to be put to (e.g. an interval of two means every other record). indices: INTEGER*4 (*), input. An array of dimension indices specifying the location within the CDF structure to store the data. The number of indices should be consistent with the number of dimensions in the CDF. counts: INTEGER*4 (*), input. The number of values which should be put along each dimension in each record. The number of counts should be consistent with the number of dimensions in the CDF. intervals: INTEGER*4 (*), input. The interval between values put along each dimension in each record (e.g. an interval of two means every other index). The number of intervals should be consistent with the number of dimensions in the CDF. values: (Depends on data type), input. The buffer of values to be put. If multiple records are being put, they should follow each other in the buffer. Within each record, the data values must be organized in the buffer with the same majority (row or column) as that of the CDF. This buffer must also be passed by reference. On a VMS system, if it is a character string (or array of strings), enclose it in the built-in function %REF(). This in not necessary on a UNIX system. status: INTEGER*4, output. The status code returned for this CDF function. CDF_OK indicates success. Appendix A lists and explains the possible status codes. 2.23 CDF_var_hyper_get. Used to get multiple values from a variable. Using this function is more efficient that using CDF_var_get for each value. CALL CDF_var_hyper_get (CDF_id, var_num, rec_start, rec_count, rec_interval, indices, counts, intervals, values, status) CDF_id: INTEGER*4, input. The identifier of the CDF to be accessed. var_num: INTEGER*4, input. The variable identification number. rec_start: INTEGER*4, input. The record number at which the get should start. rec_count: INTEGER*4, input. The number of records which should be gotten from. rec_interval: INTEGER*4, input. The interval between records to be gotten from (e.g. an interval of two means every other record). indices: INTEGER*4 (*), input. An array of dimension indices specifying the location within the CDF structure to store the data. The number of indices should be consistent with the number of dimensions in the CDF. counts: INTEGER*4 (*), input. The number of values which should be gotten along each dimension in each record. The number of counts should be consistent with the number of dimensions in the CDF. intervals: INTEGER*4 (*), input. The interval between values gotten along each dimension in each record (e.g. an interval of two means every other index). The number of intervals should be consistent with the number of dimensions in the CDF. values: (Depends on data type), output. The values to be gotten. This buffer must be large enough to hold all of the values. In most cases, CDF_var_inquire would be used first to determine the data type and string size (if applicable) for the variable. If multiple records are being gotten, they will follow each other in the buffer. Within each record, the values will be placed in the buffer in the same majority (row or column) as that of the CDF. This buffer must also be passed by reference. On a VMS system, if it is a character string (or array of strings), enclose it in the built-in function %REF(). This is not necessary on a UNIX system. status: INTEGER*4, output. The status code returned for this CDF function. CDF_OK indicates success. Appendix A lists and explains the possible status codes. 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.