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