CDF Release Notes FILE: rNotes.doc RELEASE:CDF version 2.0 AUTHOR: D. Grogan DATE: 11 February 1991 Table of Contents *- Introduction *- A New Set of Files *- One Library, Three Interfaces *- Differences Between the C and the Fortran Interfaces *- List of Changes and New Features *- Rules and Restrictions on the Use of the CDF C and CDF Fortran Interface *-- Operations on Version 2 CDFs *-- Operations on Version 1 CDFs *- Rules and Restrictions on the Use of the CDF Obsolete Interface *-- Operations on Version 2 CDFs *-- Operations on Version 1 CDFs *- Function Notes (^ indicates a new function) CDFcreate CDFopen CDFdoc ^ CDFinquire CDFclose CDFdelete CDFerror ^ CDFattrCreate CDFattrNum ^ CDFattrRename ^ CDFattrInquire CDFattrEntryInquire ^ CDFattrPut CDFattrGet CDFattrCorrectScope ^ CDFvarCreate CDFvarNum ^ CDFvarRename ^ CDFvarInquire CDFvarPut CDFvarGet CDFvarHyperPut ^ CDFvarHyperGet ^ *- REFERENCES *- Appendix A: Table of Interface Features *- Appendix B: Table of Interface Capabilities *- Introduction This document is written for programmers already familiar with the CDF version 1 software package. These notes will help you upgrade existing CDFs and CDF applications and start taking advantage of the new features and improvements now available. Use these notes in conjunction with one of the two new CDF programming references (CDF C Programming Reference or CDF Fortran Programming Reference). CDF is now written in C and portable to a number of different environments (e.g. SUN/UNIX, VAX/VMS). The CDF version 2 library is an all-new implementation of the capabilities of version 1, with the addition of several significant new features. The software library is new, there are 2 new interfaces to the library, and the structure of CDF files is different from version 1. With this release, we continue support for existing applications by providing an interface that complies with the previous specification, documented in the CDF Implementer's Guide, version 1.1. Most existing CDF programs can be made to run correctly with the new library just by re-linking. There are a few special cases, described below, where programs may fail. Most important among the advantages of the new CDF over the old are these: ¥ multi-platform capability ¥ improved performance ¥ option for transportable data encoding ¥ choice of language interfaces ¥ improved design of attributes ¥ improved error detection and reporting To fully upgrade your CDF applications to version 2 capabilities, you will have to alter their source code. This is always an unpleasant task. In many cases, the code changes will be straightforward changes of text and will not affect program logic. However, in the handling of CDF attributes, we have corrected a problem of the previous library that may require modification of algorithms in some instances. To help make the upgrade easier, we have provided some tools to aid conversion (namely, CDFconvert). We believe that the present design offers much greater flexibility without sacrificing the ease-of-use that has become the CDF's hallmark. In any event, please contact the CDF User Support Office whenever you are unsure of the best course of action or need help upgrading to CDF version 2. *- A New Set of Files As you already know, the term CDF is used in several contexts, sometimes causing confusion. Literally, it refers to a structural format specification for a set of disk files. The true byte-by-byte format is something that almost no one needs to examine. A set of files in the format is called a CDF, or sometimes a CDF dataset. Programmers recognize a version 1 CDF by its file extensions (or filetypes), *.CDF, *.CDH, *.V01, *.V02, ..., *.Vnn, knowing that there are two header files plus a variable, or vector, file for each variable in the CDF. With version 2, this has changed. Now CDFs are created with only one header file, *.CDF, plus the vector files, which are now numbered without any leading zeroes: *.V0, *.V1, *.V2, ..., *.Vnnn. Note also that the vector files are now numbered beginning at zero. [I use the upper-case form of *.CDF and other file designations for clarity. VMS does not distinguish case in file specifications. Unix users will see that their CDF file sets will have lower-case extensions, *.cdf, *.v0, *.v1, *.v2, ..., *.vnnn.] The structures of version 1 and 2 CDFs are not compatible, though both are supported. Do not mix version 1 vector files with version 2 headers in the same CDF, and vice versa. [Programmers have been known to replace a single vector file to fix an otherwise good CDF file set. This is a dubious practice at best, but is sure to cause problems between the versions.] The name of each CDF must be unique. *- One Library, Three Interfaces In the past, the software library that provides the interface to CDF files has also been called CDF, or "the CDF". In version 1 there was only one interface specification for applications programmers, and so, the core library and the interface to it have been usually considered to be equivalent. However, with version 2 of CDF, there is now one library with 3 distinct interfaces. Straightforwardly, a CDF that has been created by the old library is a version 1 CDF. If a CDF has been created by the new library, through any of the three interfaces, it is a version 2 CDF. The three interfaces to the CDF version 2 library are these: CDF C Full version 2 C language interface. CDF Fortran Full version 2 Fortran language interface. CDF Obsolete Same specification as version 1 interface with restrictions noted below. If you are developing any new applications of CDF, use either of the first two language interfaces, as you prefer; they are functionally equivalent. Use CDF Obsolete only to support existing source code. Please do not continue to write new work to the obsolete specification. You have two options concerning existing applications that you may have. Use the CDF Obsolete interface, subject to the restrictions below, or alter their source code to meet the new specifications and use the C or Fortran interface. Restrictions on the usage of the three interfaces are described in a later section. A convenient table of capabilities for the interfaces on both version 1 and version 2 CDFs is provided among the Appendices. *- Differences Between the C and the Fortran Interfaces The two interfaces are functionally equivalent. The primary differences are listed below, some of which are dictated by language convention: 1) Names of subroutines or functions The naming conventions that have been employed distinguish the Fortran interface from the C interface. Those names containing underscores are Fortran subroutines; those without underscores are C functions. Thus, subroutine CDF_var_put is equivalent to the function CDFvarPut. 2) Method for handling return codes The Fortran interface is a set of subroutines. Keeping with version 1 conventions, each subroutine has a return-status output argument called a CDF status variable (previously called an rcode). Keeping with common C-language usage, in the C interface the CDFstatus values are returned by the functions rather than passed in the argument list. The following examples represent the differences. Version 1 subroutine- name and return-code calling convention: integer*4 rcode CDF_create (..., rcode) Version 2 Fortran subroutine-name and status-code convention: integer*4 status CDF_create (..., status) Version 2 C subroutine- name and status-code convention: CDFstatus status; status = CDFcreate(...); 3) Method of passing arguments The Fortran interface follows the language's standard such that all arguments passed are addresses. (Character strings on VAXes are special cases. See the CDF FORTRAN Programming Reference for details.) The C interface keeps to C conventions by passing arguments by their value whenever possible, that is, for simple variables that are function inputs. If you have written C programs that use the version 1 Fortran interface (the CDF obsolete interface), pay special attention to which arguments are now passed by value. 4) Base referent for indexing arrays Following the conventions of each language, the items in any Fortran array are indexed starting at one. The items in a C array are indexed starting at zero. The next section is an item-by-item summary of the general changes in version 2. For notes concerning the usage of individual functions, refer to the section below titled Function Notes. *- List of Changes and New Features ¥ The library is available for VAX VMS and for Sun Unix systems. ¥ Two new language interfaces are provided, one for C and one for Fortran. (Existing CDF applications will continue to be supported through a separate interface to the version 2 library called CDF Obsolete.) ¥ CDF functions in the C interface are named having no underscores, for instance, CDFcreate, CDFvarPut. CDF subroutines in the Fortran interface have names with underscores as in version 1 of the library, CDF_create, CDF_var_put. ¥ Separate programming references are provided for C and Fortran users. ¥ You must now include a file of standard definitions and constants in your applications. For C programs: #include "cdf.h" For Fortran programs: include 'cdf.inc' ¥ These fixed limits of CDF have been increased: The number of CDFs that may be open at one time was 5; it is now 128. The number of variables a CDF may have was 99; it is now 128. The number of attributes a CDF may have was 99; now no limit is imposed by the CDF library. See the language references for all constants and limits. ¥ CDFs can now be created in one of two data representations, HOST_ENCODING, in a machine's native form for best performance, or NETWORK_ENCODING, when inter-machine transport of CDFs is required. The encoding is specified when a CDF is created and cannot later be changed without re-creating the CDF. See notes on the function CDFcreate. ¥ New capabilities have been added for handling attributes. These are design changes that may have an impact on upgrading version 1 CDF applications. There is no longer just one function required for inquiring about attributes. There are now two, CDFattrInquire, which is different in behavior, and CDFattrEntryInquire, which is new. This redesign gives three new capabilities: 1) An attribute entry may consist of an array of values. 2) An attribute's scope of reference is declared to be either GLOBAL_SCOPE or VARIABLE_SCOPE when it is created. For example, a user-defined HISTORY or TITLE attribute might refer to a CDF as a whole (global in scope). On the other hand, an attribute called VALIDMIN might naturally refer to the set of variables individually (variable scope), that is, valid minimum for each variable. The explicit declaration of an attribute's scope resolves an ambiguity of version 1 design that could lead to logical inconsistencies in some programs. 3) The datatype of an attribute is no longer declared when an attribute is created. Entries of attributes are now independently typed at the time they are written. With this important new feature, an entry for a VARIABLE_SCOPE attribute can always be given the same datatype as the variable to which it refers. For instance, an attribute such as VALIDMIN can be an integer when it refers to an integer variable and a floating-point when it refers to a floating-point variable. See notes on all the attribute functions. ¥ New functions have been added for reading and writing dimensional subsets, or hyperplanes, of CDF variables. These functions are provided expressly for accessing very-large CDFs more efficiently than item-by-item variable access allows. The standard CDFvarPut and CDFvarGet functions remain unchanged, and in many cases will be preferred because they are so convenient to use. However, when data volumes are high, CDFvarHyperPut and CDFvarHyperGet will give significant improvements in performance. Additionally, hyperplane access provides an efficient mechanism for subsampling variables across dimensions or across records. ¥ In version 1, references to variables and attributes was either by means of index integers or by character-string names. This was a convenient feature. Unfortunately, it has severely hampered good performance and has been removed. All references to variables and attributes are now by integer index only. However, to retain some of the convenience of the previous usage, new lookup functions for the name strings have been provided, CDFvarNum and CDFattrNum. For example, you can no longer use this form (Fortran style): call CDF_var_put( ..., 'CALORIC',...) ! error results The index to the variable CALORIC must now be used in this manner: call CDF_var_put(..., CDF_var_num(CDFid, 'CALORIC'),...) Or, for best performance, in this way: index_of_caloric = CDF_var_num( CDFid, 'CALORIC') do while (gotwo.eq.cool) call CDF_var_put( ..., index_of_caloric,...) end do All variable functions except CDFvarCreate are affected by this change. A similar change applies to all references to attributes, and thus all attribute functions except CDFattrCreate are affected. See also functions CDFvarNum and CDFattrNum. ¥ Also for the sake of improved performance, CDF datatypes are no longer declared or referenced in any way by character strings. Pre-defined numeric constants identify all CDF datatypes. All previous datatypes are supported under different names. See the language references for defined CDF datatypes. ¥ Previous datatype 'STRING' has been removed. Instead use CDF_CHAR or CDF_UCHAR. ¥ The status codes returned by CDF functions (previously called rcodes, or return-codes) have been expanded for better detection of problems. There are many more of them and they are more meaningful. A new function looks up status codes to provide your program with a text message explaining the status code. See the function CDFerror. ¥ When creating version 2 CDFs, the majority order for storage of variables, row- or column-major, must be declared. We strongly recommend that you use the majority order that matches your application's language, ROW_MAJOR for C, and COL_MAJOR for Fortran. However, situations may arise when you must violate this canon to achieve better performance. See the function CDFcreate. ¥ You can no longer create a CDF that already exists, accidentally or otherwise. This is a departure from previous usage, which was exclusively on VMS systems where files all have a version-number. E.g., ANGELL.CDF;1 ANGELL.CDF;2 ANGELL.CDF;3 and so forth. In order to make the interface consistent across operating systems and provide features to protect from accidental destruction of datasets, CDFcreate will return an error when the CDF already exists. The recommended procedure is for programmers to employ the CDFdelete function when datasets are meant to be re-created. See the function CDFcreate. ¥ You may no longer delete an unopened CDF. To delete a CDF you must first open it. If the CDF is corrupted and cannot be opened, the CDF (all associated files) must be deleted from the command line. ¥ Fortran programmers will continue to index CDF records, attributes, variables, and dimensions starting from an index base of 1. C programmers will reference all these same items beginning at index 0. This scheme conforms to the normal usage of each language. ¥ Among a CDF's set of files, there is no longer a file named *.CDH. Now CDFs are created with only one header file, *.CDF, plus the vector files, which are now numbered without any leading zeroes and beginning at zero: *.V0, *.V1, *.V2, ..., *.Vnnn. *- Rules and Restrictions on the Use of the CDF C and CDF Fortran Interfaces *-- Operations on Version 2 CDFs There are no special restrictions on the use of version 2 CDFs from the two new interfaces. Any CDF you create will be a version 2 CDF; you cannot create a version 1 CDF with the version 2 library. *-- Operations on Version 1 CDFs The restrictions to the use of the full version 2 interfaces all concern operations on existing, version 1 CDFs. If it is possible, we strongly recommend that you convert your version 1 CDFs to version 2 CDFs. This can be done easily using a utility we have provided called CDFconvert. If conversion is not feasible, these restrictions will apply to operations on version-1 CDFs: You can read anything in the CDF, as before. You cannot create variables or attributes. You cannot write attribute entries. You can write new values for variables in existing records (you cannot create new records). *- Rules and Restrictions on the Use of the CDF Obsolete Interface *-- Operations on Version 2 CDFs Any CDF you create with CDF Obsolete will be a version-2 CDF; you cannot create a version 1 CDF. (If you have to create a version 1 CDF, you must use version 1 of the CDF library.) When using CDF Obsolete and operating on version 2 CDFs, you have all of, and only, the capabilities of the version 1 CDF library interface. You may create, inquire, read, or write variables and attributes as before. You do not get the benefit of any of the new features of the version 2 library. The Table of Interface Capabilities summarizes the operations available through the Obsolete interface. *-- Operations on Version 1 CDFs When using CDF Obsolete and operating on version-1 CDFs, these restrictions apply: You can read anything in the CDF, as before. You cannot create variables or attributes. You cannot write attribute entries. You can write new values for variables in existing records (you cannot create new records). *- Functions Notes Each CDF function is listed below with notes of changes in its usage. The notes apply to both Fortran and C usage. However, the function and argument names shown are those of the C version. The two interfaces are sufficiently alike that the meaning will be clear to Fortran programmers. Three categories of function are identified, New Functions, Revised Functions (Major), and Revised Functions (Minor). New functions are those not available in version 1 of the CDF library. Only the purpose of each new function is noted, briefly. See the appropriate language reference for usage of new functions. Functions in the category of major revision are those which were available in version 1, but which now have significant change to the number or order of their arguments. A function is classified in the minor revision category if previously there was a comparable subroutine with the same arguments, in the same order. Notice that some of the functions in this category do have changes to the types of some of their arguments, for example, when attrNum, varNum, or dataType arguments are present. The differences mentioned above in status-code handling between C and Fortran are disregarded in the notes below. Likewise, whether an argument is the address of an object (pass by reference in VMS terms) or a temporary copy of the argument (pass by value), is not noted. Always consult the appropriate CDF language reference as final authority on function usage. First, here is a list of version 2 functions by change categories. Revised Functions (Minor) CDFopen CDFclose CDFattrGet CDFvarPut CDFvarGet Revised Functions (Major) CDFcreate CDFinquire CDFdelete CDFattrCreate CDFattrInquire CDFattrPut CDFvarCreate CDFvarInquire New Functions CDFdoc CDFerror CDFattrNum CDFattrRename CDFattrEntryInquire CDFattrCorrectScope CDFvarNum CDFvarRename CDFvarHyperGet CDFvarHyperPut Next, listed in the order in which they appear in the language references, are the function notes. ________ CDFcreate Obsolete: CDF_create (CDF_name, num_dims, dim_sizes, CDF_id, rcode) Fortran: CDF_create (CDF_name, num_dims, dim_sizes, encoding, majority, CDF_id, status) C: CDFcreate (*CDFname, numDims, dimSizes[], encoding, majority, *id) -- Notes -- Revised Function (Major). Arguments CDFname, numDims, dimSizes, and the CDFid are essentially the same. Arguments encoding and majority are new. ________ CDFopen Obsolete: CDF_open (CDF_name, CDF_id, rcode) Fortran: CDF_open (CDF_name, CDF_id, status) C: CDFopen (*CDFname, *id) -- Notes -- Revised Function (Minor). The arguments are essentially the same. ________ CDFdoc Fortran: CDF_doc (CDF_id, version, release, text, status) C: CDFdoc (id, *version, *release, text[CDF_DOCUMENT_LEN+1]) -- Notes -- New Function. This gets documentary text from a CDF including the NSSDC address and copyright notice. It will also tell you what version of the CDF library created a CDF. See the appropriate language reference. ________ CDFinquire Obsolete: CDF_inquire (CDF_id, num_dims, dim_sizes, num_recs, num_vars, num_attrs, rcode) Fortran: CDF_inquire (CDF_id, num_dims, dim_sizes, encoding, majority, num_recs, num_vars, num_attrs, status) C: CDFinquire (id, *numDims, dimSizes[], *encoding, *majority, *maxRec, *numVars, *numAttrs) -- Notes -- Revised Function (Major). Arguments CDFid, numDims, dimSizes, numVars, and numAttrs are essentially the same. The num_recs parameter has been replaced by maxRec which is the maximum record number in the CDF. Arguments encoding and majority are new. ________ CDFclose Obsolete: CDF_close (CDF_id, rcode) Fortran: CDF_close (CDF_id, status) C: CDFclose (id) -- Notes -- Revised Function (Minor). This function is essentially the same. ________ CDFdelete Obsolete: CDF_delete (CDF_name, rcode) Fortran: CDF_delete (CDF_id, status) C: CDFdelete (id) -- Notes -- Revised Function (Major). The argument CDFid is new. You may no longer delete an unopened CDF. This function no longer should receive the name of the CDF, it should get the CDFid of an open CDF. To delete a CDF you must first use CDFopen to open it. If the CDF is corrupted and cannot be opened, the CDF (all associated files) must be deleted from the command line. ________ CDFerror Fortran: CDF_error (status, text) C: CDFerror (stat, message[CDF_ERRTEXT_LEN+1]) -- Notes -- New Function. This function looks-up CDF status codes, giving a text explanation of code. ________ CDFattrCreate Obsolete: CDF_attr_create (CDF_id, attr_mnemonic, data_type, num_bytes, rcode) Fortran: CDF_attr_create (CDF_id, attr_name, attr_scope, attr_num, status) C: CDFattrCreate ( id, *attrName, attrScope, *attrNum) -- Notes -- Revised Function (Major). Argument CDFid is essentially the same. Argument attrName is essentially the same, previously called a mnemonic. Arguments data_type and num_bytes have been removed. The datatype of an attribute entry is now specified when the entry is written (see CDFattrPut). The attrScope is new. This explicitly declares the intended scope of the attribute, whether it applies to the CDF as whole (GLOBAL_SCOPE) or to variables (VARIABLE_SCOPE). The output attrNum argument is also new; it is the attribute's number. ________ CDFattrNum Fortran: CDF_attr_num (CDF_id, attr_name) C: CDFattrNum (id, *attrName) -- Notes -- New Function. Given a character-string name of an attribute, this will return the attribute's number. ________ CDFattrRename Fortran: CDF_attr_rename (CDF_id, attr_num, attr_name, status) C: CDFattrRename (id, attrNum, *attrName) -- Notes -- New Function. This function can be used to change the name of an existing attribute. ________ CDFattrInquire Obsolete: CDF_attr_inquire (CDF_id, attr_id, attr_num, attr_mnemonic, data_type, num_bytes, num_entries, rcode) Fortran: CDF_attr_inquire (CDF_id, attr_num, attr_name, attr_scope, num_entries, status) C: CDFattrInquire (id, attrNum, *attrName, *attrScope, *maxEntry) -- Notes -- Revised Function (Major). The attrNum is an attribute number; no more support for attribute references by name. The attrNum argument replaces 2 former arguments attr_id and attr_num. Argument attrName is essentially the same, previously called a mnemonic. Former arguments data_type and num_bytes have been removed (see CDFattrEntryInquire). The attrScope output argument is new. ________ CDFattrEntryInquire Fortran: CDF_attr_entry_inquire (CDF_id, attr_num, entry_num, data_type, num_elements, status) C: CDFattrEntryInquire (id, attrNum, entryNum, *dataType, *numElements) -- Notes -- New Function. This new function is required because attributes are now independently-typed entry by entry. Arguments attrNum and entryNum identify the attribute entry. You may now have a one-dimensional array of values of any datatype for an attribute entry. The numElements indicates the number of items in the array of the dataType. (String attributes are now arrays of characters.) ________ CDFattrPut Obsolete: CDF_attr_put (CDF_id, attr_id, entry_id, attr_value, rcode) Fortran: CDF_attr_put (CDF_id, attr_num, entry_num, data_type, num_elements, value, status) C: CDFattrPut (id, attrNum, entryNum, dataType, numElements, *value) -- Notes -- Revised Function (Major). CDFid is essentially the same. The attrNum argument replaces attr_id. The attrNum is an attribute number; no more support for attribute references by name. The entryNum argument replaces entry_id, same usage. The dataType argument is new to this function to support independent typing of entries. (Character-strings designating dataTypes are no longer supported, for example, the predefined constant CDF_INT4 replaces 'INT*4'.) The numElements argument is new, indicating how many elements of the dataType are to be written. The value argument is essentially the same; it is the buffer from which the numElements of dataType are taken for writing to the CDF. ________ CDFattrGet Obsolete: CDF_attr_get: (CDF_id, attr_id, entry_id, attr_value, rcode) Fortran: CDF_attr_get (CDF_id, attr_num, entry_num, value, status) C: CDFattrGet (id, attrNum, entryNum) -- Notes -- Revised Function (Minor). CDFid is essentially the same. The attrNum argument replaces attr_id. The attrNum is an attribute number; no more support for attribute references by name. The entryNum argument replaces entry_id, same usage. The value argument is essentially the same; it is the buffer into which the entry's numElements of dataType are placed after reading from the CDF. (You can only know the numElements and dataType by using the function CDFattrEntryInquire.) ________ CDFattrCorrectScope Fortran: CDF_attr_correct_scope (CDF_id, attr_num, attr_scope, status) C: CDFattrCorrectScope (id, attrNum, attrScope) -- Notes -- New Function. *** Not only is it new, it won't get old. (It will not be supported in CDF V3.0) *** This function is temporary to assist in the transition from version 1 CDFs to version 2 CDFs. Please read the notations about it in the appropriate language reference. ________ CDFvarCreate Obsolete: CDF_var_create (CDF_id, var_mnemonic, data_type, num_bytes, record_variance, dim_variances, rcode) Fortran: CDF_var_create (CDF_id, var_name, data_type, num_elements, rec_variance, dim_variances, var_num, status) C: CDFvarCreate (id, *VarName, dataType, numElements, recVariance, dimVariances[], *varNum) -- Notes -- Revised Function (Major). Arguments CDFid and varName (mnemonic) are essentially the same. Argument dataType fills the same function, but character-strings designating dataTypes are no longer supported, for example, the predefined constant CDF_INT4 replaces 'INT*4'. numElements replaces num_bytes and should be 1 except when the dataType is CDF_CHAR or CDF_UCHAR, that is, when the data type is a string of characters. The arguments recVariance and dimVariances are essentially the same. The output varNum argument is new; it is the variable's number. ________ CDFvarNum Fortran: CDF_var_num (CDF_id, var_name) C: CDFvarNum (id, *varName) -- Notes -- New Function. Given a character-string name of a variable, this will return the variable's number. ________ CDFvarRename Fortran: CDF_var_rename (CDF_id, var_num, var_name, status) C: CDFvarRename (id, varNum, *varName) -- Notes -- New Function. This function can be used to change the name of an existing variable. ________ CDFvarInquire Obsolete: CDF_var_inquire (CDF_id, var_id, var_num, var_mnemonic, data_type, num_bytes, record_variance, dim_variances, rcode) Fortran: CDF_var_inquire (CDF_id, var_num, var_name, data_type, num_elements, rec_variance, dim_variances, status) C: CDFvarInquire (id, varNum, *VarName, *dataType, *numElements, *recVariance, dimVariances[]) -- Notes -- Revised Function (Major). CDFid is essentially the same. Argument varNum replaces previous 2 arguments var_id and var_num. The varNum is a variable number; no more support for variable references by name. Output argument varName (mnemonic) is essentially the same. Argument dataType is no longer a string. Character-strings designating dataTypes are no longer supported, for example, the predefined constant CDF_INT4 replaces 'INT*4'. stringSize replaces num_bytes and will be 1 except when the dataType is CDF_CHAR or CDF_UCHAR, that is, when the data type is a string of characters. Arguments recVariance and dimVariances are the same. ________ CDFvarPut Obsolete: CDF_var_put (CDF_id, var_id, record_num, indices, value, rcode) Fortran: CDF_var_put (CDF_id, var_num, rec_num, indices, value, status) C: CDFvarPut (id, varNum, recNum, indices[], *value) -- Notes -- Revised Function (Minor). CDFid is essentially the same. The varNum is a variable; no more support for variable references by name. The other arguments, recNum, indices, and value, are the same. ________ CDFvarGet Obsolete: CDF_var_get (CDF_id, var_id, record_num, indices, value, rcode) Fortran: CDF_var_get (CDF_id, var_num, rec_num, indices, value, status) C: CDFvarGet (id, varNum, recNum, indices[], *value) -- Notes -- Revised Function (Minor). CDFid is essentially the same. The varNum is a variable; no more support for variable references by name. The other arguments, recNum, indices, and value, are the same. ________ CDFvarHyperPut Fortran: CDF_var_hyper_put (CDF_id, var_num, rec_start, rec_count, rec_interval, indices, counts, intervals, values, status) C: CDFvarHyperPut (id, varNum, recStart, recCount, recInterval, indices[], counts[], intervals[], *buffer) -- Notes -- New Function. A single call can put a multi-item, dimensional subset of data from a variable, slicing dimensions, or putting a range of records at once. Writing at regular intervals is also supported. See the appropriate language reference. ________ CDFvarHyperGet Fortran: CDF_var_hyper_get (CDF_id, var_num, rec_start, rec_count, rec_interval, indices, counts, intervals, values, status) C: CDFvarHyperGet (id, varNum, recStart, recCount, recInterval, indices[], counts[], intervals[], *buffer) -- Notes -- New Function. A single call can get a multi-item, dimensional subset of data from a variable, slicing dimensions, or getting from a range of records at once. Sampling at regular intervals is also supported. See the appropriate language reference. *- REFERENCES CDF C Programming Reference, January 1991 CDF Fortran Programming Reference, January 1991 CDF Implementer's Guide (DEC VAX/VMS), August 1988 *- Appendix A: Table of interface Features CDF C CDF Fortran CDF Obsolete __________ ___________ __________ library: cdf20lib cdf20lib cdf interface obj: -- cdf_v2_fortran_if cdf_v2_obsolete_if include: cdf.h cdf.inc no include file systems: VMS, Sun/Unix VMS, Sun/Unix VMS only traits: best performance; slight added slight added overhead; overhead; all v2 features; all v2 features; v1 features only; example calling style: status=CDFvarGet(...); call CDF_var_get(...status) call CDF_var_get(...rcode) Indexing Scheme for: Records 0 to N-1 1 to N 1 to N Variables 0 to N-1 1 to N 1 to N Attributes 0 to N-1 1 to N 1 to N Dimensions 0 to N-1 1 to N 1 to N Attribute entries 0 to N-1 1 to N 1 to N Variable Storage: structure user-defined user-defined column-major *- Appendix B: Table of Interface Capabilities for operations on version-1 and version-2 CDFs from the 3 interfaces. Interface C and Fortran Obsolete ---------------------------------------------------------------- version-1 version-2 version-1 version-2 CDF operation CDF CDF CDF CDF -------------------------------------------------------------------------------- open yes yes yes yes close yes yes yes yes inquire yes yes yes yes delete yes yes yes yes attrInquire yes yes yes yes [1] varInquire yes yes yes yes [2] attrGet yes yes yes yes varGet yes yes yes yes -------------------------------------------------------------------------------- create no yes no yes attrCreate no yes no yes varCreate no yes no yes attrPut no yes no yes -------------------------------------------------------------------------------- varPut to an yes yes yes yes existing record -------------------------------------------------------------------------------- varPut to a no yes no yes new record [1] Some version 2 features of attributes will not map exactly to the Obsolete interface requirements for these functions. In particular, version 2 supports new datatypes and arrays of attributes not found in version 1. [2] Version 2 supports new variable datatypes not found in version 1. Interface C and Fortran Obsolete ---------------------------------------------------------------- version-1 version-2 version-1 version-2 CDF operation CDF CDF CDF CDF -------------------------------------------------------------------------------- doc yes yes no no error yes yes no no attrNum yes yes no no attrEntryInquire yes yes no no varNum yes yes no no varHyperGet yes yes no no -------------------------------------------------------------------------------- attrRename no yes no no attrCorrectScope no yes no no varRename no yes no no -------------------------------------------------------------------------------- varHyperPut to yes yes no no existing record -------------------------------------------------------------------------------- varHyperPut to no yes no no a new record