Copyright: SDF 22Jan97


Scientific Data Formats Guide TOC
IDL Scientific Data Formats Guide

This help file contains the IDL Scientfic Data Formats Guide.


IDL Scientific Data Formats Guide

Select "Contents," "Keyword Search," or "Text Search" from the

Navigate menu, or click the "Help Topics" button, for more

navigational aids.


Alphabetical List of Data Format Routines

All   CDF   HDF   NCDF

CDF_ATTCREATE

CDF_ATTDELETE

CDF_ATTEXISTS

CDF_ATTGET

CDF_ATTINQ

CDF_ATTNUM

CDF_ATTPUT

CDF_ATTRENAME

CDF_CLOSE

CDF_CONTROL

CDF_CREATE

CDF_DELETE

CDF_DOC

CDF_ENCODE_EPOCH

CDF_EPOCH

CDF_ERROR

CDF_EXISTS

CDF_INQUIRE

CDF_LIB_INFO

CDF_OPEN

CDF_PARSE_EPOCH

CDF_VARCREATE

CDF_VARDELETE

CDF_VARGET

CDF_VARGET1

CDF_VARINQ

CDF_VARNUM

CDF_VARPUT

CDF_VARRENAME

HDF_CLOSE

HDF_DELDD

HDF_DF24_ADDIMAGE

HDF_DF24_GETIMAGE

HDF_DF24_GETINFO

HDF_DF24_LASTREF

HDF_DF24_NIMAGES

HDF_DF24_READREF

HDF_DF24_RESTART

HDF_DFAN_ADDFDS

HDF_DFAN_ADDFID

HDF_DFAN_GETDESC

HDF_DFAN_GETFDS

HDF_DFAN_GETFID

HDF_DFAN_GETLABEL

HDF_DFAN_LABLIST

HDF_DFAN_LASTREF

HDF_DFAN_PUTDESC

HDF_DFAN_PUTLABEL

HDF_DFP_ADDPAL

HDF_DFP_GETPAL

HDF_DFP_LASTREF

HDF_DFP_NPALS

HDF_DFP_PUTPAL

HDF_DFP_READREF

HDF_DFP_RESTART

HDF_DFP_WRITEREF

HDF_DFR8_ADDIMAGE

HDF_DFR8_GETIMAGE

HDF_DFR8_GETINFO

HDF_DFR8_LASTREF

HDF_DFR8_NIMAGES

HDF_DFR8_PUTIMAGE

HDF_DFR8_READREF

HDF_DFR8_RESTART

HDF_DFR8_SETPALETTE

HDF_DFSD_ADDDATA

HDF_DFSD_DIMGET

HDF_DFSD_DIMSET

HDF_DFSD_ENDSLICE

HDF_DFSD_GETDATA

HDF_DFSD_GETINFO

HDF_DFSD_GETSLICE

HDF_DFSD_PUTSLICE

HDF_DFSD_READREF

HDF_DFSD_SETINFO

HDF_DFSD_STARTSLICE

HDF_DUPDD

HDF_EXISTS

HDF_ISHDF

HDF_NEWREF

HDF_NUMBER

HDF_OPEN

HDF_SD_ADDDATA

HDF_SD_ATTRFIND

HDF_SD_ATTRINFO

HDF_SD_ATTRSET

HDF_SD_CREATE

HDF_SD_DIMGET

HDF_SD_DIMGETID

HDF_SD_DIMSET

HDF_SD_END

HDF_SD_ENDACCESS

HDF_SD_FILEINFO

HDF_SD_GETDATA

HDF_SD_GETINFO

HDF_SD_IDTOREF

HDF_SD_ISCOORDVAR

HDF_SD_NAMETOINDEX

HDF_SD_REFTOINDEX

HDF_SD_SELECT

HDF_SD_SETEXTFILE

HDF_SD_SETINFO

HDF_SD_START

HDF_VD_ATTACH

HDF_VD_DETACH

HDF_VD_FDEFINE

HDF_VD_FEXIST

HDF_VD_FIND

HDF_VD_GET

HDF_VD_GETID

HDF_VD_GETINFO

HDF_VD_GETNEXT

HDF_VD_INSERT

HDF_VD_ISVD

HDF_VD_ISVG

HDF_VD_LONE

HDF_VD_READ

HDF_VD_SEEK

HDF_VD_SETINFO

HDF_VD_WRITE

HDF_VG_ADDTR

HDF_VG_ATTACH

HDF_VG_DETACH

HDF_VG_GETID

HDF_VG_GETINFO

HDF_VG_GETNEXT

HDF_VG_GETTR

HDF_VG_GETTRS

HDF_VG_INQTR

HDF_VG_INSERT

HDF_VG_ISVD

HDF_VG_ISVG

HDF_VG_LONE

HDF_VG_NUMBER

HDF_VG_SETINFO

NCDF_ATTCOPY

NCDF_ATTDEL

NCDF_ATTGET

NCDF_ATTINQ

NCDF_ATTNAME

NCDF_ATTPUT

NCDF_ATTRENAME

NCDF_CLOSE

NCDF_CONTROL

NCDF_CREATE

NCDF_DIMDEF

NCDF_DIMID

NCDF_DIMINQ

NCDF_DIMRENAME

NCDF_EXISTS

NCDF_INQUIRE

NCDF_OPEN

NCDF_VARDEFNCDF_VARGET

NCDF_VARGET

NCDF_VARGET1

NCDF_VARID

NCDF_VARINQ

NCDF_VARPUT

NCDF_VARRENAME


CDF Routines
CDF

All   CDF   HDF   NCDF

CDF_ATTCREATE

CDF_ATTDELETE

CDF_ATTEXISTS

CDF_ATTGET

CDF_ATTINQ

CDF_ATTNUM

CDF_ATTPUT

CDF_ATTRENAME

CDF_CLOSE

CDF_CONTROL

CDF_CREATE

CDF_DELETE

CDF_DOC

CDF_ENCODE_EPOCH

CDF_EPOCH

CDF_ERROR

CDF_EXISTS

CDF_INQUIRE

CDF_LIB_INFO

CDF_OPEN

CDF_PARSE_EPOCH

CDF_VARCREATE

CDF_VARDELETE

CDF_VARGET

CDF_VARGET1

CDF_VARINQ

CDF_VARNUM

CDF_VARPUT

CDF_VARRENAME


HDF Routines
HDF

All   CDF   HDF   NCDF

HDF_CLOSE

HDF_DELDD

HDF_DF24_ADDIMAGE

HDF_DF24_GETIMAGE

HDF_DF24_GETINFO

HDF_DF24_LASTREF

HDF_DF24_NIMAGES

HDF_DF24_READREF

HDF_DF24_RESTART

HDF_DFAN_ADDFDS

HDF_DFAN_ADDFID

HDF_DFAN_GETDESC

HDF_DFAN_GETFDS

HDF_DFAN_GETFID

HDF_DFAN_GETLABEL

HDF_DFAN_LABLIST

HDF_DFAN_LASTREF

HDF_DFAN_PUTDESC

HDF_DFAN_PUTLABEL

HDF_DFP_ADDPAL

HDF_DFP_GETPAL

HDF_DFP_LASTREF

HDF_DFP_NPALS

HDF_DFP_PUTPAL

HDF_DFP_READREF

HDF_DFP_RESTART

HDF_DFP_WRITEREF

HDF_DFR8_ADDIMAGE

HDF_DFR8_GETIMAGE

HDF_DFR8_GETINFO

HDF_DFR8_LASTREF

HDF_DFR8_NIMAGES

HDF_DFR8_PUTIMAGE

HDF_DFR8_READREF

HDF_DFR8_RESTART

HDF_DFR8_SETPALETTE

HDF_DFSD_ADDDATA

HDF_DFSD_DIMGET

HDF_DFSD_DIMGET

HDF_DFSD_ENDSLICE

HDF_DFSD_GETDATA

HDF_DFSD_GETINFO

HDF_DFSD_GETSLICE

HDF_DFSD_PUTSLICE

HDF_DFSD_READREF

HDF_DFSD_SETINFO

HDF_DFSD_STARTSLICE

HDF_DUPDD

HDF_EXISTS

HDF_ISHDF

HDF_NEWREF

HDF_NUMBER

HDF_OPEN

HDF_SD_ADDDATA

HDF_SD_ATTRFIND

HDF_SD_ATTRINFO

HDF_SD_ATTRSET

HDF_SD_CREATE

HDF_SD_DIMGET

HDF_SD_DIMGETID

HDF_SD_DIMSET

HDF_SD_END

HDF_SD_ENDACCESS

HDF_SD_FILEINFO

HDF_SD_GETDATA

HDF_SD_GETINFO

HDF_SD_IDTOREF

HDF_SD_ISCOORDVAR

HDF_SD_NAMETOINDEX

HDF_SD_REFTOINDEX

HDF_SD_SELECT

HDF_SD_SETEXTFILE

HDF_SD_SETINFO

HDF_SD_START

HDF_VD_ATTACH

HDF_VD_DETACH

HDF_VD_FDEFINE

HDF_VD_FEXIST

HDF_VD_FIND

HDF_VD_GET

HDF_VD_GETID

HDF_VD_GETINFO

HDF_VD_GETNEXT

HDF_VD_INSERT

HDF_VD_ISVD

HDF_VD_ISVG

HDF_VD_LONE

HDF_VD_READ

HDF_VD_SEEK

HDF_VD_SETINFO

HDF_VD_WRITE

HDF_VG_ADDTR

HDF_VG_ATTACH

HDF_VG_DETACH

HDF_VG_GETID

HDF_VG_GETINFO

HDF_VG_GETNEXT

HDF_VG_GETTR

HDF_VG_GETTRS

HDF_VG_INQTR

HDF_VG_INSERT

HDF_VG_ISVD

HDF_VG_ISVG

HDF_VG_LONE

HDF_VG_NUMBER

HDF_VG_SETINFO


NCDF Routines
NCDF

All   CDF   HDF   NCDF

NCDF_ATTCOPY

NCDF_ATTDEL

NCDF_ATTGET

NCDF_ATTINQ

NCDF_ATTNAME

NCDF_ATTPUT

NCDF_ATTRENAME

NCDF_CLOSE

NCDF_CONTROL

NCDF_CREATE

NCDF_DIMDEF

NCDF_DIMID

NCDF_DIMINQ

NCDF_DIMRENAME

NCDF_EXISTS

NCDF_INQUIRE

NCDF_OPEN

NCDF_VARDEFNCDF_VARGET

NCDF_VARGET

NCDF_VARGET1

NCDF_VARID

NCDF_VARINQ

NCDF_VARPUT

NCDF_VARRENAME


Scientific Data Formats

This chapter provides an overview the three self-describing scientific data formats supported by IDL—CDF (Common Data Format), HDF (Hierarchical Data Format), and netCDF (Network Common Data Format). These data formats are now supported on all IDL platforms. Detailed documentation for each routine can be found in this volume.


CDF - Common Data Format
CDF—Common Data Format

The Common Data Format is a file format that facilitates the storage and retrieval of multi-dimensional scientific data. This version of IDL supports CDF 2.5. IDL's CDF routines all begin with the prefix "CDF_". Documentation for these routines can be found beginning on page 5.

CDF is a product of National Space Science Data Center (NSSDC). General information about CDF, including the "frequently-asked-questions" (FAQ) list, software, and CDF's IDL library (an alternative interface between CDF and IDL) are available on the World Wide Web at:

http://nssdc.gsfc.nasa.gov/cdf/cdf_home.html

If you do not have access to the WWW you can get CDF information via ftp at:

ftp://ncgl.gsfc.nasa.gov/pub/cdf/FAQ.doc

For assistance via e-mail, send a message to the internet address:

cdfsupport@nssdca.gsfc.nasa.gov


HDF - Hierarchical Data Format
HDF—Hierarchical Data Format

The Hierarchical Data Format (HDF) is a multi-object file format that facilitates the transfer of various types of data between machines and operating systems. HDF is a product of the National Center for Supercomputing Applications (NCSA). HDF is designed to be flexible, portable, self-describing and easily extensible for future enhancements or compatibility with other standard formats. The HDF library contains interfaces for storing and retrieving images and multi-dimensional scientific data. This version of IDL supports HDF 4.0. IDL's HDF routines all begin with the prefix "HDF_". Documentation for these routines can be found beginning on page 67.

Further information about HDF can be found on the World Wide Web at the HDF Information Server:

http://hdf.ncsa.uicu.edu

Alternately, you can send e-mail to hdfhelp@ncsa.uiuc.edu.


NetCDF - Network Common Data Format
NetCDF—Network Common Data Format

The network Common Data Format (netCDF) is a self-describing scientific data access interface and library developed at the Unidata Program Center in Boulder, Colorado. The netCDF interface and library use XDR (eXternal Data Representation) to make the data format machine-independent. This version of IDL supports netCDF 2.4. IDL's NetCDF routines all begin with the prefix "NCDF_". Documentation for these routines can be found beginning on page 221.

More information about netCDF can be found on Unidata's netCDF World Wide Web home page which can be found at:

http://www.unidata.ucar.edu/packages/netcdf/

Further information and the original netCDF documentation can be obtained from Unidata at the following addresses:

UCAR Unidata Program Center
P.O. Box 3000
Boulder, Colorado, USA 80307
(303) 497-8644
email: support@unidata.ucar.edu


Scientific Data Formats
Alphabetical indexing for Scientific Data Formats is arranged in three separate sections:

CDF - Common Data Format

HDF - Hierarchical Data Format

NetCD - Network Common Data Format

You may also consult the following comprehensive index:

Alphabetical List of Data Format Routines

Select "Contents," "Keyword Search," or "Text Search" from the

Navigate menu, or click the "Help Topics" button,

for more navigational aids.


Common Data Format

This chapter details the interface routines for the Common Data Format. General notes about the interface are presented below, followed by individual descriptions of the routines. This version of IDL supports CDF V2.5.

CDF Version 2.5 Compatibility Warning

CDFs created with CDF V2.5 (the version currently used by IDL) take up less disk space than CDFs created with previous CDF distributions. The new version saves 1689 bytes per CDF file regardless of the file's contents, plus an additional savings of 128 bytes per variable. A side effect of this improvement is that V2.5 CDFs can only be read with the CDF V2.5 distribution. CDF V2.5 files are not readable by previous versions of CDF.

Variables and Attributes

Information in a CDF file consists of attributes (metadata) and collections of data records (variables).

Variables

IDL can create CDF files representing any data that can be stored in a zero- to eight-dimensional array. CDF supports two distinct types of variables, rVariables and zVariables. For reasons of efficiency, CDF uses "variances" to indicate whether data is unique between records and dimensions. For example, consider a data set of simultaneous surface temperatures at a variety of locations, the IDL code for creating the CDF file is included at the end of this section. A variable representing "GMT time" will vary from record to record, but not dimension to dimension (since all data are taken simultaneously). On the other hand, a variable such as longitude may not vary from record to record, but will vary from dimension to dimension. Record variance is set using the REC_VARY and REC_NOVARY keywords to CDF_VARCREATE, while dimensional variance is set through the DimVary argument to CDF_VARCREATE. In both cases, the default is varying data.

rVariables

rVariables (or "regular" variables) are multidimensional arrays of values, each having the same dimensions. That is, all rVariables in a CDF must have the same number of dimensions and dimension sizes. In IDL, the rVariable dimension sizes are declared when the CDF file is first created with CDF_CREATE. In the above example at the end of this section, all variables except "time" are rVariables.

zVariables

zVariables (The "z" doesn't stand for anything—the CDF people just like the letter "z") are multidimensional arrays of values of the same data type. zVariables can have different dimensionality from other zVariables and rVariables. In general, zVariables are much more flexible, and therefore easier to use, than rVariables.

For more discussion on CDF variables, see sections 1.5 ("Organizing Your Data in CDF") of the version 2.5 CDF User's Guide.

Attributes

Attributes can contain auxiliary information about an entire CDF file (global scope attributes or gAttributes), or about particular CDF variables (variable scope attributes or rAttributes/zAttributes depending on variable type). CDF attributes can be scalar or vector in nature, and of any valid datatype. In the case of vector, or multiple entry, attributes the user must keep track of the entry numbers ( in CDF terms these are the gEntry, rEntry, or zEntry numbers depending on attribute type). For example, every rVariable in a CDF file might have an rAttribute named "Date". A vector zVariable might have a zAttribute named "Location" with values such as ["Melbourne Beach", "Crowley", ...]. A global attribute "MODS" might be used to keep track of the modification history of a CDF file (see "CDF_ATTPUT" on page 20). Note however, that variables cannot have multiple attributes with the same names. In IDL, CDF attributes are created with CDF_ATTPUT and retrieved with CDF_ATTGET.

For more discussion on CDF variables, see section 1.6 ("Attributes") of the version 2.5 CDF User's Guide. Certain "standard" attributes are required for a file to conform to the NSSDC standard. For a description of these attributes see section 2.5.1 ("Standard Attributes") of the Version 2.5 CDF User's Guide.

CDF File Options

File Type

The SINGLE_FILE and MULTI_FILE keywords to CDF_CREATE allow CDFs to be written as either:

1.	all data in a single file, or

2.	a separate file for each variable, plus a master file for global information.

The default is MULTI_FILE. For more discussion on CDF file format options, see section 1.4.1 of the version 2.5 CDF User's Guide.

Data Encodings/Decodings

Keywords to CDF_CREATE allow files to be written in a variety of data encoding and decoding options. (For example, the /SUN_ENCODING keyword creates a file in the SUN native encoding scheme). The default encoding/decoding is network (XDR). All CDF encodings and decodings can be written or read on all platforms, but matching the encoding with the architecture used provides the best performance. If you work in a single-platform environment most of the time, select HOST_ENCODING for maximum performance. If you know that the CDF file will be transported to a computer using another architecture, specify the encoding for the target architecture or specify NETWORK_ENCODING (the default). Specifying the target architecture provides maximum performance on that architecture; specifying NETWORK_ENCODING provides maximum flexibility.

For more discussion on CDF encoding/decoding methods and combinations, see sections 2.2.7 ("Encoding") and 2.2.8 ("Decoding") of the version 2.5 CDF User's Guide.

Creating CDF Files

The following list details the basic IDL commands needed to create a new CDF file:

•	CDF_CREATE: Call this procedure to begin creating a new file. CDF_CREATE contains a number of keywords which affect the internal format of the new CDF file.

•	CDF_VARCREATE: Define the variables to be used in the file.

•	CDF_ATTPUT: Optionally, use attributes to describe the data.

•	CDF_VARPUT: Write the appropriate data to the CDF file.

•	CDF_CLOSE: Close the file.

Reading CDF Files

The following commands are the basic commands needed to read data from a CDF file:

•	CDF_OPEN: Open an existing CDF file.

•	CDF_INQUIRE: Call this function to find the general information about the contents of the CDF file.

•	CDF_CONTROL: Call this function to obtain further information about the CDF file

•	CDF_VARINQ: Retrieve the names, types, sizes, and other information about the variables in the CDF file.

•	CDF_VARGET: Retrieve the variable values.

•	CDF_ATTINQ: Optionally, retrieve the names, scope and other information about the CDFs attributes.

•	CDF_ATTGET: Optionally, retrieve the attributes.

•	CDF_CLOSE: Close the file.

•	If the structure of the CDF file is already known, the inquiry routines do not need to be called—only CDF_OPEN, CDF_ATTGET, CDF_VARGET, and CDF_CLOSE would be needed.

Type Conversion

Values are converted to the appropriate type before being written to a CDF file. For example, in the commands below, IDL converts the string "12" to a floating-point 12.0 before writing it:

varid=CDF_VARCREATE(fileid, 'VarName',['VARY','VARY'],$

    DIM=[2,3+5],/CDF_FLOAT)

CDF_VARPUT, fileid, 'VarName', '12' 	; Reference by variable ID

Specifying Attributes and Variables

Variables and attributes can be referred to either by name or by their ID numbers in most CDF routines. For example, in the CDF_VARCREATE command shown in the example under "Type Conversion" on page 9, the following command would have been equivalent:

CDF_VARCREATE, fileid, varid, '12'	;Reference by variable ID.

Example: Creating a CDF File

The following is a simple example demonstrates the basic procedure used in creating a CDF file. See "Variables and Attributes" on page 6 for a discussion of the variances used in this example. See the documentation for individual CDF routines for more specific examples.

id = CDF_CREATE('Temperature.cdf', [2,3], /CLOBBER )

att_id = CDF_ATTCREATE(id, 'Title', /GLOBAL)

CDF_ATTPUT, id, att_id, 0, 'My Fancy CDF'

att1_id = CDF_ATTCREATE(id, 'Planet', /GLOBAL)

CDF_ATTPUT, id, 'Planet', 0, 'Mars'

time_id = CDF_VARCREATE(id, 'Time', ['NOVARY', 'NOVARY'], $

    /REC_VARY)

att2_id = CDF_ATTCREATE(id, 'Time Standard', /VARIABLE_SCOPE)

CDF_ATTPUT, id, att2_id, time_id, 'GMT'	;times are every half hour starting a 8 am GMT.

FOR I=0,9 DO CDF_VARPUT, id, time_id, 8.+ 0.5 * I, rec_start=I

temp_id = CDF_VARCREATE(id, 'Temp', ['VARY', 'VARY'], $

    /REC_VARY, /ZVAR, DIMENSIONS=[2,3])

long_id = CDF_VARCREATE(id, 'Longitude', ['VARY', 'VARY'], $

    /REC_NOVARY)

lat_id = CDF_VARCREATE(id, 'Latitude', ['VARY', 'VARY'], $

    /REC_NOVARY)

CDF_VARPUT, id, temp_id, FINDGEN(2, 3, 10)
;write 10 temperature records.

CDF_VARPUT, id, long_id, [[10.0, 12.0], [8.0, 6.0], [3.0, 2.0]]
;create longitudes.

CDF_VARPUT, id, lat_id, [[40.0, 42.0], [38.0, 34.0],[30.0, 31.0]]
;create latitudes.

CDF_CLOSE, id


CDF_ATTCREATE

The CDF_ATTCREATE function creates a new attribute in the specified Common Data Format file. If successful, the attribute ID is returned.

Calling Sequence

Result = CDF_ATTCREATE(Id, Attribute_Name)

Arguments

Id

The CDF ID of the file for which a new attribute is created, returned from a previous call to CDF_OPEN or CDF_CREATE.

Attribute_Name

A string containing the name of the attribute to be created.

Keywords

GLOBAL_SCOPE

Set this keyword to make the scope of the attribute global. This is the default.

VARIABLE_SCOPE

Set this keyword to indicate that the attribute's scope is per variable.

Example

id = CDF_OPEN('test')	;Create a CDF file.

xx = CDF_ATTCREATE(id, 'Attribute-1', /GLOBAL_SCOPE)

CDF_ATTRENAME, id, 'Attribute-1', 'My Favorite Attribute'

PRINT, CDF_ATTNUM(id, 'My Favorite Attribute')

CDF_CLOSE, id	;Close the CDF file.


CDF_ATTDELETE

The CDF_ATTDELETE procedure deletes an attribute from the specified CDF file. Note that the attribute's entries are also deleted, and that the attributes which numerically follow the deleted attribute within the CDF file are automatically renumbered.

Calling Sequence

CDF_ATTDELETE, Id, Attribute [, EntryNum]

Arguments

ID

The CDF ID of the file containing the Attribute to be deleted, returned from a previoius call to CDF_OPEN or CDF_CREATE.

Attribute

A string containing the name or zero-based attribute number of the attribute to be deleted.

EntryNum

The entry number to delete. If EntryNum is not specified, the entire attribute is deleted. If the attribute is variable in scope, this is either the name or number of the variable the attribute is to be associated with. If the attribute is global in scope, this is the actual gEntry. It is the user's responsibility to keep track of valid gEntry numbers. Normally gEntry numbers will begin with 0 or 1 and will increase up to MAXGENTRY (as reported in the GET_ATTR_INFO structure returned by CDF_CONTROL), but this is not required.

Keywords

ZVARIABLE

If EntryNum is a variable ID (as opposed to a variable name) and the variable is a zVariable, set this flag to indicate that the variable ID is a zVariable ID. The default is to assume that EntryNum is an rVariable ID. Note: the attribute must have a scope of VARIABLE_SCOPE.

Example

cid = CDF_CREATE('DEMOattdelete')

attr1_id = CDF_ATTCREATE(cid, 'GLOBAL_ATTR1', /GLOBAL_SCOPE)

attr2_id = CDF_ATTCREATE(cid, 'GLOBAL_ATTR2', /GLOBAL_SCOPE)

attr3_id = CDF_ATTCREATE(cid, 'VAR_ATTR1', /VARIABLE_SCOPE)

attr4_id = CDF_ATTCREATE(cid, 'VAR_ATTR2', /VARIABLE_SCOPE)

Check the number of attributes:

info = CDF_INQUIRE(cid)

HELP, info.natts

IDL prints:

<Expression>    LONG      =            4

Delete the first and third attributes:

CDF_ATTDELETE, cid, 'GLOBAL_ATTR1'

CDF_ATTDELETE, cid, 1	;The attribute numbers are zero-based and automatically renumbered

Select the new first attribute:

CDF_ATTINQ, cid, 0, name, scope, MaxEntry, MaxZentry

HELP, name, scope

IDL prints:

NAME            STRING    = 'GLOBAL_ATTR2'

SCOPE           STRING    = 'GLOBAL_SCOPE'

CDF_DELETE, cid

See Also

CDF_ATTCREATE, CDF_ATTGET, CDF_ATTEXISTS, CDF_ATTINQ, CDF_ATTPUT, CDF_ATTRENAME


CDF_ATTEXISTS

The CDF_ATTEXISTS function returns TRUE (1) if the specified attribute exists in the specified CDF file, or FALSE (0) if it does not exist. Attributes may be specified by name or number.

Calling Sequence

Result = CDF_ATTEXISTS(Id, Attribute [, EntryNum])

Arguments

Id

The CDF ID of the file containing the Attribute to be checked, returned from a previous call to CDF_OPEN or CDF_CREATE.

Attribute

A string containing the name or zero-based attribute number of the attribute to be checked.

EntryNum

The entry number to confirm. If EntryNum is not specified, the entire file is searched for the specified attribute. If the attribute is variable in scope, this is either the name or number of the variable the attribute is to be associated with. If the attribute is global in scope, this is the actual gEntry. It is the user's responsibility to keep track of valid gEntry numbers. Normally gEntry numbers will begin with 0 or 1 and will increase up to MAXGENTRY (as reported in the GET_ATTR_INFO structure returned by CDF_CONTROL), but this is not required.

Keywords

ZVARIABLE

If EntryNum is a variable ID (as opposed to a variable name) and the variable is a zVariable, set this flag to indicate that the variable ID is a zVariable ID. The default is to assume that EntryNum is an rVariable ID. Note: the attribute must have a scope of VARIABLE_SCOPE.

Example

Create a function to test an attribute's existance and return a string:

FUNCTION exists, cdfid, attname_or_number

IF CDF_ATTEXISTS(cdfid, attname_or_number) THEN $

    RETURN,' Attribute Exists' ELSE $

    RETURN,' Attribute Does Not Exist'

END

Create a CDF with 2 attributes:

cdfid = CDF_CREATE('DEMOattexists')

attr1_id = CDF_ATTCREATE(cdfid, 'GLOBAL_ATT' , /GLOBAL_SCOPE)

attr2_id = CDF_ATTCREATE(cdfid, 'VARIABLE_ATT', /VARIABLE_SCOPE)

Check the existance of the two attributes, plus a third that does not exist:

PRINT, EXISTS(cdfid, attr1_id)

IDL prints:

Attribute Exists

PRINT, EXISTS(cdfid, 1)

IDL prints:

Attribute Exists

PRINT, EXISTS(cdfid, 'BAD ATTR')

IDL prints:

Attribute Does Not Exist

CDF_DELETE, cdfid

See Also

CDF_ATTCREATE, CDF_ATTGET, CDF_ATTDELETE, CDF_ATTINQ, CDF_ATTPUT, CDF_ATTRENAME


CDF_ATTGET

The CDF_ATTGET procedure reads an attribute entry from a Common Data Format file.

Calling Sequence

CDF_ATTGET, Id, Attribute, EntryNum, Value

Arguments

Id

The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE.

Attribute

A string containing the name of the attribute or the attribute number to be written.

EntryNum

The entry number. If the attribute is variable in scope, this is either the name or number of the variable the attribute is to be associated with. If the attribute is global in scope, this is the actual gEntry. It is the user's responsibility to keep track of valid gEntry numbers. Normally gEntry numbers will begin with 0 or 1 and will increase up to MAXGENTRY (as reported in the GET_ATTR_INFO structure returned by CDF_CONTROL), but this is not required.

Value

A named variable in which the value of the attribute is returned.

Keywords

CDF_TYPE

Set this keyword equal to a named variable which will contain the CDF type of the attribute entry, returned as a scalar string. Possible returned values are: CDF_CHAR, CDF_UCHAR, CDF_INT1, CDF_BYTE, CDF_UINT1, CDF_UINT2, CDF_INT2, CDF_UINT4, CDF_INT4, CDF_REAL4, CDF_FLOAT, CDF_REAL8, CDF_DOUBLE, or CDF_EPOCH. If the type cannot be determined, "UNKNOWN" is returned.

Note that, as is true with variable data, attribute  entries of type CDF_INT1, CDF_BYTE, CDF_UINT2, and CDF_UINT4 are  converted into IDL supported datatypes (for example, data of type CDF_UINT2, data of the C-type unsigned short, is converted into IDL's INT, a signed integer. (So, an attribute that is 65535 as a CDF_UINT2 will appear as INT = -1 in IDL). In these cases, pay special attention to the return values.

ZVARIABLE

If EntryNum is a variable ID (as opposed to a variable name) and the variable is a zVariable, set this flag to indicate that the variable ID is a zVariable ID. The default is to assume that EntryNum is an rVariable ID. Note: the attribute must have a scope of VARIABLE_SCOPE.

Example

id = CDF_OPEN('foo')	;Open the CDF file created in the CDF_ATTPUT example.

CDF_ATTGET, id, 'Att2', 'Var2', x

PRINT, X, FORMAT='("[",9(X,F3.1,","),X,F3.1,"]")'

IDL prints:

[ 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0]
;This is the expected output, since this attribute was created with a call to FINDGEN.

CDF_CLOSE, id	;Close the CDF file.


CDF_ATTINQ

The CDF_ATTINQ procedure obtains information about a specified attribute in a Common Data Format file.

Calling Sequence

CDF_ATTINQ, Id, Attribute, Name, Scope, MaxEntry, MaxZEntry

Arguments

Id

The CDF ID of the file containing the desired attribute, returned from a previous call to CDF_OPEN or CDF_CREATE.

Attribute

Either a string containing the name of the attribute or the attribute number to be inquired.

Name

A named variable in which the name of the attribute is returned.

Scope

A named variable in which a string, describing the scope of the attribute, is returned. This string will have one of the following values: "GLOBAL_SCOPE", "VARIABLE_SCOPE", "GLOBAL_SCOPE_ASSUMED", or "VARIABLE_SCOPE_ASSUMED".

MaxEntry

A named variable in which the maximum rVariable entry number for this attribute is returned.

MaxZEntry

A named variable in which the maximum zVariable entry number for this attribute is returned.

Example

cdfid= CDF_OPEN('/cdrom/ozone.8.20.92')

CDF_ATTINQ, cdfid, 0, name, scope, maxentry, maxzentry

PRINT, name, scope, maxentry, maxzentry


CDF_ATTNUM

The CDF_ATTNUM function returns the attribute number associated with a particular attribute in a Common Data Format file.

Calling Sequence

Result = CDF_ATTNUM(Id, Attribute_Name)

Arguments

Id

The CDF ID for the file that contains the desired attribute, returned from a previous call to CDF_OPEN or CDF_CREATE.

Attribute_Name

A string containing the name of the attribute.

Example

See the example for "CDF_ATTPUT" on page 20.


CDF_ATTPUT

The CDF_ATTPUT procedure writes an attribute entry to a Common Data Format file, or attaches an attribute to a CDF variable. If the specified entry already exists, it is overwritten.

Calling Sequence

CDF_ATTPUT, Id, Attribute, EntryNum, Value

Arguments

Id

The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE.

Attribute

A string containing the name of the attribute or the attribute number to be written.

EntryNum

The entry number. If the attribute is variable in scope, this is either the name or number of the variable the attribute is to be associated with. If the attribute is global in scope, this is the actual gEntry. It is the user's responsibility to keep track of valid gEntry numbers. Normally gEntry numbers will begin with 0 or 1 and will increase up to MAXGENTRY (as reported in the GET_ATTR_INFO structure returned by CDF_CONTROL), but this is not required.

Value

The value(s) to be written.

Keywords

ZVARIABLE

If EntryNum is a variable ID (as opposed to a variable name) and the variable is a zVariable, set this flag to indicate that the variable ID is a zVariable ID. The default is to assume that EntryNum is an rVariable ID. Note: the attribute must have a scope of VARIABLE_SCOPE.

Example

Id= CDF_CREATE('foo', /VAX_ENCODING, /HOST_DECODING, $

    /ROW_MAJOR)	;no dimensions.

dummy= CDF_VARCREATE(id, 'Var1', /CDF_INT4, /REC_VARY)

v2= CDF_VARCREATE(id, 'Var2', /CDF_FLOAT, /REC_NOVARY)

dummy= CDF_ATTCREATE(id, 'Title', /VARIABLE)

global_dummy = CDF_ATTCREATE(id,'Date',/GLOBAL)

dummy= CDF_ATTCREATE(id, 'Att2', /VARIABLE)

CDF_ATTPUT, id, 'Title', 'Var1', 'Temperature at surface'

CDF_ATTPUT, id, 'Title', v2, 'Time of recording'

CDF_ATTPUT, id, 'Date',1,'July 4, 1996'

CDF_ATTPUT, id, 'Att2', 'Var2', FINDGEN(10)

Rename the "Att2" attribute to "Attribute2":

CDF_ATTRENAME, Id, 'Att2', 'Attribute2'

Verify the attribute number (zero-based) of Attribute2

PRINT, CDF_ATTNUM(id, 'Attribute2')

IDL prints:

1

CDF_CLOSE, id	;Close the CDF file. This file is used in the example for CDF_ATTGET.

The following example uses the Global attribute "MODS" to keep track of the modification history of a CDF file named mods.cdf.

id = CDF_CREATE('mods.cdf', /CLOBBER)

cid = CDF_ATTCREATE(id, 'MODS', /GLOBAL_SCOPE)

CDF_ATTPUT, id, cid, 0, 'Original Version'

CDF_CLOSE, id

Next, reopen the CDF file and make modifications:

id = CDF_OPEN('mods.cdf')

CDF_CONTROL, id, ATTRIBUTE='MODS', GET_ATTR_INFO=ginfo
;Use CDF_CONTROL to get the MAXGENTRY used.

CDF_ATTPUT, id, cid, ginfo.maxgentry+1,'Second Version'
;Insert the new gEntry at MAXGENTRY+1.

CDF_CLOSE, id

Reopen the CDF file again and make more modifications:

id = CDF_OPEN('mods.cdf')

CDF_CONTROL, id, ATTRIBUTE='MODS', GET_ATTR_INFO=ginfo

CDF_ATTPUT, id, cid, ginfo.maxgentry+1, 'Third Version'

CDF_CLOSE, id

;Reopen the CDF file again and make a modification in the MAXGENTRY + 2 spot (skipping an entry number).

id = CDF_OPEN('mods.cdf')

CDF_CONTROL, id, ATTRIBUTE='MODS', GET_ATTR_INFO=ginfo

CDF_ATTPUT, id, cid, ginfo.maxgentry+2, 'Fourth Version'

Now, Examine the CDF file to review its modification history. Since the gENTRY numbers have a gap in them, we can check each attribute with the CDF_ATTEXISTS function. This is a good idea if you do not know for certain that the attribute entries are serially numbered.

CDF_CONTROL, id, ATTRIBUTE='MODS', GET_ATTR_INFO=ginfo

  FOR I=0, ginfo.maxgentry DO BEGIN

    IF CDF_ATTEXISTS(id, cid, I) THEN BEGIN

      CDF_ATTGET, id, cid, I, gatt

      PRINT, I, gatt, FORMAT='("Attribute: MODS (gENTRY #",i1,") = ",A)'

    ENDIF ELSE BEGIN

      PRINT, I, FORMAT='("Attribute: MODS (gENTRY #",i1,") $

        Does not exist")'

    ENDELSE

  ENDFOR

CDF_CLOSE, id

IDL prints:

Attribute: MODS (gENTRY #0) = Original Version

Attribute: MODS (gENTRY #1) = Second Version

Attribute: MODS (gENTRY #2) = Third Version

Attribute: MODS (gENTRY #3) Does not exist

Attribute: MODS (gENTRY #4) = Fourth Version


CDF_ATTRENAME

The CDF_ATTRENAME procedure is used to rename an existing attribute in a Common Data Format file.

Calling Sequence

CDF_ATTRENAME, Id, OldAttr, NewName

Arguments

Id

The CDF ID of the file containing the desired attribute, returned from a previous call to CDF_OPEN or CDF_CREATE.

OldAttr

A string containing the current name of the attribute or the attribute number to be renamed.

NewName

A string containing the new name for the attribute.

Example

See the example for "CDF_ATTPUT" on page 20.


CDF_CLOSE

The CDF_CLOSE procedure closes the specified Common Data Format file. The CDF's data buffers are flushed, all of the CDF's open files are closed, and the CDF identifier is freed. You must use CDF_CLOSE to close a CDF to guarantee that all modifications you have made are actually written to disk.

Calling Sequence

CDF_CLOSE, Id

Arguments

Id

The CDF ID of the file to be closed, returned from a previous call to CDF_OPEN or CDF_CREATE.

Example

id = CDF_OPEN('open_close.cdf')	;Open a file.

... 	;Other CDF_ commands.

CDF_CLOSE, id	;Close the cdf file.


CDF_CONTROL

The CDF_CONTROL procedure allows you to obtain or set information for a Common Data Format file, its variables, and its attributes.

Calling Sequence

CDF_CONTROL, Id

Arguments

Id

The CDF ID of the file being changed or queried, as retuned from a previous call to CDF_OPEN or CDF_CREATE.

Keywords

ATTRIBUTE

Makes the attribute specified the current attribute. Either an attribute name or an attribute number may be specified.

GET_ATTR_INFO

Set this keyword to a named variable which will contain information about the current attribute. Information is returned in the form of a structure with the following tags:

{ NUMGENTRIES:0L, NUMRENTRIES:0L, NUMZENTRIES:0L,

  MAXGENTRY:0L, MAXRENTRY:0L, MAXZENTRY:0L }

The first three tags contain the number of globals, rVariables, and zVariables associated with the attribute. MAXGENTRY contains the highest index used, and the last two tags contain the highest variable ids used that were used when setting the attribute's value.

Note that an attribute must be set before GET_ATTR_INFO can be used. For example:

CDF_CONTROL, id, ATTRIBUTE='ATT1', GET_ATTR_INFO=X

GET_CACHESIZE

Set this keyword to a named variable which will be set equal to the number of 512-byte cache buffers being used for the current .cdf file. For discussion about using caches with CDF files, see section 2.1.4 ("Caching Scheme") of the version 2.5 CDF User's Guide.

GET_COPYRIGHT

Set this keyword to a named variable which will contain the copyright notice of the CDF library now being used by IDL (as opposed to the library that was used to write the current CDF).

GET_FILENAME

Set this keyword to a named variable which will contain the pathname of the current .cdf file.

GET_FORMAT

Set this keyword to a named variable which will contain a string describing the CDF Format of the current CDF file. Possible formats are SINGLE_FILE and MULTI_FILE, and can only be set with the CDF_CREATE procedure. For example:

id = CDF_CREATE('single', /SINGLE_FILE)

CDF_CONTROL, id, GET_FORMAT = cdfformat

HELP, cdfformat

IDL prints:

CDFFORMAT      STRING    = 'SINGLE_FILE'

GET_NEGTOPOSFP0_MODE

Set this keyword to a named variable which will be set equal to the CDF negative to positive floating point 0.0 (NEGtoPOSfp0) mode. In NEGtoPOSfp0 mode, values equal to -0.0 will be converted to 0.0 whenever encountered. By CDF convention, a returned value of -1 indicates that this feature is enabled, a returned value of zero indicates that this feature is disabled.

GET_NUMATTRS

Set this keyword to a named variable which will contain a two-element array of longs. The first value will contain the number of attributes with global scope, the second value will contain the number of attributes with variable scope. NOTE: attributes with GLOBAL_SCOPE_ASSUMED scope will be included in the global scope count and attributes with VARIABLE_SCOPE_ASSUMED will be included in the count of attributes with variable scope.

Note that you can obtain the total number of attributes using the CDF_INQUIRE routine.

GET_RVAR_CACHESIZE

Set this keyword to a named variable which will be set equal to the number of 512-byte cache buffers being used for the current MULTI_FILE format CDF and the rVariable indicated by the VARIABLE keyword. This keyword should only be used for MULTI_FILE CDF files. For discussion about using caches with CDF files, see section 2.1.4 ("Caching Scheme") of the version 2.5 CDF User's Guide.

GET_READONLY_MODE

Set this keyword to a named variable which will be set equal to the CDF readonly mode. By CDF convention a returned value of -1 indicates that the file is in readonly mode, a returned value of zero indicates that the file is not in readonly mode.

GET_VAR_INFO

Set this keyword to a named variable that will contain information about the current variable. For detailed information about the returned values, consult section 2.3.8 ("RECORDS") of the version 2.5 CDF User's Guide. Information is returned in the form of a structure with the following tags:

{ EXTENDRECS:0L, MAXALLOCREC:0L, MAXREC:0L,
MAXRECS:0L, NINDEXENTRIES:0L, NINDEXRECORDS:0L,
PADVALUE:<as appropriate> }

The EXTENDRECS field will contain the number of records by which the current variable will be extended whenever a new record needs to be added.

The MAXALLOCREC field will contain the maximum record number (zero-based) allocated for the current variable. Records can only be allocated for NOVARY zVariables in SINGLE_FILE format CDFs. When these conditions are not met, the value is set to -1.

The MAXREC field will contain the maximum record number for the current variable. For variables with a record variance of NOVARY this will be at most zero. A value of -1 indicates that no records have been written.

The MAXRECS field will contain the maximum record number (zero-based) of all variables of this type (rVariable or zVariable) in the current CDF. A value of -1 indicates that no records have been written.

The NINDEXENTRIES field will contain the number of index entries for the current variable in the current CDF.  This value is -1 unless the current CDF is of SINGLE_FILE format, and the variable is a zVariable.

The NINDEXRECORDS field will contain the number of index records for the current variable in the current CDF. This value is -1 unless the current CDF is of SINGLE_FILE format, and the variable is a zVariable.

The PADVALUE field will contain the value being used to fill locations that are not explicitly filled by the user. If a PADVALUE is not specified, CDF_CONTROL returns an error.

For example:

fid = CDF_CREATE('test.cdf')

varid = CDF_VARCREATE(fid, 'test')

CDF_CONTROL, fid, GET_VAR_INFO=info, VARIABLE='test'

% CDF_CONTROL: Function completed but:

NO_PADVALUE_SPECIFIED: A pad value has not been specified.

GET_ZMODE

Set this keyword to a named variable which will be set equal the zMode of the current CDF. In a non-zero zMode, CDF rVariables are temporarily replaced with zVariables. The possible returned values are:

•	0 = zMode is off

•	1 = zMode is on in zMode/1, indicating that the dimensionality and variances of the variables will stay the same.

•	2 = zMode is on in zMode/2, indicating that those dimensions with false variances (NOVARY) will be eliminated.

For Information about zModes, consult Section 2.1.2 of the version 2.5 CDF User's Guide.

GET_ZVAR_CACHESIZE

Set this keyword to a named variable which will be set equal to the number of 512-byte cache buffers being used in the current MULTI_FILE format CDF and the  zVariable indicated by the VARIABLE keyword. This keyword should only be used with MULTI_FILE CDF files. For discussion about using caches with CDF files, see section 2.1.4 ("Caching Scheme") of the version 2.5 CDF User's Guide.

SET_CACHESIZE

Set this keyword equal to the desired number of 512-byte cache buffers to used for the current .cdf file. For discussion about using caches with CDF files, see section 2.1.4 ("Caching Scheme") of the version 2.5 CDF User's Guide.

SET_EXTENDRECS

Set this keyword equal to the number of additional physical records that should be added to the current variable whenever it needs to be extended.

SET_INITIALRECS

Set this keyword equal to the number of records that should be initially written to the current variable. Note that this keyword should be set before writing any data to the variable.

SET_NEGTOPOSFP0_MODE

Set this keyword to a non-zero value to put the current CDF file into negative to positive floating point 0.0 (NEGtoPOSfp0) mode. In this mode, values equal to -0.0 will be converted to 0.0 whenever encountered. Setting this keyword equal to 0 (zero) takes the current CDF file out of NEGtoPOSfp0 mode.

SET_PADVALUE

Set this keyword equal to the pad value for the current variable.

SET_READONLY_MODE

Set this keyword to a non-zero value to put the current CDF file into readonly mode. Set this keyword equal to 0 (zero) to take the current CDF file out of readonly mode.

SET_RVAR_CACHESIZE

Set this keyword equal to the desired number of 512-byte cache buffers to used for the rVariable file specified by the VARIABLE keyword. This keyword should only be used with MULTI_FILE CDF files. For discussion about using caches with CDF files, see section 2.1.4 ("Caching Scheme") of the version 2.5 CDF User's Guide.

SET_RVARS_CACHESIZE

Set this keyword equal to the desired number of 512-byte cache buffers to used for all rVariable files in the current CDF file or files. This keyword should only be used with MULTI_FILE CDF files. For discussion about using caches with CDF files, see section 2.1.4 ("Caching Scheme") of the version 2.5 CDF User's Guide.

SET_ZMODE

Set this keyword to change the zMode of the current CDF. In a non-zero zMode, CDF rVariables are temporarily replaced with zVariables. Set this keyword to one (1) to change to zMode/1, in which the dimensionality and variances of the variables stay the same. Set this keyword to two (2) to change to zMode/2, in which those dimensions with false variances (NOVARY) are eliminated. For Information about zModes, consult Section 2.1.2 of the version 2.5 CDF User's Guide.

SET_ZVAR_CACHESIZE

Set this keyword equal to the desired number of 512-byte cache buffers to used for the zVariable's file specified by the VARIABLE keyword. This keyword should only be used with MULTI_FILE CDF files. For discussion about using caches with CDF files, see section 2.1.4 ("Caching Scheme") of the version 2.5 CDF User's Guide.

SET_ZVARS_CACHESIZE

Set this keyword equal to the desired number of 512-byte cache buffers to used for all zVariable files in the current CDF. This keyword should only be used with MULTI_FILE CDF files. For discussion about using caches with CDF files, see section 2.1.4 ("Caching Scheme" of the version 2.5 CDF User's Guide.

VARIABLE

Set this keyword to a name or index to set the current variable. For example,

CDF_CONTROL, id, VAR='MyData', SET_INITIALRECS=20

specifies that the variable MyData should have 20 records written to it initially.

Note that if VARIABLE is set to the index of a zVariable, the ZVARIABLE keyword must also be set. If ZVARIABLE is not set, the variable is assumed to be an rVariable.

ZVARIABLE

Set this keyword to TRUE if the current variable is a zVariable and is referred to by index. For example:

CDF_CONTROL, id, VARIABLE=0, /ZVARIABLE, GET_VAR_INFO=V

See Also

CDF_CREATE, CDF_INQUIRE


CDF_CREATE

The CDF_CREATE function creates a new Common Data Format file with the given filename and dimensions. If successful, this function returns the CDF ID for the new file.

Note that when you create a CDF file, you must specify both encoding and decoding methods. Encoding specifies the method used to write data to the CDF file. Decoding specifies the method used to retrieve data from the CDF file and pass it to an application (IDL, for example). Encoding and decoding methods are specified by setting the XXX_ENCODING and XXX_DECODING keywords to CDF_CREATE. If no decoding method is specified, the decoding method is set to be the same as the encoding method.

All CDF encoding and decodings can be written or read on all platforms, but matching the encoding with the architecture used provides the best performance. If you work in a single-platform environment most of the time, select HOST_ENCODING for maximum performance. If you know that the CDF file will be transported to a computer using another architecture, specify the encoding for the target architecture or specify NETWORK_ENCODING (the default). Specifying the target architecture provides maximum performance on that architecture; specifying NETWORK_ENCODING provides maximum flexibility.

For more discussion on CDF encoding/decoding methods and combinations, see sections 2.2.7 ("Encoding") and 2.2.8 ("Decoding") of the version 2.5 CDF User's Guide.

Calling Sequence

Result = CDF_CREATE(Filename, [Dimensions])

Arguments

Filename

A scalar string containing the name of the file to be created. Note that if the desired filename has a .cdf ending, you can omit the extension and specify just the first part of the filename. For example, specifying "mydata" would open the file mydata.cdf.

Dimensions

A vector of values specifying size of each rVariable dimension. If no dimensions are specified, then the file will contain a single scalar per record (i.e., a 0-dimensional CDF).

Keywords

ALPHAOSF1_ENCODING
ALPHAOSF1_DECODING

Set this keyword to indicate DEC ALPHA/OSF1 data encoding/decoding.

ALPHAVMSD_ENCODING
ALPHAVMSD_DECODING

Set this keyword to indicate DEC ALPHA/VMS data encoding/decoding using Digital's D_FLOAT representation.

ALPHAVMSG_ENCODING
ALPHAVMSG_DECODING

Set this keyword to indicate DEC ALPHA/VMS data encoding/decoding using Digital's G_FLOAT representation.

CLOBBER

Set this keyword to erase the existing file (if the file already exists) before creating the new version. Note that if the existing file has been corrupted, the CLOBBER operation may fail, causing IDL to display an error message. In this case you must manually delete the existing file from outside IDL.

COL_MAJOR

Set this keyword to specify column major (IDL-like) array ordering for variable storage.

HOST_ENCODING
HOST_DECODING

Set this keyword to select that the file will use native data encoding/decoding.

HP_ENCODING
HP_DECODING

Set this keyword to select HP 9000 data encoding/decoding.

IBMRS_ENCODING
IBMRS_DECODING

Set this keyword to select IBM RS/6000 series data encoding/decoding.

IBMPC_ENCODING
IBMPC_DECODING

Set this keyword to select IBM PC data encoding/decoding.

SGI_ENCODING
SGI_DECODING

Set this keyword to select SGI (MIPSEB) data encoding/decoding (Silicon Graphics Iris and Power series).

DECSTATION_ENCODING
DECSTATION_DECODING

Set this keyword to select Decstation (MIPSEL) data encoding/decoding.

MAC_ENCODING
MAC_DECODING

Set this keyword to select Macintosh data encoding/decoding.

MULTI_FILE

Set this keyword to cause all CDF control information and attribute entry data to be placed in one .cdf file, with a separate file created for each defined variable. If the variable in an rVariable, then the variable files will have extensions of .v0, .v1, etc.; zVariables will be stored in files with extensions of .z0, .z1, etc. This is the default format, and is usually more efficient than the SINGLE_FILE format. See section 2.2.7 ("Format") in the version 2.5 CDF User's Guide for more information. If both SINGLE_FILE and MULTI_FILE are set the file will be created in the MULTI_FILE format.

MULTI_FILE Example:

id=CDF_CREATE('multi', /MULTI_FILE)

CDF_CONTROL, id, GET_FORMAT=cdf_format

HELP, cdf_format

IDL prints:

CDF_FORMAT      STRING    = 'MULTI_FILE'

NETWORK_ENCODING
NETWORK_DECODING

Set this keyword to select network-transportable data encoding/decoding (XDR). This is the default method.

NEXT_ENCODING
NEXT_DECODING

Set this keyword to select NeXT data encoding/decoding.

ROW_MAJOR

Set this keyword to specify row major (C-like) array ordering for variable storage. This is the default.

SINGLE_FILE

Set this keyword to cause all CDF information (control information, attribute entry data, variable data, etc.) to be written to a single .cdf file. The default is to use the MULTI_FILE format where a separate file is created for each variable. See section 2.2.7 ("Format") of the version 2.5 CDF User's Guide for more information.

SUN_ENCODING
SUN_DECODING

Set this keyword to select SUN data encoding/decoding.

VAX_ENCODING
VAX_DECODING

Set this keyword to select VAX data encoding/decoding.

Example

Use the following command to create a 10-element by 20-element CDF using network encoding and Sun decoding:

id = CDF_CREATE('cdf_create.cdf', [10,20], /NETWORK_ENCODING, $

    /SUN_DECODING)

.....	;other cdf commands.

CDF_CLOSE, id	;close the file.

Now suppose that we decide to use HP_DECODING instead. We can use the CLOBBER keyword to delete the existing file when creating the new file:

id = CDF_CREATE('cdf_create.cdf', [10,20], /NETWORK_ENCODING, $

    /HP_DECODING, /CLOBBER)

.....	;other cdf commands.

CDF_CLOSE, id	;close the file.

The new file is written over the existing file. Use the following command to delete the file:

CDF_DELETE, id


CDF_DELETE

The CDF_DELETE procedure deletes the specified Common Data Format file. Files deleted include the original .cdf file and the .v0, .v1, etc. files if they exist.

Calling Sequence

CDF_DELETE, Id

Arguments

Id

The CDF ID of the file to be deleted, returned from a previous call to CDF_OPEN or CDF_CREATE.

Example

id = CDF_OPEN('open_close.cdf')	;Open a file.

... 	;Other CDF_ commands.

CDF_DELETE, id	;Close and Delete the cdf file.


CDF_DOC

The CDF_DOC procedure retrieves general documentation information about a Common Data Format file.

Calling Sequence

CDF_DOC, Id, Version, Release, Copyright

Arguments

Id

A CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE.

Version

A named variable in which the version number of the CDF library that created the CDF is returned.

Release

A named variable in which the release number of the CDF library that created the CDF is returned.

Copyright

A named variable in which the copyright notice of the CDF library that created the CDF is returned.

Keywords

INCREMENT

Set this keyword to a named variable which will contain the increment of the CDF library that created the specified CDF file.

Example

id=CDF_CREATE('VersionCheck')	;Create a CDF file.

CDF_DOC, id, vers, rel, copy, INCREMENT=incr

PRINT,'File Written Using CDF', vers, rel, incr, $

    FORMAT='(A,I1,".",I1,"r",I2)'

IDL prints:

File Written Using CDF2.5r18

CDF_CLOSE, id	;Close the CDF file.


CDF_ENCODE_EPOCH

The CDF_ENCODE_EPOCH function encodes a CDF_EPOCH variable into a string.  Four different string formats are available. The default (EPOCH=0) is the standard CDF format, which may be parsed by the CDF_PARSED_EPOCH function or broken down with the CDF_EPOCH procedure.

Calling Sequence

Result = CDF_ENCODE_EPOCH(Epoch)

Arguments

Epoch

The double-precision CDF_EPOCH value to be encoded. For more information about CDF_EPOCH values, see section 2.2.10 ("Data Types") of the version 2.5 CDF User's Guide.

Keyword

EPOCH

Set this keyword to indicate the type of output desired,

Set EPOCH=0 to select output of the standard type, which is described in CDF_PARSE_EPOCH.

Set EPOCH=1 to select output of the type yyyymodd.ttttttt where: yyyy is the year, mo is the month (1-12), dd is the day of the month (1-31), and ttttttt is the fraction of the day (e.g. 2500000 at 6 am).

Set EPOCH=2 to select output of the type yyyymoddhhmmss where: yyyy is the year, mo is the month (1-12), dd is the day of the month (1-31), hh is the hour (0-23), mm is the minute (0-59), and ss is the second (0-59).

Set EPOCH=3 to select output of the type yyyy-mo-ddThh:mm:ss.cccZ where: yyyy is the year, mo is the month (1-12), dd is the day of the month (1-31), hh is the hour (0-23), mm is the minute (0-59), ss is the second (0-59), and ccc is the millisecond (0-999). The characters T and Z are the CDF_EPOCH type 3 place holders.

Example

epoch_string = '04-Dec-1995 20:19:18.176'

epoch = CDF_PARSE_EPOCH(epoch_string)

HELP, epoch_string, epoch

IDL prints:

EPOCH_STRING    STRING    = '04-Dec-1995 20:19:18.176'

EPOCH           DOUBLE    =    6.2985328e+13

Create encode strings:

encode0 = CDF_ENCODE_EPOCH(test_epoch, EPOCH=0)

encode1 = CDF_ENCODE_EPOCH(test_epoch, EPOCH=1)

encode2 = CDF_ENCODE_EPOCH(test_epoch, EPOCH=2)

encode3 = CDF_ENCODE_EPOCH(test_epoch, EPOCH=3)

Compare encoding formats:

HELP, encode0, encode1, encode2, encode3

IDL prints:

ENCODE0       STRING    = '04-Dec-1995 20:19:18.176'

ENCODE1       STRING    = '19951204.8467381'

ENCODE2       STRING    = '19951204201918'

ENCODE3       STRING    = '1995-12-04T20:19:18.176Z'

See Also

CDF_EPOCH, CDF_PARSE_EPOCH


CDF_EPOCH

The CDF_EPOCH procedure computes or breaks down CDF_EPOCH values in a Common Data Format file. When computing an epoch, any missing value is considered to be set to zero.

Calling Sequence

CDF_EPOCH, Epoch, Year [, Month, Day, Hour, Minute, Second, Milli]

Arguments

Epoch

The Epoch value to be broken down, or a named variable into which the computed epoch will be placed.

Year

The year (e.g., 1992) or a named variable.

Month

The month (1-12) or a named variable.

Day

The day (1-31) or a named variable.

Hour

The hour (0-23) or a named variable.

Minute

The minute (0-59) or a named variable.

Second

The second (0-59) or a named variable.

Milli

The millisecond (0-999) or a named variable.

Keywords

BREAKDOWN_EPOCH

If this keyword is set, Epoch is a value which will broken down and the resulting Year, Month, Day, etc. are returned in the remaining parameters which must be named variables.

COMPUTE_EPOCH

If this keyword is set, Epoch is a named variable into which the epoch is placed and the other parameters are values which will be used to compute the epoch.

Example

CDF_EPOCH, MergeDate, 1992, 9, 20, 3, /COMPUTE_EPOCH

CDF_EPOCH, 4.7107656e13, yr, mo, dy, hr, mn, sc, milli, /BREAK


CDF_ERROR

The CDF_ERROR function returns a string containing a short explanation of a given status code returned from a Common Data Format file.

Calling Sequence

Result = CDF_ERROR(Status)

Arguments

Status

The status code to be explained.


CDF_EXISTS

The CDF_EXISTS function returns true if the Common Data Format (CDF) scientific data format library is supported on the current IDL platform.

This routine is written in the IDL language. Its source code can be found in the file cdf_exists.pro in the lib subdirectory of the IDL distribution.

Calling Sequence

Result = CDF_EXISTS()

Example

The following IDL command prints an error message if the CDF library is not available:

IF CDF_EXISTS() EQ 0 THEN PRINT, 'CDF not supported.'


CDF_INQUIRE

The CDF_INQUIRE function returns global information about the Common Data Format file. This information is returned in a structure of the form:

{ NDIMS:0L, DECODING:"", ENCODING:"", MAJORITY:"", MAXREC:0L, $

  NVARS:0L, NZVARS:0L, NATTS:0L, DIM:LONARR(NDIMS) }

The tags of this structure are described below.

Calling Sequence

Result = CDF_INQUIRE(Id)

Arguments

Id

A CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE.

 Explanation of the Structure Tags

NDIMS

The longword integer specifying the number of dimensions in the rVariables in the current CDF.

DECODING

A string describing the decoding type set in the CDF file. For example, 'MAC_DECODING' or 'ALPHAVMSD_ENCODING'.

ENCODING

A string describing the type of encoding used in the CDF file. For example, 'NETWORK_ENCODING' or 'VAX_ENCODING'.

MAJORITY

A string describing the majority used in the CDF file. The majority will be either row ('ROW_MAJOR') or column ('COL_MAJOR').

MAXREC

A longword integer specifying the highest record number written in the rVariables in the current CDF. The MAXREC field will contain the value -1 if no rVariables have yet been written to the CDF.

NVARS

A longword integer specifying the number of rVariables (regular variables) in the CDF.

NZVARS

A longword integer specifying the number of zVariables in the CDF.

NATTS

A longword integer specifying the number of attributes in the CDF. Note that the number returned in this field includes both global and variable attributes. You can use the GET_NUMATTR keyword to the CDF_CONTROL routine to determine the number of each.

DIM

A vector where each element contains the corresponding dimension size for the rVariables in the current CDF. For 0-dimensional CDF's, this argument contains a single element (a zero).

Example

cdfid = CDF_CREATE('CDFinquire', /HP_ENCODING, /MAC_DECODING)

attr1_id = CDF_ATTCREATE(cdfid, 'GLOBAL_ATT', /GLOBAL_SCOPE)

attr2_id = CDF_ATTCREATE(cdfid,'VARIABLE_ATT', /VARIABLE_SCOPE)

CDF_CONTROL, cdfid, GET_NUMATTRS = num_attrs

PRINT, 'This CDF has ', num_attrs(0), 'Global attribute(s) and ',$

    num_attrs(1), 'Variable attribute(s).', FORMAT='(A,I2,A,I2,A)'

IDL prints:

This CDF has  1 Global attribute(s) and  1 Variable attribute(s).

inquire = CDF_INQUIRE(cdfid)

HELP, inquire, /STRUCT

IDL prints:

** Structure <4003e0c0>, 9 tags, length=48, refs=1:

   NDIMS           LONG                 0

   DECODING        STRING    'MAC_DECODING'

   ENCODING        STRING    'HP_ENCODING'

   MAJORITY        STRING    'ROW_MAJOR'

   MAXREC          LONG                -1

   NVARS           LONG                 0

   NZVARS          LONG                 0

   NATTS           LONG                 2

   DIM             LONG      Array(1)

CDF_DELETE, cdfid	;Delete the CDF file.

See Also

CDF_CONTROL, CDF_DOC, CDF_LIB_INFO


CDF_LIB_INFO

The CDF_LIB_INFO procedure returns information about the CDF Library being used by this version of IDL. Information about the version of CDF used to create a particular CDF file can be obtained through CDF_DOC.

Calling Sequence

CDF_LIB_INFO

Keywords

COPYRIGHT

A named variable in which the copyright notice of the CDF library that this version of IDL is using will  be returned.

INCREMENT

A named variable in which the incremental number of the CDF library that this version of IDL is using will be returned.

RELEASE

A named variable in which the release number of the CDF library that this version of IDL is using will be returned.

SUBINCREMENT

A named variable in which the subincremental character of the CDF library that this version of IDL is  using will be returned.

VERSION

A named variable in which the version number of the CDF library that this version of IDL is using will be returned.

Example

CDF_LIB_INFO, VERSION=V, RELEASE=R, COPYRIGHT=C, $

    INCREMENT=I

PRINT, 'IDL ', !version.release, 'uses CDF Library ', $

    V, R, I, FORMAT='(A,A,A,I1,".",I1,".",I2,A)'

PRINT, C

IDL prints:

IDL 5.0 uses CDF Library 2.5.19

NSSDC Common Data Format (CDF)

(C) Copyright 1990-1995 NASA/GSFC

National Space Science Data Center

NASA/Goddard Space Flight Center

Greenbelt, Maryland 20771 USA

(DECnet   -- NCF::CDFSUPPORT)

(Internet -- CDFSUPPORT@NSSDCA.GSFC.NASA.GOV)

See Also

CDF_DOC


CDF_OPEN

The CDF_OPEN function opens an existing Common Data Format file. If successful, the CDF ID for the file is returned.

Calling Sequence

Result = CDF_OPEN(Filename)

Arguments

Filename

A scalar string containing the name of the file to be created. Note that if the desired filename has a .cdf ending, you can omit the extension and specify just the first part of the filename. For example, specifying "mydata" would open the file mydata.cdf.

Example

id = CDF_OPEN('open_close.cdf')	;Open a file.

... 	;Other CDF_ commands.

CDF_CLOSE, id	;Close the cdf file.


CDF_PARSE_EPOCH

The CDF_PARSE_EPOCH function parses a properly formatted input string into a double precision value properly formatted for use as a CDF_EPOCH variable.  CDF_EPOCH variables may be unparsed into a variety of formats using the CDF_ENCODE_EPOCH function.

Calling Sequence

Result = CDF_PARSE_EPOCH(Epoch_string)

Arguments

Epoch_string

A formatted string that will be parsed into a double precision value suitable to be used as a  CDF_EPOCH value. The format expected by CDF_PARSE_EPOCH (the CDF standard) is dd-mmm-yyyy hh:mm:ss.ccc where:

•	dd is the day of the month, 1-31.

•	mmm is the month, Jan, Feb, Mar, Apr,May, Jun, Jul, Aug, Sep, Oct, Nov, or Dec.

•	yyyy is the year, A.D.

•	hh is the hour, 0-23.

•	mm is the minute, 0-59.

•	ss is the second, 0-59, and

•	ccc is the millisecond, 0-999.

For more information about CDF_EPOCH values, see section 2.2.10 ("Data Types") of the version 2.5 CDF User's Guide.

Example

test_string = '04-Dec-1995 20:19:18.176'

test_epoch = CDF_PARSE_EPOCH(test_string)

HELP, test_string, test_epoch

IDL prints:

TEST_STRING     STRING    = '04-Dec-1995 20:19:18.176'

TEST_EPOCH      DOUBLE    =    6.2985328e+13

PRINT, CDF_ENCODE_EPOCH(test_epoch, EPOCH=0)

IDL prints:

04-Dec-1995 20:19:18.176

See Also

CDF_ENCODE_EPOCH, CDF_EPOCH


CDF_VARCREATE

The CDF_VARCREATE function creates a new variable in a Common Data Format file.

Calling Sequence

Result = CDF_VARCREATE(Id, Name [, DimVary])

Arguments

Id

The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE.

Name

A string containing the name of the variable to be created.

DimVary

A one-dimensional array containing one element per CDF dimension. If the element is non-zero or the string 'VARY', the variable will have variance in that dimension. If the element is zero or the string 'NOVARY' then the variable will have no variance with that dimension. If the variable is zero-dimensional, this argument may be omitted.

Keywords

You must specify the type variable being created. This is done by setting one of the following keywords:

•	CDF_BYTE	•  CDF_INT4

•	CDF_CHAR	•  CDF_REAL4

•	CDF_DOUBLE	•  CDF_REAL8

•	CDF_EPOCH	•  CDF_UCHAR

•	CDF_FLOAT	•  CDF_UINT1

•	CDF_INT1	•  CDF_UINT2

•	CDF_INT2	•  CDF_UINT4

If no type is specified, CDF_FLOAT is assumed.

Although all CDF variable types are supported within the file, IDL has full support only for the following CDF data types: CDF_DOUBLE, CDF_EPOCH, CDF_FLOAT, CDF_INT2, CDF_INT4, CDF_REAL4, CDF_REAL8, and CDF_UCHAR.

ALLOCATERECS

Set this keyword equal to the desired number of pre-allocated records for this variable in a SINGLE_FILE CDF file. Pre-allocating records ensure that variable data is stored contiguously in the CDF file. For discussion about allocating records, see section 2.3.8 ("Records") of the version 2.5 CDF User's Guide.

DIMENSIONS

Set this keyword to create a new zVariable with the specified dimensions. For example:

id = CDF_CREATE("cdffile.cdf", [100] )

zid = CDF_VARCREATE(id, "Zvar", [1,1,1], DIM=[10,20,30])

NUMELEM

The number of elements of the data type at each variable value. This keyword only has meaning for string data types (CDF_CHAR, CDF_UCHAR). This is the number of characters in the string. The default is 1.

REC_NOVARY

If this keyword is set, all records will contain the same information.

REC_VARY

If this keyword is set, all records will contain unique data. This is the default.

ZVARIABLE

A variable is assumed to be a zVariable if its dimensions are specified by the DIMENSIONS keyword. Set this keyword to create a zero-dimensional zVariable.

For example:

id = CDF_CREATE("cdffile.cdf", [100] )

zid = CDF_VARCREATE(id, "Zvar", /ZVARIABLE)

Example

Create a CDF file to record the data retrieved from an array of temperature and salinity detectors. In this example, there is a 3 x 4 array of detectors at two depths, 10.0 meters and 20.2 meters:

id = CDF_CREATE("temp_salinity.cdf", [3,4], /NETWORK_ENCODING, $

    /SUN_DECODING, /CLOBBER)

temp_id =CDF_VARCREATE(id, "Temperature", ['Vary', 'Vary'], $

    /REC_VARY,/CDF_FLOAT)

depth_id = CDF_VARCREATE(id, "Depth", [0,0], /REC_VARY, /CDF_FLOAT)

sal_id = CDF_VARCREATE(id, "Salinity", [1,1], /REC_VARY, $

    /CDF_DOUBLE)

;Create and fill the UNITS attribute:

units_att = CDF_ATTCREATE(id, 'UNITS', /VARIABLE)

CDF_ATTPUT, id, 'UNITS', 'Depth', 'Meters'

CDF_ATTPUT, id, 'UNITS', temp_id, 'Kelvin'

CDF_ATTPUT, id, units_att, sal_id, 'Percent'

;Create and write some fictitous data:

data1 = 20.0 + FINDGEN(3,4)

CDF_VARPUT, id, varid, data1

CDF_VARPUT, id, depth_id, '10.0'	;IDL will handle the type conversion, CDF will set all values of this record to a depth of 10.0.

CDF_VARPUT, id, depth_id, 20.2,rec_start=1
;Set the second depth.

CDF_VARPUT, id, sal_id, DINDGEN(3,4)/10.0
;Make more fictitous data.

;Demostrate the non-variance of depth by retrieving the values. On the first pass, use CDF_VARGET1 to retrieve single values:

CDF_VARGET1, id, depth_id, pth_0	;Get single values.

CDF_VARGET1, id, depth_id, depth_1, REC_START=1
;Get single values.

HELP, depth_0, depth_1

IDL prints:

DEPTH_0         FLOAT     =       10.0000

DEPTH_1         FLOAT     =       20.2000

Now retrieve the full depth records:

CDF_VARGET, id, depth_id, depth, REC_COUNT=2

;Examine the depth variable

HELP, depth

IDL prints:

DEPTH           FLOAT     = Array(3, 4, 2)

PRINT, depth

IDL prints:

10.0000      10.0000      10.0000

10.0000      10.0000      10.0000

10.0000      10.0000      10.0000

10.0000      10.0000      10.0000

20.2000      20.2000      20.2000

20.2000      20.2000      20.2000

20.2000      20.2000      20.2000

20.2000      20.2000      20.2000

The following example creates a variable, setting the data type from a string variable, which could have been returned by the DATATYPE keyword to a CDF_VARINQ call.

VARTYPE = 'CDF_FLOAT'

Use the _EXTRA keyword and the CREATE_STRUCT function to make the appropriate keyword.

VarId = CDF_VARCREATE(Id, 'Pressure', [1,1], $

    NUMELEM=2, _EXTRA=CREATE_STRUCT(VARTYPE,1))

CDF_CLOSE, id	;Close the CDF file.

CDF_VARDELETE

The CDF_VARDELETE procedure deletes a variable from a SINGLE_FILE CDF file. Note that the variable's entries are also deleted, and that the variables which numerically follow the deleted variable within the CDF file are automatically renumbered. CDF rVariables and zVariables are counted separately within CDF files.  Attempting to delete a variable from a MULTI_FILE format CDF file will result in an warning message.

Calling Sequence

CDF_VARDELETE,Id,Variable

Arguments

ID

The CDF ID of the file containing the Variable to be deleted, returned from a previous call to CDF_OPEN or CDF_CREATE.

VARIABLE

A string containing the name of the variable to be deleted OR the variable number to be deleted.  Variable numbers are 0-based in IDL. zVariables and rVariables are counted separately in CDF files.

Keywords

ZVARIABLE

Set this keyword if the Variable is a zVariable and was passed by number.  The default is to assume that Variable is an rVariable.

Example

cid = CDF_CREATE('DEMOvardelete',/SINGLE_FILE)

Create 3 zVariables and 1 rVariable:

var1_id = CDF_VARCREATE(cid, 'rVAR1', /CDF_FLOAT)

var2_id = CDF_VARCREATE(cid, 'zVAR1', /CDF_INT4, /REC_NOVARY, $

                        /ZVARIABLE)

var3_id = CDF_VARCREATE(cid, 'zVAR2', /CDF_CHAR, [2,10], $

                        NUMELEM=10, DIM=[5,5])

var4_id = CDF_VARCREATE(cid, 'zVAR3' ,/CDF_REAL8, /ZVARIABLE)

Check the number of variables:

info = CDF_INQUIRE(cid)

HELP, info.nzvars, info.nvars

IDL prints:

<Expression>    LONG      =            3

<Expression>    LONG      =            1

Delete the first and third zvariables:

CDF_VARDELETE, cid, 'zVAR1', /ZVARIABLE

CDF_VARDELETE, cid, 1, /ZVARIABLE

Caution	Remember the variable numbers are zero-based and are automatically renumbered.

info = CDF_INQUIRE(cid)

HELP, info.nzvars, info.nvars

IDL prints:

<Expression>    LONG      =            1

<Expression>    LONG      =            1

varinfo = CDF_VARINQ(cid, 0, /ZVARIABLE)
;check on zVAR2

HELP, varinfo, /STRUCTURE

IDL prints:

** Structure <400a3b40>, 8 tags, length=48, refs=1:

   IS_ZVAR         INT              1

   NAME            STRING    'zVAR2'

   DATATYPE        STRING    'CDF_CHAR'

   NUMELEM         LONG                10

   RECVAR          STRING    'VARY'

   DIMVAR          BYTE      Array(2)

   ALLOCATERECS    LONG      Array(2)

   DIM             LONG      Array(1)

CDF_DELETE, cid

See Also

CDF_ATTDELETE, CDF_CONTROL, CDF_VARCREATE, CDF_VARINQ


CDF_VARGET

The CDF_VARGET procedure reads multiple values from a Common Data Format file variable. By default, all elements of a record are read. If INTERVAL, and/or OFFSET are specified but no COUNT is specified, CDF_VARGET attempts to get as many elements of each record as possible.

Calling Sequence

CDF_VARGET, Id, Variable, Value

Arguments

Id

The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE

Variable

A string containing the name of the variable or the variable number being read.

Value

A named variable in which the values of the variable are returned.

Keywords

COUNT

An optional vector containing the counts to be used in reading Value. The default is to read all elements in each record, taking into account INTERVAL and OFFSET.

INTERVAL

A vector specifying the interval between values in each dimension. The default value is 1 for each dimension.

OFFSET

A vector specifying the array indices within the specified record(s) at which to begin writing. OFFSET is a 1-dimensional array containing one element per CDF dimension. The default value is zero for each dimension.

REC_COUNT

The number of records to read. The default is 1.

REC_INTERVAL

The interval between records when reading multiple records. The default value is 1.

REC_START

The record number at which to start reading. The default is 0.

STRING

Set this keyword to return CDF_CHAR and CDF_UCHAR data from the CDF file into Value as string data rather than byte data. This keyword is ignored if the data in the CDF file is not of type CDF_CHAR or CDF_UCHAR.

ZVARIABLE

If Variable is a variable ID (as opposed to a variable name) and the variable is a zVariable, set this flag to indicate that the variable ID is a zVariable ID. The default is to assume that Variable is an rVariable ID.

Example

Create a CDF file,  and make a few variables:

id = CDF_CREATE('DEMOvargets')

vid1 = CDF_VARCREATE(id, 'VAR1', /CDF_CHAR, NUMELEM=15)

vid2=CDF_VARCREATE(id, 'VAR2', /CDF_UCHAR, NUMELEM=10)

CDF_VARPUT, id, vid1, BINDGEN(15, 2)+55, COUNT=2

CDF_VARPUT, id, vid2, ['IDLandCDF ', 'AreWayCool']

Retreive the CDF_CHAR array as byte data:

CDF_VARGET, id, 'VAR1', var1_byte, REC_COUNT=2

IDL prints:

% CDF_VARGET: Warning: converting data to unsigned bytes

This warning message indicates that the data was stored in the CDF file with type CDF_CHAR (signed 1-byte characters),  but was retreived by IDL with type BYTE (unsigned byte).  To turn this warning message off,  set !QUIET=1.

HELP, var1_byte

IDL prints:

VAR1_BYTE       BYTE      = Array(15,  2)

Retreive the CDF_CHAR array as string data:

CDF_VARGET, id, 'VAR1', var1_string, REC_COUNT=2, /STRING

HELP, var1_string

IDL prints:

VAR1_STRING     STRING    = Array(2)

For demonstration purposes, use the "VAR2" variable number to access "VAR2" for the duration of this example:

var2num = CDF_VARNUM(id, 'VAR2")

HELP, var2num

IDL prints:

VAR2NUM         LONG      =            1

Rename "VAR2" to "VAR_STRING_2":

CDF_VARRENAME, id, var2num, 'VAR_STRING_2'

Examine VAR_STRING_2 with CDF_VARINQ:

VAR2_INQ = CDF_VARINQ(id, var2num)

HELP, VAR2_INQ, /STRUCTURE

IDL prints:

** Structure <400b1600>, 6 tags, length=33, refs=1:

   IS_ZVAR         INT                    0

   NAME            STRING     `VAR_STRING_2'

   DATATYPE        STRING        `CDF_UCHAR'

   NUMELEM         LONG                   10

   RECVAR          STRING             `VARY'

   DIMVAR          BYTE                    0

Read in and print out VAR_STRING_2:

CDF_VARGET, id, var2num, var2_string, /STRING, REC_COUNT=2

PRINT, var2_string

IDL prints:

IDLandCDF  AreWayCool

CDF_DELETE, id	;Delete the CDF file


CDF_VARGET1

The CDF_VARGET1 procedure reads one value from a Common Data Format file variable.

Calling Sequence

CDF_VARGET1, Id, Variable, Value

Arguments

Id

The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE.

Variable

A string containing the name of the variable or the variable number to be read.

Value

A named variable in which the value of the variable is returned.

Keywords

OFFSET

A vector specifying the array indices within the specified record(s) at which to begin reading. OFFSET is a 1-dimensional array containing one element per CDF dimension. The default value is 0 for each dimension.

REC_START

The record number at which to start reading. The default is 0.

STRING

Set this keyword to return CDF_CHAR and CDF_UCHAR data from the CDF file into Value as string data rather than byte data. This keyword is ignored if the data in the CDF file is not of type CDF_CHAR or CDF_UCHAR.

ZVARIABLE

If Variable is a variable ID (as opposed to a variable name) and the variable is a zVariable, set this flag to indicate that the variable ID is a zVariable ID. The default is to assume that Variable is an rVariable ID.

Example

See the example for "CDF_VARCREATE" on page 50.


CDF_VARINQ

The CDF_VARINQ function returns a structure containing information about the specified variable in a Common Data Format file. This structure has the form:

{ IS_ZVAR:0, NAME:"", DATATYPE:"", NUMELEM:0L, $

  RECVAR:"", DIMVAR:BYTARR(...) [, DIM:LONARR(...)]}

Note: the DIM field is included in the structure only if IS_ZVAR is one. This structure's tags are explained below.

Calling Sequence

Result = CDF_VARINQ(Id, Variable)

Arguments

Id

The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE.

Variable

A string containing the name of the variable or the variable number being inquired.

Keywords

ZVARIABLE

If Variable is a variable ID (as opposed to a variable name) and the variable is a zVariable, set this flag to indicate that the variable ID is a zVariable ID. The default is to assume that Variable is an rVariable ID.

Explanation of the Structure Tags

IS_ZVAR

This field will contain a 1 if the variable is a zVariable or a 0 if it is an rVariable.

NAME

The name of the variable.

DATATYPE

A string describing the data type of the variable. The string has the form 'CDF_XXX' where XXX is FLOAT, DOUBLE, EPOCH, UCHAR, etc.

NUMELEM

The number of elements of the data type at each variable value. This is always 1 except in the case of string type variables (CDF_CHAR, CDF_UCHAR).

RECVAR

A string describing the record variance of the variable. This is either the string 'VARY' or 'NOVARY'.

DIMVAR

An array of bytes. The value of each element is zero if there is no variance with that dimension and one if there is variance. For zero-dimensional CDFs, DIMVAR will have one element whose value is zero.

DIM

An array of longs. The value of each element corresponds to the dimension of the variable. This field is only included in the structure if the variable is a zVariable.

Example

See the example for "CDF_VARGET" on page 56.


CDF_VARNUM

The CDF_VARNUM function returns the variable number associated with a given variable name in a Common Data Format file. If the specified variable cannot be found in the CDF file, CDF_VARNUM returns the scalar -1.

Calling Sequence

Result = CDF_VARNUM(Id, VarName [, IsZVar])

Arguments

Id

The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE.

VarName

A string containing the name of the variable.

IsZVar

A named variable into which CDF_VARNUM will place a 1 to indicate that the referenced variable is a zVariable or a 0 to indicate that it is an rVariable.

Example

See the example for "CDF_VARGET" on page 56.


CDF_VARPUT

The CDF_VARPUT procedure writes a value to a variable in a Common Data Format file. This function provides equivalent functionality to the C routines CDFvarPut and CDFvarHyperPut.

Calling Sequence

CDF_VARPUT, Id, Variable, Value

Arguments

Id

The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE.

Variable

A string containing the name of the variable or the variable number being written.

Value

The value to write. If the value has 1 more dimension than the CDF, multiple records will be written.

Keywords

COUNT

An optional vector containing the counts to be used in writing Value. Note that counts do not have to match the dimensions of Value. The default count is to use the dimensions of Value.

INTERVAL

A vector specifying the interval between values in each dimension. The default value is 1 in each dimension.

OFFSET

A vector specifying the array indices within the specified record(s) at which to begin writing. OFFSET is a 1-dimensional array containing one element per CDF dimension. The default value is zero in each dimension.

REC_INTERVAL

The interval between records being written when writing multiple records. The default value is 1.

REC_START

The record number at which to start writing. The default is 0.

ZVARIABLE

If Variable is a variable ID (as opposed to a variable name) and the variable is a zVariable, set this flag to indicate that the variable ID is a zVariable ID. The default is to assume that Variable is an rVariable ID.

Example

id= CDF_CREATE('mycdf', [5,10], /NETWORK_ENCODING, /ROW_MAJOR)

varid= CDF_VARCREATE(id, 'V1', [1,1], /CDF_FLOAT, /REC_VARY)

To write the value 42.0 into record 12, third row, fourth column:

CDF_VARPUT, id, varid, 42, REC_START=12, OFFSET=[2,3]

To write 3 records, skipping every other record, starting at record 2, writing every other entry of each record. Note that in this example we write 25 values into each record written:

CDF_VARPUT, id, varid, FINDGEN(5,5,3), INTERVAL=[2,1], $

            REC_INTERVAL=2, REC_START=2

CDF_DELETE, id


CDF_VARRENAME

The CDF_VARRENAME procedure renames an existing variable in a Common Data Format file.

Calling Sequence

CDF_VARRENAME, Id, OldVariable, NewName

Arguments

Id

The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE.

OldVariable

A string containing the current name of the variable or the variable number to be renamed.

NewName

A string containing the new name for the variable.

Keywords

ZVARIABLE

If OldVariable is a variable ID (as opposed to a variable name) and the variable is a zVariable, set this flag to indicate that the variable ID is a zVariable ID. The default is to assume that OldVariable is an rVariable ID.

Example

See the example for "CDF_VARGET" on page 56.


Hierarchical Data Format

This chapter details the interface routines for the Hierarchical Data Format. General notes about the interface are presented below, followed by individual descriptions of the routines.

This version of IDL supports HDF 4.0. However, features new to HDF 4.0 are not supported in this version of IDL. This features include, but are not limited to:

•	The new Multi-file Annotation Interface (ANxxx).

•	The new Multi-file Raster Image Interface (GRxxx).

•	HDF reading of CDF files.

•	Reading/Writing of compressed HDF scientific datasets (SDS).

•	Reading/Writing of SDS using the new n-bit interface.

HDF Interfaces

There are two basic interfaces to HDF files, the single-file application interface and the multiple-file application interface. These interfaces support eight different types (or "models") of data access. The table below lists the different models and the names of the IDL routines that access those models. Each model is described in more detail after the table.

Table 3-1: Data Access Models and Routine Prefixes.

Model	IDL Routine Name Prefix
24-bit raster	HDF_DF24_
annotation data	HDF_DFAN_
palette data	HDF_DFP_
8-bit raster	HDF_DFR8_
scientific data	HDF_DFSD_
multi-file scientific data	HDF_SD_
VData	HDF_VD_
VGroup	HDF_VG_
Single File Application Interfaces

In this mode, access is limited to one file at a time. This interface supports the 8-bit raster, 24-bit raster, palette, scientific data, and annotation models. The interfaces are described in more detail after the table.

•	8-bit Raster Model: The HDF_DFR8_ routines access 8-bit images.

•	Palette Model: The HDF_DFP_ routines are used to work with the HDF_DFR8_ routines to manipulate palettes associated with 8-bit HDF images.

•	24-bit Raster Model: The HDF_DFR24_ routines access 24-bit images.

•	Scientific Data Models (SDs): Used to manipulate arrays of arbitrary dimension and type. Under this model, an array accompanied by a record of its data type, dimensions and descriptors is called a Scientific Dataset (SD). HDF supports two kinds of SDs—the older single-file DFSD, and the new, NetCDF based, MFSD.

To show preference to the new format, HDF and IDL refer to "MFSD" as simply "SD". IDL calls to the SD model are distinguished by the prefix HDF_SD, while calls to the DFSD are distinguished by the HDF_DFSD prefix. Unfortunately, HDF4.0 uses the same tags for the two different scientific data models. Therefore, caution should be used when accessing the SDs through tags. IDL routines may seem to work, but may actually read incorrect information when tags, and not the standard HDF_SD_ routines, are used.

•	Annotation Model: The annotation model is used to describe the contents of the file through such items as labels, data descriptors, and dimension scales.

•	Vdata Model: This interface allows for the creation of customized tables. Each table consists of a series of Vdata records whose values are stored in fixed length fields. As described in more detail in the Vdata example below, a Vdata can contain three kinds of identifying information: a Vdata name, Vdata Class, and multiple Vdata field names. The Vdata model is accessed through the routines that begin with the HDF_VD_ prefix.

•	Vgroup Model: A collection of one or more data objects, Vdata sets, or Vgroups is known as a Vgroup. Each Vgroup can be given a Vgroup name and Vgroup class. The Vgroup model is accessed through the routines that begin with the HDF_VG_ prefix.

Multi-File Application Interface

The HDF_SD_ routines allow operations on more than one file at a time. This multi-file interoperability is achieved through HDF's use of a modified version of the NetCDF library. IDL's interface to HDF's multi-file capability is the HDF_SD_SETEXTFILE routine.

Creating an HDF File in IDL

The following IDL commands should be used to create a new HDF file:

•	HDF_OPEN: Call this procedure first to open an HDF file. The CREATE keyword must be set if you want to create a new file instead of open an existing one.

•	HDF_DFAN_ADDFDS: Optionally, add a file description.

•	HDF_DFAN_ADDFID: Optionally, add a file annotation.

Adding Data to an HDF File

The routines used to add data to an HDF file vary based on the interface model being used.

•	To add an 8-bit image (with or without a palette), use HDF_DFR8_ADDIMAGE or DFR8_PUTIMAGE.

•	To add a palette, use HDF_DFP_ADDPAL or HDF_DFP_PUTPAL.

•	To add a 24-bit image, use HDF_DF24_ADDIMAGE or HDF_DF24_PUTIMAGE.

•	To add a Scientific Dataset, use the following commands:

HDF_DFSD_SETINFO to insert information about the data (optional). HDF_DFSD_DIMSET to set dimension information.
HDF_DFSD_ADDDATA to insert the data.

•	To add a Multi-File Scientific Dataset, use the following commands:

HDF_SD_CREATE or HDF_SD_SELECT to create an SDS or select an existing one.
HDF_SD_DIMSET to set dimension information.
HDF_SD_ATTRSET to set attribute information.
HDF_SD_SETINFO to insert optional information about the data.
HDF_SD_ADDDATA to insert the data.
HDF_SD_SETEXTFILE to move the data to an external file (optional).
HDF_SD_ENDACCESS to end access to the SDS.

•	To add a Vdata, use the following commands:

HDF_VD_ATTACH to get a Vdata identifier.
HDF_VD_SETINFO to write information about the Vdata (optional). HDF_VD_FDEFINE to prepare non-trivial fields (optional).
HDF_VD_WRITE to write the Vdata.

•	To add a Vdata to a Vgroup, use the following commands:

HDF_VG_ATTACH to get a Vgroup identifier.
HDF_VG_SETINFO to set the Vgroup name and class (optional).
HDF_VG_INSERT to add the Vdata to a Vgroup.
HDF_VG_DETACH to close the Vgroup.
HDF_CLOSE to close the file.

HDF Examples

Two example files that demonstrate the use of the HDF routines can be found in the hdf_ncdf subdirectory of the examples subdirectory of the IDL distribution. The file hdf_info.pro prints a summary of basic information about an HDF file. The file hdf_rdwr.pro creates a new HDF file and then reads the information back from that file.

HDF Scientific Dataset ID Numbers

IDL's HDF_SD_ routines can accept two different types of ID numbers. Documentation for these routines in the IDL Reference Guide refers to these ID numbers as the SD_ID and SDS_ID arguments.

The SD_ID is the Scientific Dataset interface ID. There is only one SD_ID per HDF file. For each actual dataset used, you will also need an SDS_ID, which is the ID for the particular dataset.

Some routines, such as HDF_SD_ATTRFIND accept either an SD_ID or an SDS_ID. In these cases, the documentation refers to the ID as an S_ID, meaning that either type of ID is accepted.

A Cautionary Note about Tags

Both the old DFSD and the new MFSD HDF interfaces use the same tags. Therefore, you must be careful when reading or writing SDs. Use only the appropriate "HDF_SD_" or "HDF_DFSD_" routines. The wrong SD interface may seem to work, but may return bad results.

 IDL and HDF Data Types

HDF and IDL support many different data types. Many of the HDF routines allow you to perform a data type conversion "on the fly" by setting keywords such as FLOAT. When the data type desired is not explicitly specified, IDL uses the conversions shown in the following tables. Note that single-precision floating-point is the default data type and that the complex data type is not supported.

When writing IDL data to an HDF file, IDL data types are converted to the HDF data types shown in the following table:

Table 3-2: Type Conversions when Writing IDL Data to an HDF File

IDL Data Type	HDF Data Type
BYTE	DFNT_UINT8 (IDL bytes are unsigned)
INT	DFNT_INT16
LONG	DFNT_INT32
FLOAT	DFNT_FLOAT32
DOUBLE	DFNT_DOUBLE
STRING	DFNT_CHAR
When reading data from an HDF file, HDF data types are converted to the IDL data types shown in the following table:

Table 3-3: Type Conversions when Reading HDF Data into IDL

HDF Data Type	IDL Data Type
DFNT_CHAR or DFNT_UCHAR	STRING
DFNT_INT8 or DFNT_UINT8	BYTE
DFNT_INT16 or DFNT_UINT16	INT
DFNT_INT32 or DFNT_UINT32	LONG
DFNT_FLOAT32 or DFNT_NONE	FLOAT
DFNT_DOUBLE	DOUBLE
 HDF type codes for the supported HDF data types are shown in the table below:

Table 3-4: HDF Data Type Codes

HDF Data Type	Type Code
DFNT_UCHAR	3
DFNT_CHAR	4
DFNT_FLOAT32	5
DFNT_DOUBLE	6
DFNT_INT8	20
DFNT_UINT8	21
DFNT_INT16	22
DFNT_UINT16	23
DFNT_INT32	24
DFNT_UINT32	25
Common HDF Tag Numbers

The following table lists common HDF tag numbers and their meanings.

Table 3-5: Common HDF Tag Numbers

Tag Number	Meaning
030	Version Identifier
100	File Identifier
101	File Description
102	Tag Identifier
103	Tag Description
104	Data Identifier Label
105	Data Identifier Annotation
106	Number Type
107	Machine Type
200	Obsolete
201	Obsolete
202	Obsolete
203	Obsolete
204	Obsolete
300	RIG Image Dimension
301	Raster Image Look Up Table (LUT)
302	Raster Image
303	Compressed Raster Image
306	Raster Image Group (RIG)
307	RIG LUT Dimension
308	RIG Matte Dimension
309	Raster Image Matte Data
310	Raster Image Color Correction
311	Raster Image Color Format
312	Raster Image Aspect Ratio
400	Composite Image Descriptor
500	XY Position
602	Vector Image - Tek4014 Stream
603	Vector Image - Tek4105 Stream
701	SD Dimension Record
702	SD Data
703	SD Scales
704	SD Labels
705	SD Units
706	SD Formats
707	SD Max/Min
708	SD Coordinates
710	SD Link
720	SD Descriptor (NDG)
731	SD Calibration Information
732	SD Fill Value
1962	Vdata Description
1963	Vdata
1965	Vgroup


HDF_CLOSE

The HDF_CLOSE procedure closes the Hierarchical Data Format file associated with the given file handle.

Calling Sequence

HDF_CLOSE, Filehandle

Arguments

Filehandle

The HDF file handle returned from a previous call to HDF_OPEN.

See Also

HDF_OPEN


HDF_DELDD

The HDF_DELDD procedure deletes a tag or reference from the list of data descriptors in a Hierarchical Data Format file.

Calling Sequence

HDF_DELDD, FileHandle, Tag, Ref

Arguments

Filehandle

The HDF file handle returned from a previous call to HDF_OPEN.

Tag

The data descriptor tag to delete.

Ref

The data descriptor reference number to delete.


HDF_DF24_ADDIMAGE

The HDF_DF24_ADDIMAGE procedure writes a 24-bit raster image to a Hierarchical Data Format file. The interlace is set automatically based upon the dimensions of the image being written: ARR(3, Width, Height) for pixel interlace, ARR(Width, 3, Height) for scan-line interlace, and ARR(Width, Height, 3) for scan-plane interlace.

Note	HDF_DF24_ADDIMAGE chooses an interlace based upon the location of the `3'-sized dimension. For 3x3xN, 3xNx3 and Nx3x3 images, if the first `3' encountered is supposed to be a width or height, HDF_DF24_ADDIMAGE will choose the `wrong' interlace. However, as long as one reads in the image using the same interlace, the image will be read correctly anyway. Avoid writing 24-bit-deep raster images with a width or height of 3 pixels.

Note	Input data is converted to bytes before being written to the file, as images in the DF24 HDF model are necessarily byte images.

Calling Sequence

HDF_DF24_ADDIMAGE, Filename, Image

Arguments

Filename

A scalar string containing the name of the file to be written.

Image

A 3-dimensional array of values representing the 3 planes (Red, Green, and Blue) of the 24-bit image. One of the dimensions must be 3 (e.g., a 3 x 100 x 100 array).

Keywords

FORCE_BASELINE

Set this keyword to force the JPEG quantization tables to be constrained to the range 1...255. This provides full baseline compatibility with external JPEG applications, but only makes a difference if the QUALITY keyword is set to a value less than 25. The default is TRUE.

JPEG

Set this keyword to compress the image being added using the JPEG (Joint Photographic Expert Group) method. Note that JPEG compression is lossy; see WRITE_JPEG in the IDL Reference Guide for more information about when this method is appropriate. (In other words, using JPEG compression to reduce the size of an images changes the values of the pixels and hence may alter the meaning of the corresponding data.) Setting either the QUALITY or the FORCE_BASELINE keywords implies this method.

QUALITY

Set this keyword equal to the JPEG "quality" desired. This value should be in range 0 (terrible image quality but excellent compression) to 100 (excellent image quality but minimum compression). The default is 75. Setting this keyword implies that the JPEG keyword is set. Lower values of QUALITY produce higher compression ratios and smaller files.

RLE

Set this keyword to store the image using run length compression. RLE compression is lossless, and is recommended for images where data retention is critical.

See Also

WRITE_JPEG in the IDL Reference Guide.


HDF_DF24_GETIMAGE

The HDF_DF24_GETIMAGE procedure reads a 24-bit raster image from a Hierarchical Data Format file. The default is to use the same format for reading as that used in writing the image. Note: it is slower to read an image in a different interlace than the one the image was originally written with.

Calling Sequence

HDF_DF24_GETIMAGE, Filename, Image

Arguments

Filename

A scalar string containing the name of the file to be read.

Image

A named variable in which the image data is returned.

Keywords

LINE

Set this keyword to force the image to be read with scan-line interlace.

PIXEL

Set this keyword to force the image to be read with pixel interlace.

PLANE

Set this keyword to force the image to be read with scan-plane interlace.


HDF_DF24_GETINFO

The HDF_DF24_GETINFO procedure retrieves information about the current 24-bit HDF image.

Calling Sequence

HDF_DF24_GETINFO, Filename, Width, Height, Interlace

Arguments

Filename

A string containing the name of the file to be read.

Width

A named variable in which the width of the image is returned.

Height

A named variable in which the height of the image is returned.

Interlace

A named variable in which the interface method is returned. The returned value is 0 for pixel interlacing, 1 for scan-line interlacing, and 2 for scan-plane interlacing.

Example

h = HDF_OPEN('myhdf.hdf')	;Open the file myhdf.hdf.

HDF_DF24_GETINFO, 'myhdf.hdf', width, height, interlace
;Return information about the 24-bit image.

HELP, width, height, interlace	;Print information about the returned variables. If the image were 536 by 412 pixels, and scan-line interlaced, IDL would print:
WIDTH LONG = 536
HEIGHT LONG = 412
INTERLACE LONG = 1

HDF_CLOSE('myhdf.hdf')	;Close the HDF file.

For a more detailed example, see the file hdf_info.pro, located in the examples subdirectory of the main IDL directory.

See Also

HDF_DF24_GETIMAGE, HDF_DF24_LASTREF, HDF_DF24_NIMAGES, HDF_DF24_READREF, HDF_DF24_RESTART


HDF_DF24_LASTREF

The HDF_DF24_LASTREF function returns the reference number of the most recently read or written 24-bit image in an HDF file.

Calling Sequence

Result = HDF_DF24_LASTREF()

Example

h=HDF_OPEN('myhdf.hdf')	;Open an HDF file.

PRINT, HDF_DF24_LASTREF()	;IDL prints 0, meaning that the call was successful, but no reference number was available.

a = BINDGEN(3,100,100)	;Create a 3D array, representing a 24-bit image.

HDF_DF24_ADDIMAGE, 'myhdf.hdf', a	;Write the 24-bit image to the file.

PRINT, HDF_DF24_LASTREF()	;IDL prints a reference number for the last operation (for example, 2). Note the reference number is not simply a 1-based "image number"—the reference number could easily be "2" or "3", etc.

HDF_DF24_ADDIMAGE, 'myhdf.hdf', a	;Write another image to the file.

PRINT, HDF_DF24_LASTREF()	;Print the last reference number.

PRINT, HDF_DF24_NIMAGES('myhdf.hdf')	;IDL prints "2" because we've written two images to the file.

HDF_CLOSE, h	;Close the file.

See Also

HDF_DF24_ADDIMAGE, HDF_DF24_GETIMAGE, HDF_DF24_GETINFO, HDF_DF24_NIMAGES, HDF_DF24_READREF, HDF_DF24_RESTART, HDF_DFR8_LASTREF


HDF_DF24_NIMAGES

The HDF_DF24_NIMAGES function returns the number of 24-bit images in an HDF file. A -1 is returned if the specified file is invalid or damaged.

Calling Sequence

Result = HDF_DF24_NIMAGES(Filename)

Arguments

Filename

A string containing the name of the file to be searched.

Example

h = HDF_OPEN('myhdf.hdf')	;Open an HDF file.

number = HDF_DF24_NIMAGES('myhdf.hdf')	;Return the number of 24-bit images in the file.

HELP, number	;Print information about the returned value. If there were five images in the file, IDL would print:
NUMBER LONG = 5

HDF_CLOSE, h	;Close the HDF File.

See Also

HDF_DF24_GETIMAGE, HDF_DF24_GETINFO, HDF_DF24_READREF, HDF_DF24_RESTART, HDF_DFR8_NIMAGES


HDF_DF24_READREF

The HDF_DF24_READREF procedure sets the reference number of the image in a Hierarchical Data Format file to be read by the next call to HDF_DF24_GETIMAGE.

Calling Sequence

HDF_DF24_READREF, Filename, Refno

Arguments

Filename

A scalar string containing the name of the file to be read.

Refno

The reference number for a 24-bit raster image.


HDF_DF24_RESTART

The HDF_DF24_RESTART procedure causes the next call to HDF_DF24_GETIMAGE to read the first 24-bit image in the Hierarchical Data Format file.

Calling Sequence

HDF_DF24_RESTART


HDF_DFAN_ADDFDS

The HDF_DFAN_ADDFDS procedure adds a file description to a Hierarchical Data Format file.

Calling Sequence

HDF_DFAN_ADDFDS, Filename, Description

Arguments

Filename

A scalar string containing the name of the file to be written.

Description

A string or a array of bytes containing the information to be written.


HDF_DFAN_ADDFID

The HDF_DFAN_ADDFID procedure adds a file annotation to a Hierarchical Data Format file. A file can have multiple annotations added.

Calling Sequence

HDF_DFAN_ADDFID, Filename, Label

Arguments

Filename

A scalar string containing the name of the file to be written.

Label

A string containing the annotation string.

Example

Open and HDF file:

filename = 'FID.hdf'

hid = HDF_OPEN(filename,/CREATE)

Write two file annotations:

HDF_DFAN_ADDFID, filename, 'File Annotation #1'

HDF_DFAN_ADDFID, filename, 'File Annotation #2'

Read the two annotations back:

HDF_DFAN_GETFID, filename, fid1

HDF_DFAN_GETFID, filename, fid2

HELP, fid1, fid2

IDL prints:

FID1            STRING    = 'File Annotation #1'

FID2            STRING    = 'File Annotation #2'

Try to read a non-existant FID:

HDF_DFAN_GETFID, filename, fid3

IDL prints:

% HDF_DFAN_GETFID: Could not read ID length

Read the FIRST fid again, using the FIRST keyword:

HDF_DFAN_GETFID, filename, fid4, /FIRST

HELP, fid4

FID4            STRING    = 'File Annotation #1'

HDF_CLOSE, hid	;Close the HDF file.


HDF_DFAN_GETDESC

The HDF_DFAN_GETDESC procedure reads the description for the given tag and reference number in a Hierarchical Data Format file.

Calling Sequence

HDF_DFAN_GETDESC, Filename, Tag, Ref, Description

Arguments

Filename

A scalar string containing the name of the file to be read.

Tag

The tag number.

Ref

The reference number.

Description

A named variable in which the description is returned as a vector of bytes.

If a description does not exist, the Description variable will contain either a 0L (long-integer zero) or a blank string, and a warning message will be printed. Warning messages can be suppressed by setting the !QUIET system variable to a non-zero value.

Keywords

STRING

Set this keyword to return the description as a string rather than a vector of bytes.

Example

desc1 = 'FILE DESCRIPTION NUMBER 1'

tag_image = 302

file = 'DEMOdesc.hdf'

fid = HDF_OPEN(file, /CREATE)

HDF_DFR8_ADDIMAGE, file, DIST(10)

HDF_DFAN_PUTDESC, file, tag_image, HDF_DFR8_LASTREF(), desc1

Read the description and return a vector of bytes:

HDF_DFAN_GETDESC, file, tag_image, HDF_DFR8_LASTREF(), out_desc1

HELP, out_desc1

IDL prints:

OUT_DESC1       BYTE      = Array(25)

PRINT, STRING(out_desc1)

IDL prints:

FILE DESCRIPTION NUMBER 1

Read the description and return an IDL string variable:

HDF_DFAN_GETDESC, file, tag_image, HDF_DFR8_LASTREF(), $

    out_desc2, /STRING

HELP, out_desc2

IDL prints:

OUT_DESC2       STRING    = 'FILE DESCRIPTION NUMBER 1'

HDF_CLOSE, fid

See Also

HDF_DFAN_PUTDESC


HDF_DFAN_GETFDS

The HDF_DFAN_GETFDS procedure reads the next available file description from an HDF file.

Calling Sequence

HDF_DFAN_GETFDS, Filename, Description

Arguments

Filename

A string containing the name of the file to be read.

Description

A named variable in which the description is returned. By default, the description is returned as a vector of bytes. Set the STRING keyword to return the description as a string.

If a description does not exist, the Description variable will contain either a 0L (long-integer zero) or a blank string, and a warning message will be printed. Warning messages can be suppressed by setting the !QUIET system variable to a non-zero value.

Keywords

FIRST

Set this keyword to read the first file description in the file. If FIRST is not set, the next available file description (which can be the first file description) will be read.

STRING

Set this keyword to return Description as a string instead of a vector of bytes.

Example

filename = 'DEMOfds.hdf'

fds1 = 'FILE DESCRIPTION NUMBER 1'

fds2 = 'SHORT FDS 2'

fid = HDF_OPEN(filename, /CREATE)	;Create an HDF file.

HDF_DFAN_ADDFDS, filename, fds1	;Add first file description.

HDF_DFAN_ADDFDS, filename, fds2	;Add second file description.

HDF_DFAN_GETFDS, filename, out_fds1, /FIRST
;Get the first file description.

HELP, out_fds1

IDL prints:

OUT_FDS1        BYTE      = Array(25)

PRINT, STRING(out_fds1)

IDL prints:

FILE DESCRIPTION NUMBER 1

HDF_DFAN_GETFDS, filename, out_fds2, /STRING
;Get the second file description.

HELP, out_fds2

IDL prints:

OUT_FDS2        STRING    = 'SHORT FDS 2'

HDF_CLOSE, fid	;Close the HDF file.

See Also

HDF_DFAN_ADDFDS, HDF_DFAN_ADDFID, HDF_DFAN_GETDESC, HDF_DFAN_GETFID


HDF_DFAN_GETFID

The HDF_DFAN_GETFID procedure reads the next available file annotation from a Hierarchical Data Format file.

Calling Sequence

HDF_DFAN_GETFID, Filename, Label

Arguments

Filename

A scalar string containing the name of the file to be read.

Label

A named variable in which the annotation is returned as a string.

Keywords

FIRST

Set this keyword to read the first annotation in the file. Otherwise, the next available annotation is read (which may be the first annotation).

Example

For an example using this routine, see "HDF_DFAN_ADDFID" on page 87.


HDF_DFAN_GETLABEL

The HDF_DFAN_GETLABEL procedure reads the label for the given tag-reference pair in a Hierarchical Data Format file.

Calling Sequence

HDF_DFAN_GETLABEL, Filename, Tag, Ref, Label

Arguments

Filename

A scalar string that contains the name of the file to be read.

Tag

The tag number.

Ref

The reference number.

Label

A named variable in which the label is returned as a string.

Example

fid = HDF_OPEN('test.hdf', /ALL)

label = 'TEST LABEL'

tag = 105	;The annotation tag.

ref = 2	;Choose a reference number.

HDF_DFAN_PUTLABEL, 'test.hdf', tag, ref, label
;Write the label.

HDF_DFAN_GETLABEL, 'test.hdf', tag, ref, outl
;Read the label back.

HELP, outl	;They look the same...

OUTL            STRING    = 'TEST LABEL'

HDF_CLOSE, fid	;Close the file.

See Also

HDF_DFAN_GETDESC, HDF_DFAN_LABLIST, HDF_DFAN_PUTDESC, HDF_DFAN_PUTLABEL


HDF_DFAN_LABLIST

The HDF_DFAN_LABLIST function retrieves a list of the reference numbers and the corresponding labels for a given tag in a Hierarchical Data Format file. If successful, the number of entries found is returned.

Calling Sequence

Result = HDF_DFAN_LABLIST(Filename, Tag, Reflist, Labellist)

Arguments

Filename

A scalar string containing the name of the file to be read.

Tag

The tag number.

Reflist

A named variable in which an array of reference numbers associated with the given tag is returned.

Labellist

A named variable in which an array of labels is returned. Unless the STRING keyword is set, Labellist will contain an N_ELEMENTS(Reflist) by MAXLABEL array of bytes. Note that array elements containing labels that are shorter than MAXLABEL will be padded with zeroes.

Keywords

LISTSIZE

Set the maximum size of the Reflist and Labellist returned. The default is to read all references present, or 20 if the inquiry to obtain the number of references fails.

MAXLABEL

Use this keyword to override the default label length of 16.

STARTPOS

Use this keyword to set the default starting position in the Reflist array.

STRING

Set this keyword to return an array of strings rather than an array of bytes. If STRING is set, the MAXLABEL keyword is ignored and full-length strings are returned.

Example

tag_image = 302

file = 'DEMOlablist.hdf'

n_images = HDF_DFAN_LABLIST(file, tag_image, refs, list, /STRING)

help, n_images, refs, list

IDL prints:

N_IMAGES        LONG      =            2

REFS            INT       = Array(2)

LIST            STRING    = Array(2)

PRINT, list(0)

IDL prints:

SAMPLE IMAGE LABEL

Find all the compressed images:

tag_image_comp = 303

n_comp_images = HDF_DFAN_LABLIST(file, tag_image_comp, $

    refs, list, MAXLABEL=5)

HELP, n_comp_images, refs, list

IDL prints:

N_COMP_IMAGES   LONG      =            3

REFS            INT       = Array(3)

LIST            BYTE      = Array(5, 3)

See Also

HDF_DFAN_GETLABEL, HDF_DFAN_PUTLABEL


HDF_DFAN_LASTREF

The HDF_DFAN_LASTREF function returns the reference number of the most recently read or written annotation in a Hierarchical Data Format file.

Calling Sequence

Result = HDF_DFAN_LASTREF()


HDF_DFAN_PUTDESC

The HDF_DFAN_PUTDESC procedure writes a description for the given tag and reference number in a Hierarchical Data Format file.

Calling Sequence

HDF_DFAN_PUTDESC, Filename, Tag, Ref, Description

Arguments

Filename

A scalar string containing the name of the file to be written.

Tag

The tag number.

Ref

The reference number.

Description

A string or array of bytes containing the information to be written.

If a description does not exist, the Description variable will contain either a 0L (long-integer zero) or a blank string, and a warning message will be printed. Warning messages can be suppressed by setting the !QUIET system variable to a non-zero value.

Bugs

Attempting to overwrite an existing description with a longer one fails.

Overwriting an existing description with a shorter description succeeds, but the description length is unchanged and garbage characters are left at the end of the description).

Example

See the example for "HDF_DFAN_GETDESC" on page 89.


HDF_DFAN_PUTLABEL

The HDF_DFAN_PUTLABEL procedure writes a label for the given tag and reference number in a Hierarchical Data Format file.

Calling Sequence

HDF_DFAN_PUTLABEL, Filename, Tag, Ref, Label

Arguments

Filename

A scalar string containing the name of the file to be written.

Tag

The tag number.

Ref

The reference number.

Label

A string containing the description to write.

Bugs

Due to a problem in the HDF version 4.0 library, attempting to rewrite a label fails. For example:

file = 'blah.hdf'	;Specify a file.

tag = 105 & ref = 40	;Specify tag and ref numbers.

HDF_DFAN_PUTLABEL, file, tag, ref, 'XXXX'	;Make label "XXXX"

HDF_DFAN_PUTLABEL, file, tag, ref, 'YY'	;Label now "YY"

The following command deletes the file:

OPENU, unit, file, /DELETE, /GET & CLOSE, unit

Now try to re-use label "XXXX":

HDF_DFAN_PUTLABEL, file, tag, ref, 'XXXX'

IDL prints:

% HDF_DFAN_PUTLABEL: Failed to write label

% Execution halted at:  $MAIN$


HDF_DFP_ADDPAL

The HDF_DFP_ADDPAL procedure appends a palette to a Hierarchical Data Format file.

Calling Sequence

HDF_DFP_ADDPAL, Filename, Palette

Arguments

Filename

A scalar string containing the name of the file to be written.

Palette

A vector or array containing palette data. Palettes must be either [3, 256] arrays or  786-element vectors.


HDF_DFP_GETPAL

The HDF_DFP_GETPAL procedure reads the next available palette from a Hierarchical Data Format file.

Calling Sequence

HDF_DFP_GETPAL, Filename, Palette

Arguments

Filename

A scalar string containing the name of the file to be read.

Palette

A named variable in which the palette data is returned.


HDF_DFP_LASTREF

The HDF_DFP_LASTREF function returns the reference number of the most recently read or written palette in a Hierarchical Data Format file.

Calling Sequence

Result = HDF_DFP_LASTREF()


HDF_DFP_NPALS

The HDF_DFP_NPALS function returns the number of palettes present in a Hierarchical Data Format file. This number includes palettes associated with RIS8 (8-bit raster) images.

Calling Sequence

Result = HDF_DFP_NPALS(Filename)

Arguments

Filename

A scalar string containing the name of the desired HDF file.


HDF_DFP_PUTPAL

The HDF_DFP_PUTPAL procedure appends a palette to a Hierarchical Data Format file.

Calling Sequence

HDF_DFP_PUTPAL, Filename, Palette

Arguments

Filename

A scalar string containing the name of the file to be written.

Palette

A vector or array containing palette data.  Palettes must be either [3, 256] arrays or  786-element vectors.

Keywords

DELETE

Set this keyword to delete the HDF file (if it exists) and create a new HDF file with the specified palette as its first object.

Note	The HDF file must be closed before the DELETE keyword is specified. Attempting to delete an open HDF file will result in an error.

OVERWRITE

Set this keyword to overwrite the previous palette with the one specified by Palette.

Example

id = HDF_OPEN('test.hdf', /CREATE, /RDWR)
;Create an HDF file.

HDF_DFP_PUTPAL,'test.hdf'', FINDGEN(3,256)
;Add a palette.

PRINT, HDF_DFP_NPALS('test.hdf')	;Print the number of palettes.

IDL prints:

1

HDF_DFP_PUTPAL,'test.hdf',findgen(3,256)
;Append a palette.

PRINT, HDF_DFP_NPALS('test.hdf')	;Print the number of palettes.

IDL prints:

2

HDF_DFP_PUTPAL, 'test.hdf', FINDGEN(3,256), /OVERWRITE
;Overwrite the last palette.

PRINT, HDF_DFP_NPALS('test.hdf')	;Print the number of palettes.

IDL prints:

2

;An attempt to delete a file and add a new palette without first closing the HDF file fails:

HDF_DFP_PUTPAL, 'test.hdf', FINDGEN(3,256), /DELETE

IDL prints:

% HDF_DFP_PUTPAL: Could not write palette

% Execution halted at:  $MAIN$

HDF_CLOSE, id	;Close the HDF file.

HDF_DFP_PUTPAL, 'test.hdf', FINDGEN(3,256), /DELETE
;Delete file and add a new palette.

PRINT, HDF_DFP_NPALS('test.hdf')	;Print the number of palettes.

IDL prints:

1


HDF_DFP_READREF

The HDF_DFP_READREF procedure sets the reference number of the palette in a Hierarchical Data Format file to be read by the next call to HDF_DFP_GETPAL.

Calling Sequence

HDF_DFP_READREF, Filename, Refno

Arguments

Filename

A scalar string containing the name of the file to be read.

Refno

The reference number of a palette.


HDF_DFP_RESTART

The HDF_DFP_RESTART procedure causes the next call to HDF_DFR8_GETPAL to read from the first palette in a Hierarchical Data Format file.

Calling Sequence

HDF_DFP_RESTART


HDF_DFP_WRITEREF

The HDF_DFP_WRITEREF procedure sets the reference number for the next palette to be written to a Hierarchical Data Format file. Normally, the HDF library automatically chooses a reference number for the palette. This procedure allows you to override that choice.

Calling Sequence

HDF_DFP_WRITEREF, Filename, Refno

Arguments

Filename

A scalar string containing the name of the file to be read.

Refno

The new reference number.


HDF_DFR8_ADDIMAGE

The HDF_DFR8_ADDIMAGE procedure appends an 8-bit raster image to the specified Hierarchical Data Format file.

Note	Input data is converted to bytes before being written to the file, as images in the DFR8 HDF model are necessarily byte images.

Calling Sequence

HDF_DFR8_ADDIMAGE, Filename, Image

Arguments

Filename

A scalar string containing the name of the file to be written.

Image

A two-dimensional array containing the image data. If this array is not byte-type data, it is converted to bytes before writing.

Keywords

FORCE_BASELINE

Set this keyword to force the JPEG quantization tables to be constrained to the range 1...255. This provides full baseline compatibility with external JPEG applications, but only makes a difference if the QUALITY keyword is set to a value less than 25. The default is TRUE.

JPEG

Set this keyword to compress the image being added using the JPEG (Joint Photographic Expert Group) method. Note that JPEG compression is lossy; see WRITE_JPEG in the IDL Reference Guide for more information about when this method is appropriate. (In other words, using JPEG compression to reduce the size of an images changes the values of the pixels and hence may alter the meaning of the corresponding data.) Setting either the QUALITY or the FORCE_BASELINE keywords implies this method.

IMCOMP

Set this keyword to store the image using imcomp data compression. Note that you must specify a palette. Note also that the JPEG and RLE compression methods are far superior; imcomp data compression should only be used if the images will be viewed on monitors with a very small number of colors (monochrome or 16-color).

PALETTE

Set this keyword to a vector or array containing valid palette data. Palettes must be either [3, 256] arrays or  786-element vectors. Set PALETTE equal to zero to specify that no palette be used. If the PALETTE keyword is not specified, the current palette (which may be no palette, if a palette has not been specified elsewhere or if the null palette has been explicitly specified with HDF_DFR8_SETPALETTE) will be used.

Note that if a palette is specified, it becomes the current palette, even if a default palette has been specified with HDF_DFR8_SETPALETTE.

Note also that if IMCOMP data reduction is used, you must specify a valid palette with the PALETTE keyword. It is not sufficient to set the current palette via other means.

QUALITY

Set this keyword equal to the JPEG "quality" desired. This value should be in range 0 (terrible image quality but excellent compression) to 100 (excellent image quality but minimum compression). The default is 75. Setting this keyword implies that the JPEG keyword is set. Lower values of QUALITY produce higher compression ratios and smaller files.

RLE

Set this keyword to store the image using run length compression. RLE compression is lossless, and is recommended for images where data retention is critical.

Example

Assuming that we start with a file, new.hdf, with no 8-bit raster images, images could be appended and overwritten, with the following commands:

HDF_DFR8_ADDIMAGE, 'new.hdf', Image1	;Write the first image to the file.

HDF_DFR8_ADDIMAGE, 'new.hdf', Image2	;Append 2nd image.

HDF_DFR8_ADDIMAGE, 'new.hdf', Image3	;Append 3rd image.

HDF_DFR8_PUTIMAGE, 'new.hdf', Image4	;Use HDF_DFR8_PUTIMAGE to erase all previous images and write a new image at the first position in the file.

HDF_DFR8_ADDIMAGE, 'new.hdf', Image5	;Append 2nd image.

See Also

HDF_DFR8_GETIMAGE, HDF_DFR8_PUTIMAGE, WRITE_JPEG in the IDL Reference Guide.


HDF_DFR8_GETIMAGE

The HDF_DFR8_GETIMAGE procedure retrieves an image and optionally, its palette, from a Hierarchical Data Format file.

Calling Sequence

HDF_DFR8_GETIMAGE, Filename, Image [, Palette]

Arguments

Filename

A scalar string containing the name of the file to be read.

Image

A named variable in which the image is returned.

Palette

A named variable in which the palette is returned as a 3-element by 256-element byte array. If the image does not have an associated palette, this variable is returned as 0.


HDF_DFR8_GETINFO

The HDF_DFR8_GETINFO procedure retrieves information about the current 8-bit HDF image.

Calling Sequence

HDF_DFR8_GETINFO, Filename, Width, Height, Has_Palette

Arguments

Filename

A string containing the name of the file to be read.

Width

A named variable in which the width of the image is returned.

Height

A named variable in which the height of the image is returned.

Has_Palette

A named variable in which 1 is returned if a palette is present. Otherwise, 0 is returned.

Example

h = HDF_OPEN('myhdf.hdf')	;Open the file myhdf.hdf.

HDF_DFR8_GETINFO, 'myhdf.hdf', width, height, has_palette
;Retrieve information about an image.

HELP, width, height, has_palette	;Print information about the returned variables.

IDL prints:

WIDTH LONG = 536

HEIGHT LONG = 412

HAS_PALETTE LONG = 1

HDF_CLOSE('myhdf.hdf')	;Close the HDF file.

For a more detailed example, see the file hdf_info.pro, located in the examples subdirectory of the main IDL directory.

See Also

HDF_DFR8_GETIMAGE, HDF_DFR8_NIMAGES, HDF_DFR8_READREF, HDF_DFR8_RESTART


HDF_DFR8_LASTREF

The HDF_DFR8_LASTREF function returns the reference number of the most recently read or written 8-bit image in a Hierarchical Data Format file.

Calling Sequence

Result = HDF_DFR8_LASTREF()

Example

h = HDF_OPEN('myhdf.hdf')	;Open an hdf file.

PRINT, HDF_DFR8_LASTREF()	;IDL prints "0", meaning that the call was successful, but no reference number was available.

a = BINDGEN(100,100)	;Create a 2D array representing an 8-bit image.

HDF_DFR8_ADDIMAGE, 'myhdf.hdf', a	;Write the image to the file.

PRINT, HDF_DFR8_LASTREF()	;IDL prints the reference number for the last 8-bit image operation (for example, "2"). Note the reference number is not simply a 1-based `image number'—it could easily be "2" or "3" for the first operation on the file.

HDF_DFR8_ADDIMAGE, 'myhdf.hdf', a	;Add another image.

PRINT, HDF_DFR8_NIMAGES('myhdf.hdf')	;IDL prints "2", because we've put two 8-bit images in the file.

HDF_CLOSE, h	;Close the file.

See Also

HDF_DFR8_ADDIMAGE, HDF_DFR8_GETIMAGE, HDF_DFR8_GETINFO, HDF_DFR8_LASTREF, HDF_DFR8_NIMAGES, HDF_DFR8_READREF, HDF_DFR8_RESTART


HDF_DFR8_NIMAGES

The HDF_DFR8_NIMAGES function returns the number of 8-bit images in the specified Hierarchical Data Format file. A -1 is returned if the specified file is invalid or damaged.

Calling Sequence

Result = HDF_DFR8_NIMAGES(Filename)

Arguments

Filename

A string containing the name of the file to be read.

Example

h = HDF_OPEN('myhdf.hdf')	;Open the file myfile.hdf.

number = HDF_DFR8_NIMAGES('myhdf.hdf')	;Retrieve the number of 8-bit images in the file into the variable number.

HDF_CLOSE, h	;Close the file.

See Also

HDF_DFR8_GETIMAGE, HDF_DFR8_GETINFO, HDF_DFR8_READREF HDF_DFR8_RESTART


HDF_DFR8_PUTIMAGE

The HDF_DFR8_PUTIMAGE procedure writes an 8-bit raster image as the first image in a Hierarchical Data Format file. If there are images in the file, this procedure erases all other 8-bit and 24-bit images and writes Image as the first image in the file.

Note	Input data is converted to bytes before being written to the file, as images in the DFR8 HDF model are necessarily byte images.

Calling Sequence

HDF_DFR8_PUTIMAGE, Filename, Image

Arguments

Filename

A scalar string containing the name of the file to be written.

Image

A two-dimensional array containing the image data. If this array is not byte-type data, it is converted to bytes before writing.

Keywords

FORCE_BASELINE

Set this keyword to force the JPEG quantization tables to be constrained to the range 1...255. This provides full baseline compatibility with external JPEG applications, but only makes a difference if the QUALITY keyword is set to a value less than 25. The default is TRUE.

JPEG

Set this keyword to compress the image being added using the JPEG (Joint Photographic Expert Group) method. Note that JPEG compression is lossy; see WRITE_JPEG in the IDL Reference Guide for more information about when this method is appropriate. (In other words, using JPEG compression to reduce the size of an images changes the values of the pixels and hence may alter the meaning of the corresponding data.) Setting either the QUALITY or the FORCE_BASELINE keywords implies this method.

IMCOMP

Set this keyword to store the image using imcomp data compression. Note that you must specify a palette. Note also that the JPEG and RLE compression methods are far superior; imcomp data compression should only be used if the images will be viewed on monitors with a very small number of colors (monochrome or 16-color).

PALETTE

Set this keyword to a vector or array containing valid palette data. Palettes must be either [3, 256] arrays or  786-element vectors. Set PALETTE equal to zero to specify that no palette be used. If the PALETTE keyword is not specified, the current palette (which may be no palette, if a palette has not been specified elsewhere or if the null palette has been explicitly specified with HDF_DFR8_SETPALETTE) will be used.

Note that if a palette is specified, it becomes the current palette, even if a default palette has been specified with HDF_DFR8_SETPALETTE.

Note also that if IMCOMP data reduction is used, you must specify a valid palette with the PALETTE keyword. It is not sufficient to set the current palette via other means.

QUALITY

Set this keyword equal to the JPEG "quality" desired. This value should be in range 0 (terrible image quality but excellent compression) to 100 (excellent image quality but minimum compression). The default is 75. Setting this keyword implies that the JPEG keyword is set. Lower values of QUALITY produce higher compression ratios and smaller files.

RLE

Set this keyword to store the image using run length compression. RLE compression is lossless, and is recommended for images where data retention is critical.

See Also

HDF_DFR8_ADDIMAGE, HDF_DFR8_GETIMAGE, WRITE_JPEG in the IDL Reference Guide.


HDF_DFR8_READREF

The HDF_DFR8_READREF procedure sets the reference number of the image to be read from a Hierarchical Data Format file by the next call to HDF_DFR8_GETIMAGE.

Calling Sequence

HDF_DFR8_READREF, Filename, Refno

Arguments

Filename

A scalar string containing the name of the file to be read.

Refno

A reference number for an 8-bit raster image.


HDF_DFR8_RESTART

The HDF_DFR8_RESTART procedure causes the next call to HDF_DFR8_GETIMAGE to read from the first image in the Hierarchical Data Format file.

Calling Sequence

HDF_DFR8_RESTART


HDF_DFR8_SETPALETTE

The HDF_DFR8_SETPALETTE procedure sets the current palette to be used for subsequent images in a Hierarchical Data Format file. The current palette will be used when adding images with the HDF_DFR8_ADDIMAGE routine.

Calling Sequence

HDF_DFR8_SETPALETTE, Palette

Arguments

Palette

A 768-element byte array of palette data. This array be a vector (e.g., BYTARR(768)) or a two-dimensional array (e.g., BYTARR(3, 256)).

Set the Palette array to the integer zero to set the current palette to no palette.


HDF_DFSD_ADDDATA

The HDF_DFSD_ADDDATA procedure writes data, as well as all other information set via calls to HDF_DFSD_SETINFO and HDF_DFSD_DIMSET, to a Hierarchical Data Format file.

The Data array must have the same dimensions as the array in the file. The new SDS is appended to the file, unless the OVERWRITE keyword is set.

Calling Sequence

HDF_DFSD_ADDDATA, Filename, Data

Arguments

Filename

A scalar string containing the name of the file to be written.

Data

An expression (typically an array) containing the data to write.

Keywords

OVERWRITE

Set this keyword to write Data as the first, and only, SDS in the file. All previously-written scientific data sets in the file are removed.

SET_DIM

Set this keyword to make the dimension information for the HDF file based upon the dimensions of Data.

Note	You must set the number of dimensions in the HDF file, either by setting the SET_DIM keyword or using the DIMS keyword to HDF_DFSD_SETINFO.

SET_TYPE

Set this keyword to make the data type of the current SDS based on the data type of Data.


HDF_DFSD_DIMGET

The HDF_DFSD_DIMGET procedure retrieves information about the specified dimension number of the current Hierarchical Data Format file.

Calling Sequence

HDF_DFSD_DIMGET, Dimension

Arguments

Dimension

The dimension number [0, 1, 2, ...] to get information about.

Keywords

FORMAT

Set this keyword to return the dimension format string.

LABEL

Set this keyword to return the dimension label string.

SCALE

Use this keyword to return scale information about the dimension. Set this keyword to a vector of values of the same type as the data.

UNIT

Set this keyword to return the dimension unit string.


HDF_DFSD_DIMSET

The HDF_DFSD_DIMSET procedure sets the label, unit, format, or scale of dimensions in a Hierarchical Data Format file. Note that the label, unit, and format of a dataset must be set simultaneously.

Calling Sequence

HDF_DFSD_DIMSET, Dimension

Arguments

Dimension

The dimension number that the label, unit, format or scale apply to.

Keywords

FORMAT

A string for the dimension format. This string should be a standard IDL formatting string.

LABEL

A string for the dimension label.

SCALE

A vector of values used to set the dimension scale.

UNIT

A string for the dimension units.

Example

Suppose that a stored dataset is a 20 by 100 by 50 element floating-point array of values representing water content within the volume of a cloud. Assume further that each element in the 100-element dimension (the "Y" dimension) was sampled at 1/10 mile increments. Appropriate labeling, formatting, unit, and scaling information for the Y dimension can be set with the following command:

HDF_DFSD_DIMSET, 1, LABEL = 'Y Position', FORMAT = 'F8.2', $

             UNIT = 'Miles', SCALE = 0.1*FINDGEN(100)


HDF_DFSD_ENDSLICE

The HDF_DFSD_ENDSLICE procedure ends a sequence of calls started by HDF_DFSD_STARTSLICE by closing the internal slice interface and syncronizing the file.

Calling Sequence

HDF_DFSD_ENDSLICE

Example

See the example in the documentation for .

See Also

, , , , x


HDF_DFSD_GETDATA

The HDF_DFSD_GETDATA procedure reads data from a Hierarchical Data Format file.

Calling Sequence

HDF_DFSD_GETDATA, Filename, Data

Arguments

Filename

A scalar string containing the name of the file to be read.

Data

A named variable in which the data is returned.

Keywords

GET_DIMS

Set this keyword to get dimension information for reading the data. This keyword should only be used if one has not called HDF_DFSD_GETINFO with the DIMS keyword

GET_TYPE

Set this keyword to get the data type for the current SDS.


HDF_DFSD_GETINFO

The HDF_DFSD_GETINFO procedure retrieves information about the current Hierarchical Data Format file.

Note that calling HDF_DFSD_GETINFO with the DIMS or TYPE keywords may alter which dataset is current. See "Reading an Entire Scientific Dataset" and "Getting Other Information About SDSs" in the NCSA HDF Calling Interfaces and Utilities documentation.

Note that reading a label, unit, format, or coordinate system string that has more than 256 characters can have unpredictable results.

Calling Sequence

HDF_DFSD_GETINFO, Filename

Arguments

Filename

A scalar string containing the name of the file to be read. A filename is only needed to determine SDS dimensions and/or the number of SDSs in a file.

Keywords

CALDATA

Set this keyword to a named variable which will contain the calibration data associated with an SDS data set. The data will be returned in a structure of the form:

{ CAL: 0d, CAL_ERR: 0d, OFFSET: 0d, $

  OFFSET_ERR: 0d,NUM_TYPE: 0L }

COORDSYS

Set this keyword to return the data coordinate system description string.

DIMS

Set this keyword to a named variable in which the dimensions of the current SDS are returned in a longword array.

FORMAT

Set this keyword to return the data format description string.

LABEL

Set this keyword to return the data label description string.

LASTREF

Set this keyword to return the last reference number written or read for an SDS.

NSDS

Set this keyword to return the number of SDSs in the file.

RANGE

Set this keyword to return the valid max/min values for the current SDS.

TYPE

Set this keyword to a named variable which returns a string describing the type of the current SDS (e.g., 'BYTE', 'FLOAT', etc.).

UNIT

Set this keyword to return the data unit description string.

Example

The following commands read an SDS, including information about its dimensions but not its annotations:

HDF_DFSD_GETINFO, filename, DIMS=d, TYPE=t, RANGE=r, $

              LABEL=l, UNIT=u, FORMAT=f, COORDSYS=c

...

FOR i = 0, N_ELEMENTS(d)-1 DO BEGIN

HDF_DFSD_DIMGET, i, LABEL=dl, UNIT=du, FORMAT=df, SCALE=ds

...

ENDFOR

HDF_DFSD_GETDATA, filename, data


HDF_DFSD_GETSLICE

The HDF_DFSD_GETSLICE procedure reads a slice of data from the current Hierarchical Data Format file.

Note: Before calling HDF_DFSD_GETSLICE, call HDF_DFSD_GETINFO with the DIMS and TYPE keywords to get the dimensions and type of the next data slice. Failure to get the dimensions and type will cause the HDF interface to attempt to read the data incorrectly, and may cause unexpected results.

Calling Sequence

HDF_DFSD_GETSLICE, Filename, Data

Arguments

Filename

A scalar string containing the name of the file to be read.

Data

A named variable in which the data, read from the SDS, is returned.

Keywords

COUNT

An optional vector containing the counts to be used in reading Value. The default is to read all elements in each record taking the value of OFFSET into account.

OFFSET

A vector specifying the array indices within the specified record at which to begin reading. OFFSET is a 1-dimensional array containing one element per HDF dimension. The default value is zero for each dimension.

Example

See the example in the documentation for .

See Also

, , , , x


HDF_DFSD_PUTSLICE

The HDF_DFSD_PUTSLICE procedure writes a data slice to the current Hierarchical Data Format file.

Note: Before calling HDF_DFSD_PUTSLIDCE, call HDF_DFSD_SETINFO to set the dimensions and attributes of the slice and HDF_DFSD_STARTSLICE to initialize the slice interface.

Calling Sequence

HDF_DFSD_PUTSLICE, Data

Arguments

Data

An array containing the data to write. Dimensions used to write the data are taken from the dimensions of Data, unless the COUNT keyword is used.

Keywords

COUNT

An optional vector containing the counts to be used in writing Data. The counts do have to match the dimensions (number or sizes), but the count cannot describe more elements than exist.

Example

See the example in the documentation for .

See Also

, , , , x


HDF_DFSD_READREF

The HDF_DFSD_READREF procedure specifies the reference number of the Hierarchical Data Format file to be read by the next call to HDF_DFSD_GETINFO or HDF_DFSD_GETDATA.

Calling Sequence

HDF_DFSD_READREF, Filename, Refno

Arguments

Filename

A scalar string containing the name of the file to be read.

Refno

The reference number of the desired SDS.


HDF_DFSD_SETINFO

The HDF_DFSD_SETINFO procedure controls information associated with a Hierarchical Data Format file. Because of the manner in which the underlying HDF library was written, it is necessary to set the dimensions and data type of a scientific data set the first time that HDF_DFSD_SETINFO is called.

This procedure has many options, controlled by keywords. The order in which the keywords are specified is unimportant as the routine insures the order of operation for any given call to it. CLEAR and RESTART requests are performed first, followed by type and dimension setting, followed by length setting, followed by the remaining keyword requests.

If you are not writing any ancillary information, you can call HDF_DFSD_ADDDATA with the SET_TYPE and/or SET_DIMS keywords.

Data string lengths should be set before, or at the same time as, writing the corresponding data string. For example:

HDF_DFSD_SETINFO, LEN_FORMAT=10, FORMAT='12.3F'

or

HDF_DFSD_SETINFO, LEN_FORMAT=10

HDF_DFSD_SETINFO, FORMAT='12.3F'

Due to the underlying C routines, it is necessary to set all four data strings at the same time, or the unspecified strings are treated as `' (null strings). For example:

HDF_DFSD_SETINFO, LABEL = 'hi'

HDF_DFSD_SETINFO, UNIT = 'ergs'

is the same as:

HDF_DFSD_SETINFO, LABEL='hi', UNIT='', FORMAT='', COORDSYS=''

HDF_DFSD_SETINFO, LABEL='', UNIT='ergs', FORMAT='', COORDSYS=''

Calling Sequence

HDF_DFSD_SETINFO

Arguments

None.

Keywords

BYTE

Set this keyword to make the SDS data type DFNT_UINT8 (1-byte unsigned integer).

CALDATA

Set this keyword to a structure containing calibration information. The structure should contain five tags, the first four of which are double-precision floating-point, and fifth of which should be long integer. For example:

caldata = { Cal:          1.0d $	;Calibration factor.

            Cal_Err:      0.1d $	;Calibration error.

            Offset:       2.5d $	;Uncalibrated offset.

            Offset_Err:   0.1d $	;Uncalibrated offset error.

            Num_Type:     5L   $	;Number type of uncalibrated

}	;data.

Some typical values for the Num_Type field include:

For byte data:

3L     (DFNT_UCHAR8)

21L    (DFNT_UINT8)

For integer data:

22L    (DNFT_INT16)

For long-integer data:

24L    (DFNT_INT32)

For floating-point data:

5L     (DFNT_FLOAT32)

6L     (DFNT_FLOAT64)

There are other types, but they are not native to IDL. They can be found in the hdf.h header file for the HDF library.

CLEAR

Set this keyword to reset all possible set values to their default value.

COORDSYS

A string for the data coordinate system description.

DIMS

Set this keyword to a vector of dimensions to be used in writing the next SDS. For example:

HDF_DFSD_SETINFO, DIMS = [10, 20, 30]

DOUBLE

Set this keyword to make the SDS data type DFNT_FLOAT64 (8-byte floating point).

FLOAT

Set this keyword to make the SDS data type DFNT_FLOAT32 (4-byte floating point).

FORMAT

A string for the data format description.

INT

Set this keyword to make the SDS data type DFNT_INT16 (2-byte signed integer).

LABEL

A string for the data label description.

LEN_LABEL

The label string length (default is 255).

LEN_UNIT

The unit string length (default is 255).

LEN_FORMAT

The format string length (default is 255).

LEN_COORDSYS

The format coordinate system string length (default is 255).

LONG

Set this keyword to make the SDS data type DFNT_INT32 (4-byte signed integer).

RANGE

The minimum and maximum range, represented as a 2-element vector of the same data type as the data to be written. The first element is the maximum, the second is the minimum. For example:

HDF_DFSD_SETINFO, RANGE = [10,0]

RESTART

Set this keyword to make the get (HDF_DFSD_GETSLICE) routine read from the first SDS in the file.

UNIT

A string for the data unit description.

Example

Write a 100x50 array of longs:

data = LONARR(100, 50)

HDF_DFSD_SETINFO, /CLEAR, /LONG, DIMS=[100,50], $

              RANGE=[MAX(data), MIN(data)], $

              LABEL='pressure', UNIT='pascals', $

              FORMAT='F10.0'


HDF_DFSD_STARTSLICE

The HDF_DFSD_STARTSLICE procedure prepares the system to write a slice of data to a Hierarchical Data Format file. HDF_DFSD_SETINFO must be called before HDF_DFSD_STARTSLICE to set the dimensions and attributes of the slice.

This procedure must be called before calling HDF_DFSD_PUTSLICE, and must be terminated with a call to HDF_DFSD_ENDSLICE.

Calling Sequence

HDF_DFSD_STARTSLICE, Filename

Arguments

Filename

A scalar string containing the name of the file to be written.

Example

fid=HDF_OPEN('test.hdf',/ALL)	;Open an HDF file.

Create two datasets:

slicedata1=FINDGEN(5,10,15)

slicedata2=DINDGEN(4,5)

Use HDF_DFSD_SETINFO to set the dimensions, then add the first slice:

HDF_DFSD_SETINFO,LABEL='label1', DIMS=[5,10,15], /FLOAT

HDF_DFSD_STARTSLICE,'test.hdf'

HDF_DFSD_PUTSLICE, slicedata1

HDF_DFSD_ENDSLICE

Repeat the process for the second slice:

HDF_DFSD_SETINFO, LABEL='label2', DIMS=[4,5], /DOUBLE

HDF_DFSD_STARTSLICE,'test.hdf'

HDF_DFSD_PUTSLICE, slicedata2

HDF_DFSD_ENDSLICE

HDF_DFSD_SETINFO, /RESTART

Use HDF_DFSD_GETINFO to advance slices and set slice attributes, then get the slices:

HDF_DFSD_GETINFO, name, DIMS=dims, TYPE=type

HDF_DFSD_GETSLICE, out1

HDF_DFSD_GETINFO, name, DIMS=dims, TYPE=type

HDF_DFSD_GETSLICE, out2

Close the HDF file:

HDF_CLOSE('test.hdf')

Check the first slice to see if everything worked:

IF TOTAL(out1 EQ slicedata1) EQ N_ELEMENTS(out1) THEN $

    PRINT, 'SLICE 1 WRITTEN/READ CORRECTLY' ELSE $

    PRINT, 'SLICE 1 WRITTEN/READ INCORRECTLY'

IDL prints:

SLICE 1 WRITTEN/READ CORRECTLY

Check the second slice to see if everything worked:

IF TOTAL(out2 EQ slicedata2) EQ N_ELEMENTS(out2) THEN $

    PRINT, 'SLICE 2 WRITTEN/READ CORRECTLY' ELSE $

    PRINT, 'SLICE 2 WRITTEN/READ INCORRECTLY'

IDL prints:

SLICE 2 WRITTEN/READ CORRECTLY

See Also

, , , , x


HDF_DUPDD

The HDF_DUPDD procedure generates new references to existing data in a Hierarchical Data Format file.

Calling Sequence

HDF_DUPDD, FileHandle, NewTag, NewRef, OldTag, OldRef

Arguments

Filehandle

The HDF file handle returned from a previous call to HDF_OPEN.

NewTag

An integer tag for new data descriptor.

NewRef

An integer reference number for the new data descriptor.

OldTag

The integer tag of data descriptor to duplicate.

OldRef

The reference number of data descriptor to duplicate.


HDF_EXISTS

The HDF_EXISTS function returns True if the Hierarchical Data Format (HDF) scientific data format library is supported on the current IDL platform.

This routine is written in the IDL language. Its source code can be found in the file hdf_exists.pro in the lib subdirectory of the IDL distribution.

Calling Sequence

Result = HDF_EXISTS()

Example

The following IDL command prints an error message if the HDF library is not available:

IF HDF_EXISTS() EQ 0 THEN PRINT, 'HDF not supported.'


HDF_ISHDF

The HDF_ISHDF function returns true (1)  if the file is a Hierarchical Data Format file and false (0) if the file either is not a Hierarchical Data Format file or does not exist.

Caution	This routine bases its judgement as to whether or not a file is an HDF file on the first few bytes of the file. Therefore, it is possible that HDF_ISHDF will identify the file as an HDF file, but HDF_OPEN will not be able to open the file (because it is corrupted).

Calling Sequence

Result = HDF_ISHDF(Filename)

Arguments

Filename

A scalar string containing the name of the file to be tested.


HDF_NEWREF

The HDF_NEWREF function returns the next available reference number for a Hierarchical Data Format file.

Calling Sequence

Result = HDF_NEWREF(Filehandle)

Arguments

Filehandle

The HDF file handle returned from a previous call to HDF_OPEN.


HDF_NUMBER

The HDF_NUMBER function returns the number of tags in a Hierarchical Data Format file or the number of references associated with a given tag.

Calling Sequence

Result = HDF_NUMBER(Filehandle)

Arguments

Filehandle

The HDF file handle returned from a previous call to HDF_OPEN.

Keywords

TAG

Set this keyword to an integer tag number or the string '*'. If this keyword is set to a tag number, HDF_NUMBER returns the number of references associated with the given tag. If this keyword is set to the string '*', or is not specified, HDF_NUMBER returns the total number of tags in the HDF file.


HDF_OPEN

The HDF_OPEN function opens or creates a Hierarchical Data Format file for reading and/or writing. If successful, a non-zero file handle (a longword integer) is returned. Longword -1 is returned on failure.

Note that any combination of the READ, WRITE and CREATE keywords is valid.

Calling Sequence

Result = HDF_OPEN(Filename)

Arguments

Filename

A scalar string containing the name of the file to be opened.

 Keywords

ALL

Set this keyword to create a new HDF file with read and write access. Setting this keyword is equivalent to:

HDF_OPEN(filename, /READ, /WRITE, /CREATE)

CREATE

Set this keyword to create a new HDF file.

NUM_DD

Use this keyword to override the machine default for the number of data descriptors to be allocated per DD block. For example:

H = HDF_OPEN('foo.hdf',/CREATE,/WRITE, NUM_DD=100)

RDWR

Set this keyword to open file with both read and write access. Setting this keyword is equivalent to:

HDF_OPEN(filename, /READ, /WRITE)

READ

Set this keyword to open the file with read access.

WRITE

Set this keyword to open the file with write access.


HDF_SD_ADDDATA

The HDF_SD_ADDDATA procedure writes a hyperslab of values to an SD dataset. By default, the output data is transposed. This transposition puts the data in column order, which is more efficient in HDF than row order (which is more efficient in IDL). In the rare cases where it is necessary to write the data without transposing, set the NOREVERSE keyword. The OFFSET, COUNT, and STRIDE keywords are similarly affected by the NOREVERSE keyword.

Calling Sequence

HDF_SD_ADDDATA, SDS_ID, Data

Arguments

SDS_ID

An SD dataset ID as returned by HDF_SE_SELECT or HDF_SD_CREATE.

Data

The data to be written.

Keywords

COUNT

Set this keyword to a vector of counts (i.e., the number of items) to be written in each dimension. The default is to write all available data. Use caution when using this keyword. See the second example, below.

NOREVERSE

Set this keyword to prevent HDF_SD_ADDDATA's transposition of Data and any vectors specified by keywords into column order.

START

Set this keyword to a vector that contains the starting position for the data. The default position is [0, 0, ..., 0].

STRIDE

Set this keyword to a vector that contains the strides, or sampling intervals, between accessed values of the NetCDF variable. The default stride vector is that for a contiguous write: [0, 0, ..., 0].

Example

The following example writes a 230-element by 380-element byte image to an SD dataset, then reads it back as a 70 by 100 image starting at (40, 20), sampling every other Y pixel and every third X pixel:

start = [40, 20]	;Set the start vector.

count = [70, 100]	;Set the count vector.

stride = [2, 3]	;Set the stride vector.

image = DIST(230, 380)	;Create the image.

TV, image	;Display the image.

sd_id = HDF_SD_START('image.hdf', /CREATE)
;Create a new HDF file in SD mode.

sds_id = HDF_SD_CREATE(sd_id, 'image', [230, 380], /BYTE)
;Define a new SD dataset.

HDF_SD_ADDDATA, sds_id, image	;Write the image into the dataset.

HDF_SD_GETDATA, sds_id, full	;Retrieve the full image.

HDF_SD_GETDATA, sds_id, small, COUNT=count, $

     START=start, STRIDE=stride	;Retrieve the sub-sampled image.

HELP, full, small	;Print information about the images.

IDL prints:

FULL   BYTE = Array(230, 380)

SMALL  BYTE = Array(70, 100)

ERASE	;Erase the window.

TV, full	;Display the full image.

TV, small	;Display the sub-sampled image.

Continuing with our example, suppose we want to write the center 50 by 100 pixels of the image to the file. You might be tempted to try:

HDF_SD_ADDDATA, sds_id, image, START=[90, 90], COUNT=[50,100]

You will find, however, that this captures the lower left-hand corner of the original image, rather than the center. To write the data from the center, subset the original image, choosing the data from the center:

HDF_SD_ADDDATA, sds_id, image(90:139, 90:189), START=[90, 90],$

     COUNT=[50,100]	;This is the correct way to add the data.

HDF_SD_ENDACCESS, sds_id	;End SD access.

HDF_SD_END, sd_id	;Close the file.

See Also

HDF_SD_GETDATA


HDF_SD_ATTRFIND

The HDF_SD_ATTRFIND function locates the index of an HDF attribute given its name. The attribute can be global or from a specific dataset. If an attribute is located, its index is returned. Otherwise, -1 is returned. Once an attribute's index is known, the HDF_SD_ATTRINFO function can be used to read that attribute.

Calling Sequence

Result = HDF_SD_ATTRFIND(S_ID, Name)

Arguments

S_ID

An SD interface ID as returned by HDF_SD_START (i.e., a global attribute's "SD_ID"), or HDF_SD_SELECT/HDF_SD_CREATE (i.e., a dataset's "SDS_ID").

Name

A string containing the name of the attribute whose index is to be returned.

Example

sd_id = HDF_SD_START('demo.hdf')	;Open an HDF file and start the SD interface.

gindex = HDF_SD_ATTRFIND(sd_id, 'TITLE')
;Find "TITLE", a global attribute.

sds_id = HDF_SD_SELECT(sd_id, 1)	;Get the ID for the first dataset.

HDF_SD_ATTRINFO,sd_id,gindex, NAME=name, TYPE=type, COUNT=count
;Read attribute info.

HELP, type, count, name	;Print info about the returned variables.

;IDL prints:

TYPE STRING = 'STRING'

COUNT LONG = 8

NAME STRING = 'TITLE'

dindex = HDF_SD_ATTRFIND(sds_id, 'LOCATION')
;Find the "LOCATION" dataset attribute.

HDF_SD_ATTRINFO,sds_id,dindex,NAME=name,TYPE=type,COUNT=count
;Read attribute info.

See Also

HDF_SD_ATTRINFO, HDF_SD_ATTRSET, HDF_SD_SELECT


HDF_SD_ATTRINFO

The HDF_SD_ATTRINFO procedure reads or retrieves information about an SD attribute. The attribute can be global or from a specific dataset. If an attribute is not present, an error message is printed.

Calling Sequence

HDF_SD_ATTRINFO, S_ID, Attr_Index

Arguments

S_ID

An SD interface ID as returned by HDF_SD_START (i.e., a global attribute's "SD_ID"), or HDF_SD_SELECT/HDF_SD_CREATE (i.e., a dataset's "SDS_ID").

Attr_Index

The attribute index, usually obtained by calling HDF_SD_ATTRFIND or HDF_SD_NAMETOINDEX .

Keywords

COUNT

Set this keyword to a named variable in which the total number of values in the specified attribute is returned.

DATA

Set this keyword to a named variable in which the attribute data is returned.

HDF_TYPE

Set this keyword to a named variable in which the HDF type of the attribute is returned as a scalar string. Possible returned values are DFNT_NONE, DFNT_CHAR, DFNT_FLOAT32, DFNT_FLOAT64, DFNT_INT8, DFNT_INT16, DFNT_INT32, DFNT_UINT8, DFNT_UINT16, and DFNT_UINT32.

NAME

Set this keyword to a named variable in which the name of the attribute is returned.

TYPE

Set this keyword to a named variable in which the IDL type of the attribute is returned as a scalar string. Possible returned values are BYTE, INT, LONG, FLOAT, DOUBLE, STRING, or UNKNOWN.

Example

sd_id = HDF_SD_START('demo.hdf')	;Open an HDF file and start the SD interface.

gindex = HDF_SD_ATTRFIND(sd_id, 'TITLE')	;Find a global attribute

HDF_SD_ATTRINFO, sd_id, gindex, NAME=n, TYPE=t, COUNT=c, $

                 DATA=d, HDF_TYPE=h	;Retrieve attribute info.

HELP, n, t, c, h	;Print information about the returned variables.

IDL prints:

N STRING = 'TITLE'

T STRING = 'STRING'

C LONG = 17

D STRING = '5th Ave Surf Shop'

H STRING = 'DFNT_CHAR'

sds_id = HDF_SD_SELECT(sd_id, 0)	;Return the SD dataset ID for the first dataset (index 0).

dindex = HDF_SD_ATTRFIND(sds_id, 'LOCATION')
;Find a dataset attribute.

HDF_SD_ATTRINFO,SDS_ID, dindex, NAME=n, TYPE=t, COUNT=c, DATA=d
;Retrieve attribute info.

HELP, n, t, c, d	;Print information about the new returned variables.

IDL prints:

N STRING = 'LOCATION'

T STRING = 'STRING'

C LONG = 15

D STRING = 'MELBOURNE BEACH'

See Also

HDF_SD_ATTRFIND, HDF_SD_ATTRSET, HDF_SD_CREATE, HDF_SD_SELECT, HDF_SD_START


HDF_SD_ATTSET
HDF_SD_ATTRSET

The HDF_SD_ATTRSET procedure writes attributes to an open HDF SD dataset. If no data type is specified, the data type is taken from the Values argument.

Calling Sequence

HDF_SD_ATTRSET, S_ID, Attr_Name, Values [, Count]

Arguments

S_ID

An SD interface ID as returned by HDF_SD_START (i.e., a global attribute's "SD_ID"), or HDF_SD_SELECT/HDF_SD_CREATE (i.e., a dataset's "SDS_ID").

Attr_Name

A string containing the name of the attribute to be written.

Values

The attribute values to be written.

Count

An optional integer argument specifying how many items are to be written. Count must be less than or equal to the number of elements in the Values agrument.

Keywords

BYTE

Set this keyword to indicate that the attribute is composed of bytes. Data will be stored with the HDF DFNT_UINT8 data type. Setting this keyword is the same as setting the DFNT_UINT8 keyword.

DFNT_CHAR

Set this keyword to create an attribute of HDF type DFNT_CHAR. Setting this keyword is the same as setting the STRING keyword.

DFNT_FLOAT32

Set this keyword to create an attribute of HDF type DFNT_FLOAT32. Setting this keyword is the same as setting the FLOAT keyword.

DFNT_FLOAT64

Set this keyword to create an attribute of HDF type DFNT_FLOAT64. Setting this keyword is the same as setting the DOUBLE keyword.

DFNT_INT8

Set this keyword to create an attribute of HDF type DFNT_INT8.

DFNT_INT16

Set this keyword to create an attribute of HDF type DFNT_INT16. Setting this keyword is the same as setting either the INT keyword or the SHORT keyword.

DFNT_INT32

Set this keyword to create an attribute of HDF type DFNT_INT32. Setting this keyword is the same as setting the LONG keyword.

DFNT_UINT8

Set this keyword to create an attribute of HDF type DFNT_UINT8. Setting this keyword is the same as setting the BYTE keyword.

DFNT_UINT16

Set this keyword to create an attribute of HDF type DFNT_UINT16.

DFNT_UINT32

Set this keyword to create an attribute of HDF type DFNT_UINT32.

DOUBLE

Set this keyword to indicate that the attribute is composed of double-precision floating-point values. Data will be stored with the HDF DFNT_FLOAT64 data type. Setting this keyword is the same as setting the DFNT_FLOAT64 keyword.

FLOAT

Set this keyword to indicate that the attribute is composed of single-precision floating-point values. Data will be stored with the HDF DFNT_FLOAT32 data type. Setting this keyword is the same as setting the DFNT_FLOAT32 keyword.

INT

Set this keyword to indicate that the attribute is composed of 2-byte integers. Data will be stored with the HDF DFNT_INT16 data type. Setting this keyword is the same as setting either the SHORT keyword or the DFNT_INT16 keyword.

LONG

Set this keyword to indicate that the attribute is composed of longword integers. Data will be stored with the HDF DFNT_INT32 data type. Setting this keyword is the same as setting the DFNT_INT32 keyword.

SHORT

Set this keyword to indicate that the attribute is composed of 2-byte integers. Data will be stored with the HDF DFNT_INT16 data type. Setting this keyword is the same as setting either the INT keyword or the DFNT_INT16 keyword.

STRING

Set this keyword to indicate that the attribute is composed of strings. Data will be stored with the HDF DFNT_CHAR data type. Setting this keyword is the same as setting the DFNT_CHAR keyword.

Example

fid = HDF_OPEN('demo.hdf', /ALL)	;Create a new HDF file.

sd_id = HDF_SD_START('demo.hdf', /RDWR)	;Start the SD interface.

HDF_SD_ATTRSET, sd_id, 'TITLE', 'MY TITLE GLOBAL', 16
;Create a global attribute.

HDF_SD_ATTRSET, sd_id, 'RANGE', [-99.88,55544.2], /DOUBLE
;Create another global attribute.

SDS_ID = HDF_SD_CREATE(sd_id, 'var1', [10,20], /FLOAT)
;Create a dataset.

HDF_SD_ATTRSET, SDS_ID, 'TITLE', 'MY TITLE SD_ID', 15
;Add a dataset attribute.

index=HDF_SD_ATTRFIND(sd_id, 'RANGE')	;Find the recently-created RANGE attribute.

HDF_SD_ATTRINFO,sd_id,index,NAME=atn,COUNT=atc,TYPE=att,DATA=d
;Retrieve data from RANGE.

HELP, atn, atc, att	;Print information about the returned variables.

IDL prints:

ATN STRING = 'RANGE'

ATC LONG = 2

ATT STRING = 'DOUBLE'

PRINT, d, FORMAT='(F8.2,x,F8.2)'	;Print the data returned in variable d with the given format.

IDL prints:

-99.88 55544.20

HDF_SD_ENDACCESS, sds_id	;End access to the HDF file.

HDF_SD_END, sd_id

HDF_CLOSE, fid

See Also

HDF_SD_ATTRFIND, HDF_SD_ATTRINFO, HDF_SD_CREATE, HDF_SD_SELECT


HDF_SD_CREATE

The HDF_SD_CREATE function creates and defines a Scientific Dataset (SD) for an HDF file. Keywords can be set to specify the data type. If no keywords are present a floating-point dataset is created. The returned value of this function is the SDS ID of the newly-created dataset.

Calling Sequence

Result = HDF_SD_CREATE(SD_ID, Name, Dims)

Arguments

SD_ID

An SD ID as returned by HDF_SD_START.

Name

A string containing the name of the variable to be created.

Dims

A 1-based vector specifying the dimensions of the variable. If an UNLIMITED dimension is desired, set the last vector element to zero or a negative number.

Keywords

BYTE

Set this keyword to indicate that the dataset is composed of bytes. Data will be stored with the HDF DFNT_UINT8 data type. Setting this keyword is the same as setting the DFNT_UINT8 keyword.

DFNT_CHAR

Set this keyword to create a data set of HDF type DFNT_CHAR. Setting this keyword is the same as setting the STRING keyword.

DFNT_FLOAT32

Set this keyword to create a data set of HDF type DFNT_FLOAT32. Setting this keyword is the same as setting the FLOAT keyword.

DFNT_FLOAT64

Set this keyword to create a data set of HDF type DFNT_FLOAT64. Setting this keyword is the same as setting the DOUBLE keyword.

DFNT_INT8

Set this keyword to create a data set of HDF type DFNT_INT8.

DFNT_INT16

Set this keyword to create a data set of HDF type DFNT_INT16. Setting this keyword is the same as setting either the INT keyword or the SHORT keyword.

DFNT_INT32

Set this keyword to create a data set of HDF type DFNT_INT32. Setting this keyword is the same as setting the LONG keyword.

DFNT_UINT8

Set this keyword to create a data set of HDF type DFNT_UINT8. Setting this keyword is the same as setting the BYTE keyword.

DFNT_UINT16

Set this keyword to create a data set of HDF type DFNT_UINT16.

DFNT_UINT32

Set this keyword to create a data set of HDF type DFNT_UINT32.

DOUBLE

Set this keyword to indicate that the dataset is composed of double-precision floating-point values. Data will be stored with the HDF DFNT_FLOAT64 data type. Setting this keyword is the same as setting the DFNT_FLOAT64 keyword.

FLOAT

Set this keyword to indicate that the dataset is composed of single-precision floating-point values. Data will be stored with the HDF DFNT_FLOAT32 data type. Setting this keyword is the same as setting the DFNT_FLOAT32 keyword.

INT

Set this keyword to indicate that the dataset is composed of 2-byte integers. Data will be stored with the HDF DFNT_INT16 data type. Setting this keyword is the same as setting either the SHORT keyword or the DFNT_INT16 keyword.

LONG

Set this keyword to indicate that the dataset is composed of longword integers. Data will be stored with the HDF DFNT_INT32 data type. Setting this keyword is the same as setting the DFNT_INT32 keyword.

SHORT

Set this keyword to indicate that the dataset is composed of 2-byte integers. Data will be stored with the HDF DFNT_INT16 data type. Setting this keyword is the same as setting either the INT keyword or the DFNT_INT16 keyword.

STRING

Set this keyword to indicate that the dataset is composed of strings. Data will be stored with the HDF DFNT_CHAR data type. Setting this keyword is the same as setting the DFNT_CHAR keyword.

Example

sd_id = HDF_SD_START('test.hdf', /CREATE)
;Create a new HDF file.

sds_id = HDF_SD_CREATE(sd_id, 'var1', [9,40,0], /SHORT)
;Create an dataset that includes an unlimited dimension.

The example for HDF_SD_ATTRSET also demonstrates the use of this routine.

See Also

HDF_OPEN, HDF_SD_ENDACCESS, HDF_SD_SELECT


HDF_SD_DIMGET

The HDF_SD_DIMGET procedure retrieves information about an SD dataset dimension.

Calling Sequence

HDF_SD_DIMGET, Dim_ID

Arguments

Dim_ID

A dimension ID as returned by HDF_SD _DIMGETID.

Keywords

COUNT

Set this keyword to return the dimension size.

COMPATIBILITY

Set this keyword to a named variable that will contain a string indicating the dimensional compatibility of the current dimension. Possible values are "BW_COMP" (backwards compatible), "BW_INCOMP" (backwards incompatible), or "FAIL" (the information is unavailable). For further information about dimensional compatibilities, see section 3.8.3 "Old and New Dimension Implementations" of the HDF4.0 User's Guide, and the BW_INCOMP keyword of HDF_SD_DIMSET. By default, IDL writes HDF files in "BW_COMP" mode.

FORMAT

Set this keyword to return the dimension format description string.

LABEL

Set this keyword to return the dimension label description string.

NAME

Set this keyword to return the dimension name.

NATTR

Set this keyword to return the number of attributes for the dimension.

SCALE

Set this keyword to return the scale of the dimension.

TYPE

Set this keyword to return a string describing the data's type (i.e., `BYTE').

UNIT

Set this keyword to return the dimension unit description string.

Example

For an example using this routine, see the example for HDF_SD_DIMSET.

See Also

HDF_SD_CREATE, HDF_SD_DIMGETID, HDF_SD_DIMSET, HDF_SD_SELECT


HDF_SD_DIMGETID

The HDF_SD_DIMGETID function returns a dimension ID given a dataset's "SDS_ID" and a dimension number.

Calling Sequence

Result = HDF_SD_DIMGETID(SDS_ID, Dimension_Number)

Arguments

SDS_ID

An SD dataset ID as returned by HDF_SD _SELECT or HDF_SD_CREATE.

Dimension_Number

A zero-based dimension number. The dimension number must be greater than or equal to 0 and less than the maximum dimension number, or rank.

Example

For an example illustrating this routine, see the documentation for HDF_SD_DIMSET.

See Also

HDF_SD_CREATE, HDF_SD_DIMGET, HDF_SD_DIMSET, HDF_SD_SELECT


HDF_SD_DIMSET

The HDF_SD_DIMSET function sets the scale and data strings for an SD dimension.

Calling Sequence

HDF_SD_DIMSET, Dim_ID

Arguments

Dim_ID

A dimension ID as returned by HDF_SD _DIMGETID.

Keywords

BW_INCOMP

Set this keyword to write SD dimensions in the "new" (HDF4.1 and later) style. Versions of HDF prior to HDF4.0 beta 2 were inefficient in the use of SD dimensions. HDF now uses a new internal representation of SD dimensions. If the BW_INCOMP keyword is not set, or is explicitly set equal to zero, the current version of HDF writes SD dimensions in both the pre-HDF4.0 format AND the "new" format. This default behavior is called the BW_COMP dimensional compatibility representation.

Setting the BW_INCOMP keyword causes the current dimension to be written in only the "new" (HDF4.1 and later) format. Depending on your HDF file,using this new format can reduce the size of the HDF by up to a factor of 2, but at the expense of incompatibility with pre HDF4.0 beta 2 applications (IDL version 4, for example). The COMPATIBILITY keyword of HDF_SD_DIMGET can be used to check the dimensional compatibility of an HDF dimension.

Note	Future versions of HDF will recognize only the "new" (BW_INCOMP) dimensional representation.

FORMAT

A string for the dimension format.

LABEL

A string for the dimension label.

NAME

A string for the dimension name.

SCALE

A vector containing the dimension scale values.

UNIT

A string for the dimension unit.

Example

sd_id = HDF_SD_START('myhdf.hdf', /RDWR)
;Initialize the SD interface.

sds_id = HDF_SD_CREATE(sd_id, 'var1', [10,20,0], /LONG)
;Create 3 dimensions.

dim_id=HDF_SD_DIMGETID(sds_id,0)	;Select the first dimension.

HDF_SD_DIMSET, dim_id, NAME='d1', LABEL='l1', $

               FORMAT='f1', UNIT='u1', SCALE=FINDGEN(10)
;Set the data strings and scale for the first dimension.

HDF_SD_DIMGET, dim_id, NAME=d1, LABEL=l1, FORMAT=f1, $

           UNIT=u1, SCALE=sc, COUNT=cnt, NATTR=natt, TYPE=type
;Retrieve the information.

HELP, d1, l1, f1, u1, sc, cnt, natt, type
;Print information about the returned variables.

IDL prints:

D1 STRING = 'd1'

L1 STRING = 'l1'

F1 STRING = 'f1'

U1 STRING = 'u1'

SC FLOAT = Array(10)

CNT LONG = 10

NATT LONG = 3

TYPE STRING = 'FLOAT'

HDF_SD_ENDACCESS,sds_id	;Close the SD interface.

HDF_SD_END, sd_id

See Also

HDF_SD_CREATE, HDF_SD_DIMGET, HDF_SD_DIMGETID, HDF_SD_SELECT


HDF_SD_END

The HDF_SD_END function closes the SD interface to an HDF file. Failure to close the file without a call to HDF_SD_END results in the loss of any changed or added SD data. Therefore, HDF_SD_END calls should always be paired with calls to HDF_SD_START. Before HDF_SD_END is called, all access to SD datasets should be terminated with calls to HDF_SD_ENDACCESS.

Calling Sequence

HDF_SD_END, SD_ID

Arguments

SD_ID

An SD interface ID as returned by HDF _SD_START.

Example

sd_id = HDF_SD_START('test.hdf', /CREATE)
;Open a new HDF file.

...	;Various commands could now be used to access SD data in the HDF file.

HDF_SD_ENDACESS, sds_id_1	;When done with datasets, access should be ended with calls to HDF_SD_ENDACCESS.

HDF_SD_END, sd_id	;When done with an HDF file, it should be closed.

Another example can be seen in the documentation for HDF_SD_ATTRSET.

See Also

HDF_CLOSE, HDF_OPEN, HDF_SD_ENDACCESS, HDF_SD_START


HDF_SD_ENDACCESS

The HDF_SD_ENDACCESS function closes an SD dataset interface. Failure to close the interface can result in the loss of any changed or added SD data. This routine should be called once for each call to HDF_SD_START or HDF_SD_CREATE. After all SD dataset interfaces are closed, the HDF file can safely be closed with HDF_SD_END.

Calling Sequence

HDF_SD_ENDACCESS, SD_ID

Arguments

SDS_ID

An SD dataset ID as returned by HDF_SD_SELECT, or HDF_SD_CREATE.

Example

sd_id = HDF_SD_START('test.hdf', /CREATE)
;Open a new HDF file.

sds_id_1 = HDF_SD_SELECT(sd_id,0)	;Access the HDF file.

HDF_SD_ENDACCESS, sds_id_1	;End access to any SD IDs.

HDF_SD_END, sd_id	;Close the HDF file.

For Also, see the example in HDF_SD_ATTRSET.

See Also

HDF_CLOSE, HDF_OPEN, HDF_SD_CREATE, HDF_SD_ENDACCESS, HDF_SD_START


HDF_SD_FILEINFO

The HDF_SD_FILEINFO procedure retrieves the number of datasets and global attributes in an HDF file.

Calling Sequence

HDF_SD_FILEINFO, SD_ID, Datasets, Attributes

Arguments

SD_ID

An SD interface ID as returned by HDF_SD_START.

Datasets

A named variable in which the total number of SD-type objects (i.e., the number of datasets + the number of dimensions) in the file is returned.

Attributes

A named variable in which the number of global attributes in the file is returned.

Example

sd_id = HDF_SD_START('demo.hdf', /CREATE)
;Start the SD interface.

HDF_SD_ATTRSET,sd_id, 'TITLE', 'MYTITLE'
;Set a global attribute.

HDF_SD_ATTRSET,sd_id, 'TITLE2', 'MYTITLE2'
;Set another one.

sds_id = HDF_SD_CREATE(sd_id, 'var1', [10,3])
;Create a dataset.

HDF_SD_FILEINFO, sd_id, datasets, attributes
;Retrieve info about the dataset.

HELP, datasets, attributes	;Print information about the returned variables.

IDL prints:

DATASETS LONG = 1

ATTRIBUTES LONG = 2

HDF_SD_ENDACCESS, sds_id	;End SD access.

HDF_SD_END, sd_id	;Close the SD interface.

See Also

HDF_SD_ATTRFIND, HDF_SD_ATTRINFO, HDF_SD_START


HDF_SD_GETDATA

The HDF_SD_GETDATA procedure retrieves a hyperslab of values from an SD dataset. By default, the retrieved data is transposed from HDF's column order format into IDL's row order which is more efficient in IDL. To retrieve the dataset without this transposition, set the NOREVERSE keyword.

Calling Sequence

HDF_SD_GETDATA, SDS_ID, Data

Arguments

SDS_ID

An SD dataset ID as returned by HDF_SD _SELECT or HDF_SD_CREATE.

Data

A named variable in which the values are returned.

Keywords

COUNT

Set this keyword to a vector containing the counts, or number of items, to be read. The default is to read all available data.

NOREVERSE

Set the keyword to retrieve the data without transposing the data from column to row order.

START

Set this keyword to a vector containing the starting position for the read. The default start position is [0, 0, ..., 0].

STRIDE

Set this keyword to a vector containing the strides, or sampling intervals, between accessed values of the HDF variable. The default stride vector is that for a contiguous read: [0, 0, ..., 0].

Example

For an example using this routine, see the documentation for HDF_SD_ADDDATA

See Also

HDF_SD_ADDDATA, HDF_SD_GETINFO


HDF_SD_GETINFO

The HDF_SD_GETINFO procedure retrieves information about an SD dataset.

Caution	Reading a label, unit, format, or coordinate system string that has more than 256 characters can have unpredictable results.

Calling Sequence

HDF_SD_GETINFO, SDS_ID

Arguments

SDS_ID

An SD dataset ID as returned by HDF_SD _SELECT or HDF_SD_CREATE.

Keywords

CALDATA

Set this keyword to a named variable in which the calibration data associated with the SD dataset is returned. The data is returned in a structure of the form:

For more information about calibration data, see the documentation for HDF_SD_SETINFO.

COORDSYS

Set this keyword to a named variable in which the coordinate system description string is returned.

DIMS

Set this keyword to a named variable in which the dimensions of the SD dataset are returned. For efficiency, these dimensions are returned in reverse order from their HDF format unless the NOREVERSE keyword is also set.

FILL

Set this keyword to a named variable in which the fill value of the SD dataset is returned. Note that a fill value must be set in the SD dataset. If a fill value is not set, the value of the variable named by this keyword will be undefined, and IDL will issue a warning message.

FORMAT

Set this keyword to a named variable in which the format description string is returned. If the format description string is not present, this variable will contain an empty string.

HDF_TYPE

Set this keyword to a named variable in which the HDF type of the SD dataset is returned as a scalar string. Possible returned values are DFNT_NONE, DFNT_CHAR, DFNT_FLOAT32, DFNT_FLOAT64, DFNT_INT8, DFNT_INT16, DFNT_INT32, DFNT_UINT8, DFNT_UINT16, and DFNT_UINT32.

LABEL

Set this keyword to a named variable in which the label description string is returned. If the label description string is not present, this variable will contain an empty string.

NAME

Set this keyword to a named variable in which the SD dataset name is returned. If the SD dataset name is not present, this variable will contain an empty string.

NATTS

Set this keyword to a named variable in which the number of "NetCDF-style" attributes for the SD dataset is returned.

NDIMS

Set this keyword to a named variable in which the number of dimensions in the dataset is returned.

NOREVERSE

Set this keyword in conjunction with DIMS to return the variable dimensions in non-reversed form. By default, IDL reverses data and dimensions from the HDF format to improve efficiency.

RANGE

Set this keyword to a named variable in which the maximum and minimum of the current SD dataset is returned as a two-element vector. Note that a range must be set in the SD dataset. If the range is not set, the value of the variable named by this keyword will be undefined, and IDL will issue a warning message.

TYPE

Set this keyword to a named variable in which the IDL type of the SD dataset is returned as a scalar string. Possible returned values are BYTE, INT, LONG, FLOAT, DOUBLE, STRING, or UNKNOWN.

UNIT

Set this keyword to a named variable in which the unit description string is returned. If the unit description string is not present, this variable will contain an empty string.

Example

For an example using this routine, see the documentation for HDF_SD_SETINFO.

See Also

HDF_OPEN, HDF_SD_END, HDF_SD_SETINFO, HDF_SD_START


HDF_SD_IDTOREF

The HDF_SD_IDTOREF function converts a SD data set ID into a SD data set reference number. The reference number can be used to add the SD data set to a Vgroup through the HDF_VG interface. The tag number for an SD is 720.

Calling Sequence

Result = HDF_SD_IDTOREF(SDS_ID)

Arguments

SDS_ID

A SDS_ID as returned from HDF_SD_CREATE or HDF_SD_SELECT .

Example

Create an SD data set and get the Reference number.

file_id = HDF_OPEN('demo.hdf', /RDWR)

sd_id = HDF_SD_START('demo.hdf', /RDWR)

dim=[100]

sds_id = HDF_SD_CREATE(sd_id, 'demo_data', dim, /FLOAT)

ref = HDF_SD_IDTOREF(sds_id)

HDF_SD_ADDDATA, sds_id, FINDGEN(100)/10.45 + 2.98

HDF_SD_ENDACCESS, sds_id

HDF_SD_END, sd_id

Use the Reference number to add the SD to a Vgroup ;

SD_TAG = 720

vgID = HDF_VG_GETID(file_id,-1)

vg_handle = HDF_VG_ATTACH(file_id, vgID, /WRITE)

HDF_VG_SETINFO, vg_handle, name='data1', class='demo'

HDF_VG_ADDTR, vg_handle, SD_TAG, ref

Use HDF_VG_INQTR to verify the SD was added correctly :

IF HDF_VG_INQTR(vg_handle, SD_TAG, ref) then $

    PRINT, 'SUCCESS' ELSE PRINT, 'Failure'

IDL prints:

SUCCESS

HDF_VG_DETACH, vg_handle

HDF_CLOSE, file_id

See Also

, , , , , , , , x


HDF_SD_ISCOORDVAR

The HDF_SD_ISCOORDVAR function returns True (1) if the supplied dataset ID represents a NetCDF "coordinate" variable. Otherwise, False (0) is returned.

Calling Sequence

Result = HDF_SD_ISCOORDVAR(SDS_ID)

Arguments

SDS_ID

An SD dataset ID as returned by HDF_SD _SELECT or HDF_SD_CREATE.


HDF_SD_NAMETOINDEX

The HDF_SD_NAMETOINDEX function returns an SD dataset index given its name and SD interface ID. An error message is printed if the dataset cannot be located. The returned index can be used by HDF_SD_SELECT to access an SD dataset.

Calling Sequence

Result = HDF_SD_NAMETOINDEX(SD_ID, SDS_Name)

Arguments

SD_ID

An SD interface ID as returned by HDF_SD_START.

SDS_Name

A string containing the name of the SD dataset be located.

Example

sd_id = HDF_SD_START('demo.hdf')	;Start the SD interface.

index = HDF_SD_NAMETOINDEX(sd_id, 'variable_2')
;Return the index of the `variable_2' dataset.

sds_id=HDF_SD_SELECT(sd_id,index)	;Access the dataset.

HDF_SD_ENDACCESS, sds_id	;End access.

HDF_SD_END, sd_id

See Also

HDF_SD_REFTOINDEX, HDF_SD_SELECT, HDF_SD_START


HDF_SD_REFTOINDEX

The HDF_SD_REFTOINDEX function returns a scientific dataset's index given its reference number and SD interface ID.

Calling Sequence

Result = HDF_SD_REFTOINDEX(SD_ID, Refno)

Arguments

SD_ID

An SD interface ID as returned by HDF_SD_START.

Refno

The SD reference number for the desired dataset.

Example

sd_id = HDF_SDSTART('demo.hdf')	;Initialize the SD interface.

refno = 66	;Define the reference number for which we want to search.

index = HDF_SD_REFTOINDEX(sd_id, refno)	;Return the index number.

sds_id = HDF_SD_SELECT(sd_id, index)	;Now the dataset can be accessed.

HDF_SD_ENDACCESS,SDS_ID	;End access.

HDF_SD_END, sd_id

See Also

HDF_SD_IDTOREF, x


HDF_SD_SELECT

The HDF_SD_SELECT function returns an SD dataset ID given the current SD interface ID, and the zero-based SD dataset index.

HDF_SD_FILEINFO can be used to determine the number of SD datasets in an HDF file, HDF_SD_REFTOINDEX can be used to find the index from its SD dataset ID, and HDF_SD_NAMETOINDEX can be used to find the index from its name.

Calling Sequence

Result = HDF_SD_SELECT(SD_ID, Number)

Arguments

SD_ID

A SD interface ID as returned from HDF _SD_START.

Number

A zero-based SD dataset index.

Example

sd_id = HDF_SD_START('test.hdf')	;Open an HDF file.

sds_id_1=HDF_SD_SELECT(sd_id, 0)	;Access the first SD in the HDF file.

HDF_SD_ENDACCESS, sds_id_1	;End access to any SD ids.

HDF_SD_END, sd_id	;Close the file.

See Also

HDF_SD_CREATE, HDF_SD_END, HDF_SD_ENDACCESS, HDF_SD_NAMETOINDEX, HDF_SD_REFTOINDEX, HDF_SD_SELECT, HDF_SD_START


HDF_SD_SETEXTFILE

The HDF_SD_SETEXTFILE procedure moves data values from a dataset into an external file. Only the data is moved, all other information remains in the original file. This routine can only be used with HDF version 3.3 (and later) files, not on older HDF files or NetCDF files. Data can only be moved once, and the user must keep track of the external file(s). The OFFSET keyword allows writing to an arbitrary location in the external file.

As shown in the example, when adding data to an external file SD, you must first use HDF_SD_ENDACCESS to sync the file, then reacquire the SDS ID with HDF_SD_SELECT before using HDF_SD_SETEXTFILE.

Calling Sequence

HDF_SD_SETEXTFILE, SDS_ID, Filename

Arguments

SDS_ID

An SD dataset ID as returned by HDF_SD_SELECT.

Filename

The name of the external file to be written.

Keywords

OFFSET

Set this keyword to a number of bytes from the beginning of the external file at which data writing should begin. Exercise extreme caution when using this keyword with existing files.

Example

sd_id = HDF_SD_START('ext_main.hdf', /CREATE)
;Create an HDF file.

sds_id = HDF_SD_CREATE(sd_id, 'float_findgen', [3,5], /FLOAT)
;Add an SD.

HDF_SD_ADDDATA, sds_id, FINDGEN(3,5)	;Put some data into the SD.

HDF_SD_ENDACCESS,sds_id	;Call HDF_SD_ENDACCESS to sync the file.

sds_id = HDF_SD_SELECT(sd_id, 0)	;Reacquire the SDS_ID.

HDF_SD_SETEXTFILE, sds_id, 'findgen.hdf'
;Move data to an external file named findgen.hdf.

HDF_SD_GETDATA, sds_id, fout	;Retrieve data from the external file into the variable fout.

PRINT, fout	;Print the contents of fout.

IDL prints:

0.00000 1.00000 2.00000

3.00000 4.00000 5.00000

6.00000 7.00000 8.00000

9.00000 10.0000 11.0000

12.0000 13.0000 14.0000

HDF_SD_ENDACCESS, sds_id	;Sync and close the files.

HDF_SD_END, sd_id

See Also

HDF_SD_END, HDF_SD_ENDACCESS, HDF_SD_SELECT, HDF_SD_START


HDF_SD_SETINFO

The HDF_SD_SETINFO procedure sets information about an SD dataset.

Caution	Setting a label, unit, format, or coordinate system string that has more than 256 characters can have unpredictable results.

Calling Sequence

HDF_SD_SETINFO, SDS_ID

Arguments

SDS_ID

An SD dataset ID as returned by HDF_SD _SELECT or HDF_SD_CREATE.

Keywords

FILL

Set this keyword to the fill value of the SD dataset.

FORMAT

Set this keyword to a string to be used as the SD dataset format.

LABEL

Set this keyword to a string to be used as the SD dataset label.

RANGE

Set this keyword to a two dimensional array that contains the minimum and maximum values of the SD dataset.

UNIT

Set this keyword to a string to be used as the SD dataset units.

COORDSYS

Set this keyword to a string to be used as the SD dataset coordinate system.

CALDATA

Set this keyword to a structure that contains the calibration data. This structure must contain five tags as shown below. The first four tags are of double-precision floating-point type. The fifth tag should be a long integer that specifies the HDF number type. The structure should have the following form:

CALDATA={ Cal: 0.0D $	;Calibration Factor

      Cal_Err: 0.0D $	;Calibration Error

       Offset: 0.0D $	;Uncalibrated Offset

       Offset_Err: 0.0D $	;Uncalibrated Offset Error

       Num_Type: 0L }	;Number Type of Uncalibrated Data

The relationship between HDF and IDL number types is illustrated by the following table:

HDF Number Type	IDL Data Type
0L	UNDEFINED
3L	STRING
21L	BYTE
22L	INTEGER
24L	LONG INTEGER
5L	FLOATING-POINT
6L	DOUBLE-PRECISION
The relationship between the calibrated data (CD) and the uncalibrated data (UD) is given by the equation:

CD = Cal * (UD - Offset)	;Cal and Offset are the values of the Cal and Offset structure fields described above.

Example

sd_id = HDF_SD_START('demo.hdf', /RDWR)
;Open an HDF file.

sds_id = HDF_SD_CREATE(sd_id, 'variable1', [10, 20], /DOUBLE)
;Define a new dataset for the file.

CAL={Cal:1.0D, Cal_Err:0.1D, Offset:2.5D, Offset_Err:0.1D, $

     Num_Type:6L}	;Create a calibration data structure.

HDF_SD_SETINFO, sds_id, LABEL='label1', unit='unit1', $

                format='format1', coordsys='coord1', $

                FILL=999.991, RANGE=[99.99,-78], caldata=CAL
;Set information about the dataset.

HDF_SD_GETINFO, sds_id, LABEL=l, UNIT=u, FORMAT=f, $

                COORDSYS=c, FILL=fill, RANGE=r, CALDATA=cd, $

                NDIMS=ndims, DIMS=dims, TYPE=ty
;Retrieve the information.

HELP, l, u, f, c, fill, r, cd, ndims, dims, ty
;Print information about the returned variables.

IDL prints:

L STRING = `label1'

U STRING = `unit1'

F STRING = `format1'

C STRING = `coord1'

FILL DOUBLE = 999.99103

R DOUBLE = Array(2)

CD STRUCT = -> < Anonymous > Array(1)

NDIMS LONG = 2

DIMS LONG = Array(2)

TY STRING = `DOUBLE'

PRINT, r	;Print the range.

IDL prints:

-78.000000 99.989998

PRINT, cd	;Print the calibration data.

IDL prints:

{ 1.0000000 0.10000000 2.5000000 0.10000000 6}

PRINT, dims	;Print the dimensions.

IDL prints:

10 20

HDF_SD_ENDACCESS, sds_id	;Close the SD interface.

HDF_SD_END, sd_id

See Also

HDF_SD_END, HDF_SD_ENDACCESS, HDF_SD_GETINFO, HDF_SD_START


HDF_SD_START

The HDF_SD_START function opens or creates an HDF file and initializes the SD interface. The returned value of this function is the SD ID of the HDF file. If no keywords are present, the file is opened in read-only mode.

Note that every file opened with HDF_SD_START should eventually be closed with a call to HDF_SD_END.

Calling Sequence

Result = HDF_SD_START(Filename)

Arguments

Filename

A scalar string containing the name of the file to be opened or created. HDF_SD_START can open the following file types: XDR-based NetCDF files, "old-style" DFSD files, or "new-style" SD files. New files are created as "new-style" SD files.

Keywords

READ

Set this keyword to open the SD interface in read-only mode. If no keywords are specified, this is the default behavior.

RDWR

Set this keyword to open the SD interface in read and write mode.

CREATE

Set this keyword to create a new SD file.

Example

sd_id = HDF_SD_START('test.hdf', /CREATE)
;Open a new HDF file. The file is ready to be accessed.

HDF_SD_END, sd_id	;When finished with the file, close it with a call to HDF_SD_END.

For a more complicated example, see the documentation for HDF_SD_ATTRSET.

See Also

HDF_CLOSE, HDF_OPEN, HDF_SD_ATTRFIND, HDF_SD_ATTRINFO, HDF_SD_ATTRSET, HDF_SD_CREATE, HDF_SD_END, HDF_SD_FILEINFO, HDF_SD_NAMETOINDEX, HDF_SD_REFTOINDEX, HDF_SD_SELECT, HDF_SD_SETEXTFILE


HDF_VD_ATTACH

The HDF_VD_ATTACH function accesses a VData with the given Id in a Hierarchical Data Format file. If successful, a handle for that VData is returned, otherwise 0 is returned.

Calling Sequence

Result = HDF_VD_ATTACH(Filehandle, VDataId)

Arguments

Filehandle

The HDF file handle returned from a previous call to HDF_OPEN.

VDataId

The VData reference number, usually obtained by HDF_VD_GETID or HDF_VD_LONE. Set this argument to -1 to create a new VData.

Keywords

READ

Set this keyword to open the VData for reading. This is the default.

WRITE

Set this keyword to open the VData for writing. If VDataID is set equal to -1, the file is opened for writing whether or not this keyword is set.


HDF_VD_DETACH

The HDF_VD_DETACH procedure is called when done accessing a VData in a Hierarchical Data Format file. This routine must be called for every VData attached for writing before closing the HDF file to insure that VSET information is properly updated.

Calling Sequence

HDF_VD_DETACH, VData

Arguments

VData

The VData handle returned by a previous call to HDF_VD_ATTACH.


HDF_VD_FDEFINE

The HDF_VD_FDEFINE procedure adds a new field specification for a VData in a Hierarchical Data Format file. HDF_VD_FDEFINE can only be used for a new VData.

Calling Sequence

HDF_VD_FDEFINE, VData, Fieldname

Arguments

VData

The VData handle returned by a previous call to HDF_VD_ATTACH.

Fieldname

A string containing the new field name.

Keywords

BYTE

Set this keyword to indicate that the field will contain 8-bit unsigned integer data.

DOUBLE

Set this keyword to indicate that the field will contain 64-bit floating point data.

FLOAT

Set this keyword to indicate that the field will contain 32-bit floating point data.

INT

Set this keyword to indicate that the field will contain 16-bit integer data.

LONG

Set this keyword to indicate that the field will contain 32-bit integer data.

ORDER

This keyword specifies the number of distinct components in the new field. Compound variables have an order greater than 1. The default order is 1.

Example

HDF_VD_FDEFINE, vid, 'VEL', /DOUBLE, ORDER=3


HDF_VD_FEXIST

The HDF_VD_FEXIST function returns true if all the fields specified in Fieldname exist in the specified Hierarchical Data Format file.

Calling Sequence

Result = HDF_VD_FEXIST(VData, Fieldnames)

Arguments

VData

The VData handle returned by a previous call to HDF_VD_ATTACH.

Fieldnames

A string containing a comma-separated list of fields to test. For example 'VEL' or 'PZ,PY,PX'.


HDF_VD_FIND

The HDF_VD_FIND function returns the reference number of a VData with the specified name in a Hierarchical Data Format file. A 0 is returned if an error occurs or a VData of the given name does not exist.

Calling Sequence

Result = HDF_VD_FIND(Filehandle, Name)

Arguments

Filehandle

The HDF file handle returned from a previous call to HDF_OPEN.

Name

A string containing the name of the VData to be found.


HDF_VD_GET

The HDF_VD_GET procedure is a general VData inquiry routine. Set the various keywords to named variables to return information about a VData in a Hierarchical Data Format file.

Calling Sequence

HDF_VD_GET, VData

Arguments

VData

A VData handle returned by HDF_VD_ATTACH.

Keywords

CLASS

Set this keyword to a named variable in which the class name of the VData is returned as a string.

COUNT

Set this keyword to a named variable in which a long, containing the number of records in the VData, is returned.

FIELDS

Set this keyword to a named variable in which a comma-separated string of fields in the VData is returned (e.g., 'PX,PY,PZ')

The maximum number of fields is 256 (except on the Macintosh, where it is 64). Each field can be up to 128 characters in length. The returned fields may or may not contain buffering whitespace depending on how the HDF file was created.

INTERLACE

Set this keyword to a named variable in which a string, containing either 'FULL_INTERLACE' or 'NO_INTERLACE', is returned.

NAME

Set this keyword to a named variable in which a string, containing the name of the VData, is returned.

NFIELDS

Set this keyword to a named variable in which a long, containing the number of fields in the VDATA, is returned. For example, the VData containing the fields "PX,PY,PZ", has an NFIELDS of 3.

REF

Set this keyword to a named variable in which the reference number of the VData is returned.

SIZE

Set this keyword to a named variable in which a long, containing the local size of a record of VData, is returned.

TAG

Set this keyword to a named variable in which the tag number of the VData is returned.

Example

HDF_VD_GET, vdat, CLASS=c, COUNT=co, FIELDS=f, NAME=n, SIZE=s

See Also

HDF_VD_GETINFO, HDF_VG_GETINFO


HDF_VD_GETID

The HDF_VD_GETID function returns the VData reference number for the next VData in a Hierarchical Data Format file after the specified VDataId.

Set VDataId to -1 to return the first VData ID in the file.

Calling Sequence

Result = HDF_VD_GETID(Filehandle, VDataId)

Arguments

Filehandle

The HDF file handle returned by a previous call to HDF_OPEN.

VDataID

The VData reference number, generally obtained by HDF_VD_GETID or HDF_VD_LONE. Set this argument to -1 to return the first VData in the file.


HDF_VD_GETINFO

The HDF_VD_GETINFO procedure is a general VData inquiry routine. Set the various keywords to named variables to return information about each field of a VData in a Hierarchical Data Format file.

Calling Sequence

HDF_VD_GETINFO, VData, Index

Arguments

VData

The VData handle returned by a previous call to HDF_VD_ATTACH.

Index

A zero-based index specifying which field or the name of the field within the VData to inquire about. For example:

HDF_VD_GETINFO, Vdat, 'VEL', ORDER=order

Keywords

NAME

Set this keyword to a named variable in which the name of the field is returned as a string.

ORDER

Set this keyword to a named variable in which the order of the field is returned.

SIZE

Set this keyword to a named variable in which the size of a data value for the specified field in the VData is returned.

TYPE

Set this keyword to a named variable in which the type of the field is returned. One of the following strings is returned: 'BYTE', 'INT', 'LONG', 'FLOAT', 'DOUBLE'.

Example

HDF_VD_GET, Vdat, NFIELDS=n

FOR index=0,n-1 DO BEGIN

  HDF_VD_GETINFO, Vdat, index, NAME=n, TYPE=t, ORDER=o

  PRINT, index, ':', n, 'TYPE=', t, 'ORDER=', o

ENDFOR


HDF_VD_GETNEXT

The HDF_VD_GETNEXT function returns the reference number of the next object inside a VData in a Hierarchical Data Format file. If Id is -1, the first item in the VData is returned, otherwise Id should be set to a reference number previously returned by HDF_VD_GETNEXT. HDF_VD_GETNEXT returns -1 if there was an error or there are no more objects after the one specified by Id.

Calling Sequence

Result = HDF_VD_GETNEXT(VData, Id)

Arguments

VData

The VData handle returned by a previous call to HDF_VD_ATTACH.

Id

A VGroup or VData reference number obtained by a previous call to HDF_VG_GETNEXT or HDF_VD_GETNEXT. Alternatively, this value can be set to -1 to return the first item in the VData.


HDF_VD_INSERT

The HDF_VD_INSERT procedure adds a VData or VGroup to the contents of a VGroup in a Hierarchical Data Format file.

Calling Sequence

HDF_VD_INSERT, VGroup, VData

Arguments

VGroup

The VGroup handle returned by a previous call to HDF_VG_ATTACH.

VData

The VData (or VGroup) handle returned by HDF_VD_ATTACH (HDF_VG_ATTACH).


HDF_VD_ISVD

The HDF_VD_ISVD function returns True (1) if the object associated with Id is a VData in a Hierarchical Data Format file.

Calling Sequence

Result = HDF_VD_ISVD(VGroup, Id)

Arguments

VGroup

The VGroup handle returned by a previous call to HDF_VG_ATTACH.

Id

The VGroup or VData reference number obtained by a previous call to HDF_VG_GETNEXT or HDF_VD_GETNEXT.

Example

Vid = HDF_VD_GETNEXT(Vgrp, -1)

PRINT, HDF_VD_ISVD(VGrp, Vid)


HDF_VD_ISVG

The HDF_VD_ISVG function returns True (1) if the object associated with Id is a VGroup in a Hierarchical Data Format file.

Calling Sequence

Result = HDF_VG_ISVG(VGroup, Id)

Arguments

VGroup

The VGroup handle returned by a previous call to HDF_VG_ATTACH.

Id

The VGroup or VData reference number obtained by a previous call to HDF_VG_GETNEXT.

Example

Vid = HDF_VD_GETNEXT(Vgrp, -1)

PRINT, HDF_VD_ISVG(VGrp, Vid)


HDF_VD_LONE

The HDF_VD_LONE function returns an array containing all VDatas in a Hierarchical Data Format file that are not contained in another VData. If there are no lone VDatas, HDF_VD_LONE returns -1.

Calling Sequence

Result = HDF_VD_LONE(Filehandle)

Arguments

Filehandle

The HDF file handle returned from a previous call to HDF_OPEN.

Keywords

MAXSIZE

The maximum number of groups to be returned (the default is to return all known lone VDatas). For example, to return only the first 12 groups:

X = HDF_VD_LONE(fid, MAX=12)

Example

X = HDF_VD_LONE(fid)

IF N_ELEMENTS(X) EQ 0 THEN $

PRINT, 'No Lone VDatas' ELSE PRINT, 'Lone VDatas:', X


HDF_VD_READ

The HDF_VD_READ function reads data from a VData in a Hierarchical Data Format file. This function returns the number of records successfully read from the VData.

The default is to use FULL_INTERLACE and to read all fields in all records. The user can override the defaults with keywords. If multiple fields with different data types are read, all of the data is read into a byte array. The data must then be explicitly converted back into the correct type(s) using various IDL type conversion routines. For example:

nread = HDF_VD_READ(vdat, x, NREC=1, FIELDS="FLT,LNG")

floatvalue = FLOAT(x, 0)

longvalue = LONG(x, 4)

Calling Sequence

Result = HDF_VD_READ(VData, Data)

Arguments

VData

The VData handle returned by a previous call to HDF_VD_ATTACH.

Data

A named variable in which the data is returned.

Keywords

FIELDS

A string containing a comma-separated list of fields to be read. Normally HDF_VD_READ will read all fields in the VData.

FULL_INTERLACE

Set this keyword to use full interlace when reading (the default).

NO_INTERLACE

Set this keyword to use no interlace when reading.

NRECORDS

The number of records to read. By default, HDF_VD_READ reads all records from a VData.

Examples

Typical read:

NREC = HDF_VD_READ(Vdat, X)

Read one field:

NREC = HDF_VD_READ(Vdat, X, FIELDS='VEL')

Read a record:

NREC = HDF_VD_READ(Vdat, X, NRECORDS=1)


HDF_VD_SEEK

The HDF_VD_SEEK procedure moves the read pointer within the specified VData in a Hierarchical Data Format file to a specific record number. Note that the record number is zero-based.

Calling Sequence

HDF_VD_SEEK, VData, Record

Arguments

VData

A VData handle returned by HDF_VD_ATTACH.

Record

The zero-based record number to seek.


HDF_VD_SETINFO

The HDF_VD_SETINFO procedure specifies general information about a VData in a Hierarchical Data Format file. Keywords can be used to establish the name, class, and interlace for the specified VData.

Calling Sequence

HDF_VD_SETINFO, VData

Arguments

VData

The VData handle returned by a previous call to HDF_VD_ATTACH.

Keywords

CLASS

A string that sets the class name for the VData.

FULL_INTERLACE

Set this keyword to store data in the file with full interlace (i.e., sequentially by record).

NAME

A string that sets the name of the VData.

NO_INTERLACE

Set this keyword to store data in the file with no interlace (i.e., sequentially by field).

Example

HDF_VD_SETINFO, Vdat, NAME='My Favorite Data', /FULL


HDF_VD_WRITE

The HDF_VD_WRITE procedure stores data in a VData in a Hierarchical Data Format file.

There are many restrictions on writing data to a VData. When writing multiple fields of varying types, only limited error checking is possible. When writing a series of fields all with the same type, data is converted to that type before writing. For example:

Vdat = HDF_VD_ATTACH(Fid, -1, /WRITE)

Data = INDGEN(10)	;Create a 10 integer vector.

HDF_VD_WRITE, Vdat, 'PX', Data	;Data converted to FLOAT before write.

It is possible to write less data than exists in Data by using the NRECORDS keyword. For example, the following command writes 5 records, instead of the 10 implied by the size of the data (VEL is assumed to be of type FLOAT, order=3):

HDF_VD_WRITE, Vdat, 'VEL', FINDGEN(3,10),NREC=5

VEL now contains [ [ 0.0, 1.0, 2.0 ], ..., [ 12.0, 13.0, 14.0] ]

HDF_VD_WRITE will not allow a user to specify more records than exist. For example, the following command fails:

HDF_VD_WRITE, Vdat, 'VEL', [1,2,3], NREC=1000

Bugs

Data can not be appended. Attempts to append data may make future attempts to read data fail. Data can not be overwritten.

Calling Sequence

HDF_VD_WRITE, VData, Fields, Data

Arguments

VData

The VData handle returned by a previous call to HDF_VD_ATTACH.

Fields

A string containing a comma-separated list of the fields to be written.

Data

The data to be written to the specified VData.

Keywords

FULL_INTERLACE

Set this keyword to use full interlace when writing (the default).

NO_INTERLACE

Set this keyword to use no interlace when writing.

NRECORDS

The number of records to written. By default, HDF_VD_WRITE writes all records from a VData.

Restrictions

It is not possible to write IDL structures directly to a VData (because of possible internal padding depending upon fields/machine architecture, etc.). The user must put the data into a byte array before using HDF_VD_WRITE.

When writing a series of fields all with the same type, the low order dimension of Data must match the sum of the orders of the fields. For example:

HDF_VD_WRITE, Vdat, 'PX,PY', FLTARR(3,10)

fails. PX and PY are both order 1 (total 2) and the array's low order dimension is 3.


HDF_VG_ADDTR

The HDF_VG_ADDTR procedure adds a tag and reference to the specified VGroup in a Hierarchical Data Format file.

Calling Sequence

HDF_VG_ADDTR, VGroup, Tag, Ref

Arguments

VGroup

The VGroup handle returned by a previous call to HDF_VG_ATTACH.

Tag

The tag to be written.

Ref

The reference number to be written.

Example

See "HDF_SD_IDTOREF" on page 170 for an example using this function.

See Also

HDF_VG_GETTR, HDF_VG_GETTRS, HDF_VG_INQTR, HDF_VG_INSERT


HDF_VG_ATTACH

The HDF_VG_ATTACH procedure attaches (opens) a VGroup in a Hierarchical Data Format file for reading or writing. If successful, a handle for that group is returned. If it fails, 0 is returned.

If VGroupId is set to -1, a new VGroup is created. If neither the READ nor WRITE keywords are set, the VGroup is opened for reading.

Calling Sequence

Result = HDF_VG_ATTACH(Filehandle, VGroupId)

Arguments

Filehandle

The HDF file handle returned from a previous call to HDF_OPEN.

VGroupId

The VGroup reference number, generally obtained by HDF_VG_GETID or HDF_VG_LONE.

Keywords

READ

Set this keyword to open the VGroup for reading.

WRITE

Set this keyword to open the VGroup for writing.

Example

See "HDF_SD_IDTOREF" on page 170 for an example using this function.


HDF_VG_DETACH

The HDF_VG_DETACH procedure should be called when you are finished accessing a VGroup in a Hierarchical Data Format file. This routine must be called for every VGroup attached for writing before closing the HDF file in order to insure that VSET information is properly updated.

Calling Sequence

HDF_VG_DETACH, VGroup

Arguments

VGroup

The VGroup handle returned by a previous call to HDF_VG_ATTACH.

Example

See "HDF_SD_IDTOREF" on page 170 for an example using this function.


HDF_VG_GETID

The HDF_VG_GETID function returns the VGroup ID for the next VGroup after the specified VGroupId in a Hierarchical Data Format file. Use a VGroupId of -1 to get the first VGroup in the file.

Calling Sequence

Result = HDF_VG_GETID(Filehandle, VGroupId)

Arguments

Filehandle

The HDF file handle returned from a previous call to HDF_OPEN.

VGroupID

The VGroup reference number, generally obtained by HDF_VG_GETID or HDF_VG_LONE.

Example

See "HDF_SD_IDTOREF" on page 170 for an example using this function.


HDF_VG_GETINFO

The HDF_VG_GETINFO procedure is a general VGroup inquiry routine. Set the various keywords to named variables to return information about different aspects of a VGroup in a Hierarchical Data Format file.

Calling Sequence

HDF_VG_GETINFO, VGroup

Arguments

VGroup

The VGroup handle returned by a previous call to HDF_VG_ATTACH.

Keywords

CLASS

Set this keyword to a named variable in which the class of the VGroup is returned as a string.

NAME

Set this keyword to a named variable in which the name of the VGroup is returned as a string.

NENTRIES

Set this keyword to a named variable in which the number of objects inside the VGroup is returned as a long integer.

Example

HDF_VG_GETINFO, Vgrp, CLASS=c, NAME=nm, NENTRIES=n

PRINT, c, nm, n


HDF_VG_GETNEXT

The HDF_VG_GETNEXT function returns the reference number of the next object inside a VGroup in a Hierarchical Data Format file. If Id is -1, the first item in the VGroup is returned, otherwise Id should be set to a reference number previously returned by HDF_VG_GETNEXT. HDF_VG_GETNEXT returns -1 if there was an error or there are no more objects after the one specified by Id.

Calling Sequence

Result = HDF_VG_GETNEXT(VGroup, Id)

Arguments

VGroup

The VGroup handle returned by a previous call to HDF_VG_ATTACH.

Id

A VGroup or VData reference number obtained by a previous call to HDF_VG_GETNEXT. Alternatively, this value can be set to -1 to return the first item in the VGroup.


HDF_VG_GETTR

The HDF_VG_GETTR procedure returns the tag/reference pair at the specified position within a VGroup in a Hierarchical Data Format file.

Calling Sequence

HDF_VG_GETTR, VGroup, Index, Tags, Refs

Arguments

VGroup

The VGroup handle returned by a previous call to HDF_VG_ATTACH.

Index

The position within VGroup.

Tags

A named variable in which the tag numbers are returned.

Refs

A named variable in which the reference numbers are returned.


HDF_VG_GETTRS

The HDF_VG_GETTRS procedure returns the tag/reference pairs of the Hierarchical Data Format file objects belonging to the specified VGroup.

Calling Sequence

HDF_VG_GETTRS, VGroup, Tags, Refs

Arguments

VGroup

The VGroup handle returned by a previous call to HDF_VG_ATTACH.

Tags

A named variable in which the tag numbers are returned.

Refs

A named variable in which the reference numbers are returned.

Keywords

MAXSIZE

The maximum number of tags and references to be returned. The default is to return all tags and references in VGroup.


HDF_VG_INQTR

The HDF_VG_INQTR function returns true if the specified tag and reference pair is linked to the specified VGroup in a Hierarchical Data Format file.

Calling Sequence

Result = HDF_VG_INQTR(VGroup, Tag, Ref)

Arguments

VGroup

The VGroup handle returned by a previous call to HDF_VG_ATTACH.

Tag

The tag number.

Ref

The reference number.

Example

See "HDF_SD_IDTOREF" on page 170 for an example using this function.


HDF_VG_INSERT

The HDF_VG_INSERT procedure adds a VData or VGroup to the contents of a VGroup in a Hierarchical Data Format file.

Calling Sequence

HDF_VG_INSERT, VGroup, VData

Arguments

VGroup

The VGroup handle returned by a previous call to HDF_VG_ATTACH.

VData

The VData (or VGroup) handle returned by HDF_VD_ATTACH (HDF_VG_ATTACH).


HDF_VG_ISVD

The HDF_VG_ISVD function returns true if the object associated with Id is a VData in a Hierarchical Data Format file.

Calling Sequence

Result = HDF_VG_ISVD(VGroup, Id)

Arguments

VGroup

The VGroup handle returned by a previous call to HDF_VG_ATTACH.

Id

The VGroup or VData reference number obtained by a previous call to HDF_VG_GETNEXT.

Example

Vid = HDF_VG_GETNEXT(Vgrp, -1)

PRINT, HDF_VG_ISVD(VGrp, Vid)


HDF_VG_ISVG

The HDF_VG_ISVG function returns true if the object associated the Id is a VGroup in a Hierarchical Data Format file.

Calling Sequence

Result = HDF_VG_ISVG(VGroup, Id)

Arguments

VGroup

The VGroup handle returned by a previous call to HDF_VG_ATTACH.

Id

The VGroup or VData reference number obtained by a previous call to HDF_VG_GETNEXT.

Example

Vid = HDF_VG_GETNEXT(Vgrp, -1)

PRINT, HDF_VG_ISVG(VGrp, Vid)


HDF_VG_LONE

The HDF_VG_LONE function returns an array containing the IDs of all VGroups in a Hierarchical Data Format file that are not contained in another VGroup. If there are no lone VGroups, HDF_VG_LONE returns -1.

Calling Sequence

Result = HDF_VG_LONE(Filehandle)

Arguments

Filehandle

The HDF file handle returned by a previous call to HDF_OPEN.

Keywords

MAXSIZE

The maximum number of groups to return (the default is to return all lone VGroups). For example, to return no more than 12 VGroups, use the command:

X = HDF_VG_LONE(fid, MAX=12)

Example

X=HDF_VG_LONE(fid)

IF X(0) EQ-1 THEN $

   PRINT, "No Lone VGroups" ELSE PRINT, "Lone VGroups:", X


HDF_VG_NUMBER

The HDF_VG_NUMBER function returns the number of Hierarchical Data Format file objects in the specified VGroup.

Calling Sequence

Result = HDF_VG_NUMBER(VGroup)

Arguments

VGroup

The VGroup handle returned by a previous call to HDF_VG_ATTACH.


HDF_VG_SETINFO

The HDF_VG_SETINFO procedure sets the name and class of a VGroup.

Calling Sequence

HDF_VG_SETINFO, VGroup

Arguments

VGroup

The VGroup handle as returned by HDF_VG _ATTACH.

Keywords

CLASSNAME

A string containing the class name for the VGroup.

NAME

A string containing the name for the VGroup.

Example

fid = HDF_OPEN('demo.hdf',/RDWR)	;Open an HDF file.

vgid = HDF_VG_ATTACH(fid, -1, /WRITE)	;Add a new VGroup.

HDF_VG_SETINFO, vgid, NAME='My Name', CLASS='My VGroup Class'
;Set the name and class for the VGroup.

Now retrieve and show the information

HDF_VG_GETINFO, vgid, NAME=outname, CLASS=outclass
;Retrieve the name and class information from the file.

HELP, outname, outclass	;Print information about the returned variables.

IDL prints:

OUTNAME STRING = 'My Name'

OUTCLASS STRING = 'My VGroup Class'

HDF_VG_DETACH, vgid	;End VGroup access.

HDF_CLOSE, fid	;Close the HDF file.

See Also

HDF_VG_GETINFO


Network Common Data Format

This chapter details the interface routines for the Network Common Data Format. General notes about the interface are presented below, followed by individual descriptions of the routines. This version of IDL supports netCDF 2.4.

NetCDF Data Modes

There are two modes associated with accessing a netCDF file: define mode and data mode. In define mode, dimensions, variables, and new attributes can be created but variable data cannot be read or written. In data mode, data can be read or written and attributes can be changed, but new dimensions, variables, and attributes cannot be created.

IDL's NCDF_CONTROL routine can be used control the mode of a netCDF file. The only time it is not necessary to set the mode with NCDF_CONTROL is when using the NCDF_CREATE procedure to create a new file. NCDF_CREATE places the new netCDF file into define mode automatically.

Attributes, Dimensions, and Variables

The three basic components of a netCDF file are described below.

Attributes

Attributes can contain auxiliary information about an entire netCDF file (global attributes) or about a single netCDF variable. Every attribute has a name, data type, and length associated with it. It is common to repeat attribute names for each variable. For example, every variable in a netCDF file might have an attribute named "Units". Note however, that variables cannot have multiple attributes with the same names.

Dimensions

Dimensions are named integers that are used to specify the size (or dimensionality) of one or more variables. Each dimension must have a unique name, but a variable and dimension can share a name. Each netCDF file is allowed to have one boundless (or unlimited) dimension. Most often the unlimited dimension is used as a temporal variable, allowing data to be appended to an existing netCDF file. An example of this use is shown later.

Variables

Variables are multidimensional arrays of values of the same data type. Each variable has a size, type, and name associated with it. Variables can also have attributes that describe them.

Creating NetCDF Files

The following IDL commands should be used to create a new netCDF file:

•	NCDF_CREATE: Call this procedure to begin creating a new file. The new file is put into define mode.

•	NCDF_DIMDEF: Create dimensions for the file.

•	NCDF_VARDEF: Define the variables to be used in the file.

•	NCDF_ATTPUT: Optionally, use attributes to describe the data.

•	NCDF_CONTROL, /ENDEF: Call NCDF_CONTROL and set the ENDEF keyword to leave define mode and enter data mode.

•	NCDF_VARPUT: Write the appropriate data to the netCDF file.

•	NCDF_CLOSE: Close the file.

Reading NetCDF Files

The following commands should be used to read data from a netCDF file:

•	NCDF_OPEN: Open an existing netCDF file.

•	NCDF_INQUIRE: Call this function to find the format of the netCDF file.

•	NCDF_DIMINQ: Retrieve the names and sizes of dimensions in the file.

•	NCDF_VARINQ: Retrieve the names, types, and sizes of variables in the file.

•	NCDF_ATTNAME: Optionally, retrieve attribute names.

•	NCDF_ATTINQ: Optionally, retrieve the types and lengths of attributes.

•	NCDF_ATTGET: Optionally, retrieve the attributes.

•	NCDF_VARGET: Read the data from the variables.

•	NCDF_CLOSE: Close the file.

If the structure of the netCDF file is already known, the inquiry routines do not need to be called—only NCDF_OPEN, NCDF_ATTGET, NCDF_VARGET, and NCDF_CLOSE would be needed.

NetCDF Examples

Two example files that demonstrate the use of the netCDF routines can be found in the hdf_ncdf subdirectory of the examples subdirectory of the IDL distribution. The file nncdf_cat.pro prints a summary of basic information about a netCDF file. The file ncdf_rdwr.pro creates a new netCDF file and then reads the information back from that file.

A Complete Example with Unlimited Dimensions

The following example shows how to create a netCDF file, populate it with data, read data from the file, and make a simple plot from the data.The resulting graphic is shown below.

id = NCDF_CREATE('inquire.nc', /CLOBBER)
;Create a new NetCDF file with the filename inquire.nc.

NCDF_CONTROL, id, /FILL	;Fill the file with default values.

hours = INDGEN(5)	;We'll create some time-dependant data, so here is an array of hours from 0 to 5.

data = FLTARR(5,10)	;Create a 5 by 10 array to hold floating-point data.

FOR i=0,9 DO $	;Generate some values.

    data(*,i) = (i+0.5) * EXP(-hours/2.) / SIN((i+1)/30.*!PI)

xid = NCDF_DIMDEF(id, 'x', 10)	;Make dimensions.

zid = NCDF_DIMDEF(id, 'z', /UNLIMITED)

hid = NCDF_VARDEF(id, 'Hour', [zid], /SHORT)
;Define variables.

vid = NCDF_VARDEF(id, 'Temperature', [xid,zid], /FLOAT)
;Define variable.

NCDF_ATTPUT, id, vid, 'units', 'Degrees x 100 F'

NCDF_ATTPUT, id, vid, 'long_name', 'Warp Core Temperature'

NCDF_ATTPUT, id, hid, 'long_name', 'Hours Since Shutdown'

NCDF_ATTPUT, id, /GLOBAL, 'Title', 'Really important data'

NCDF_CONTROL, id, /ENDEF	;Put file in data mode.

NCDF_VARPUT, id, hid, hours 	;Input data.

FOR i=0,4 DO NCDF_VARPUT, id, vid, $

    REFORM(data(i,*)), OFFSET=[0,i]	;Oops! We forgot the 6th hour! This is not a problem, however, as you can dynamically expand a netCDF file if the unlimited dimension is used.

NCDF_VARPUT, id, hid, 6, OFFSET=[5]	;Add the hour and data.

NCDF_VARPUT, id, vid, FINDGEN(10)*EXP(-6./2), OFFSET=[0,5]
;Add the temperature.

NCDF_VARGET, id, vid, output_data	;Read the data back out.

NCDF_ATTGET, id, vid, 'long_name', ztitle

NCDF_ATTGET, id, hid, 'long_name', ytitle

NCDF_ATTGET, id, vid, 'units', subtitle

!P.CHARSIZE = 2.5

!X.TITLE = 'Location'

!Y.TITLE = STRING(ytitle)	;Convert from bytes to strings.

!Z.TITLE = STRING(ztitle) + '!C' + STRING(subtitle)

NCDF_CLOSE, id	;Close the NetCDF file.

SHOW3, output_data	;Display the data.

Type Conversion

Values are converted to the appropriate type before being written to a netCDF file. For example, in the commands below, IDL converts the string "12" to a floating-point 12.0 before writing it:

varid=NCDF_VARDEF(fileid, 'VarName', [d0,d1,d2+d3], /FLOAT)

NCDF_VARPUT, fileid, 'VarName', '12'

Specifying Attributes and Variables

Variables and attributes can be referred to either by name or by their ID numbers in most netCDF routines. For example, given the NCDF_VARDEF command shown below, the two NCDF_VARPUT commands shown after it are equivalent:

varid = NCDF_VARDEF(fileid, 'VarName', [d0,d1,d2+d3], /FLOAT)

NCDF_VARPUT, fileid, 'VarName', '12'
;Reference by variable name.

NCDF_VARPUT, fileid, varid,'12'	;Reference by variable ID.

String Data in NetCDF Files

Strings are stored as arrays of ASCII bytes in netCDF files. To read string data from netCDF files, use the STRING function to convert bytes back into characters. When writing an IDL string array to a variable, an extra dimension (the maximum string length) must be added to the variable definition. Both of these situations are illustrated by the following example:

string_in = REPLICATE('Test String',10,10)
;Make a test string

string_in(0,0) = 'Long Test String'	;Make one element longer than the others.

HELP, string_in	;IDL reports:
STRING_IN    STRING  = Array(10, 10)

ncdfid = NCDF_CREATE('string.nc', /CLOBBER)
;Create a new netCDF file.

xid = NCDF_DIMDEF(ncdfid, 'height', 10)
;Define first dimension.

yid = NCDF_DIMDEF(ncdfid, 'width', 10)
;Define second dimension.

zid = NCDF_DIMDEF(ncdfid, 'length', MAX(STRLEN(string_in)))
;Find the length of the longest string and use that as the third dimension.

id = NCDF_VARDEF(ncdfid, 'strings', [zid,yid,xid], /CHAR)
;Define the variable with dimensions zid, yid, xid.

NCDF_CONTROL, ncdfid, /ENDEF	;Put the file into define mode.

NCDF_VARPUT, ncdfid, id, string_in	;Write the string variable. The array will be stored as bytes in the file.

NCDF_VARGET, ncdfid, id, byte_out	;Read the byte array back out.

NCDF_CLOSE, ncdfid	;Close the file.

HELP, byte_out	;IDL reports that BYTE_OUT is a (16, 10, 10) BYTE array.

PRINT, STRING(byte_out(*,0,0))	;Taking the STRING of the first "row" of byte_out returns the first element of our original array, "Long Test String".

string_new = STRING(byte_out)	;Convert the entire byte array back into strings.

HELP, string_new	;The new string array has the same dimensions and values as our original string, string_in.

IF TOTAL(string_in NE string_new) EQ 0 THEN PRINT, 'Success!'
;This statement compares the two arrays and prints "Success!" if they are equal—and they are.


NCDF_ATTCOPY

The NCDF_ATTCOPY function copies an attribute from one netCDF file to another. Note that Incdf and Outcdf can be the same netCDF ID. NCDF_ATTCOPY returns the attribute number of the copied attribute in the new file, or -1 if the copy was not successful.

Calling Sequence

Result = NCDF_ATTCOPY(Incdf, [Invar,] Name, Outcdf, [Outvar])

Arguments

Incdf

The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

Invar

The netCDF variable ID to be read, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable. If the IN_GLOBAL keyword is set, this argument must be omitted.

Name

A scalar string containing the name of the attribute to be copied.

Outcdf

The netCDF ID of a netCDF file opened for writing, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

Outvar

The netCDF variable ID to be written, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable. If the OUT_GLOBAL keyword is set, this argument must be omitted.

Keywords

IN_GLOBAL

Set this keyword to read a global attribute.

OUT_GLOBAL

Set this keyword to create a global attribute.

Example

See example from "NCDF_ATTINQ" on page 231.


NCDF_ATTDEL

The NCDF_ATTDEL procedure deletes an attribute from a netCDF file.

Calling Sequence

NCDF_ATTDEL, Cdfid, [Varid,] Name

Arguments

Cdfid

The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

Varid

The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable.

Name

A scalar string containing the name of the attribute to be deleted.

Keywords

GLOBAL

Set this keyword to delete a global variable.

Example

id = NCDF_OPEN('test.nc', /WRITE)	 ;Open file test.nc for writing.

NCDF_ATTDEL, id, 'TITLE', /GLOBAL	 ;Delete global attribute TITLE from the file.

NCDF_CLOSE, id	 ;Close the file.

See Also

NCDF_ATTNAME, NCDF_ATTPUT


NCDF_ATTGET

The NCDF_ATTGET procedure retrieves the value of an attribute from a netCDF file.

Calling Sequence

NCDF_ATTGET, Cdfid, [Varid,] Name, Value

Arguments

Cdfid

The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

Varid

The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable. If the GLOBAL keyword is used, this argument must be omitted.

Name

A scalar string containing the attribute name.

Value

A named variable in which the attribute's value is returned. NCDF_ATTGET sets Value's size and data type appropriately.

Keywords

GLOBAL

Set this keyword to retrieve the value of a global attribute.

Example

For an example using this routine, see the documentation for NCDF_ATTINQ.

See Also

NCDF_ATTINQ, NCDF_ATTNAME, NCDF_ATTPUT


NCDF_ATTINQ

The NCDF_ATTINQ function returns a structure that contains information about a netCDF attribute. This structure, described below, has the form:

{ DATATYPE:'', LENGTH=0L }

Calling Sequence

Result = NCDF_ATTINQ(Cdfid [,Varid], Name)

Arguments

Cdfid

The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

Varid

The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable. If the GLOBAL keyword is set, this argument must be omitted.

Name

A scalar string containing the name of the attribute for which information is to be returned.

Keywords

GLOBAL

Set this keyword to inquire about a global variable. If this keyword is set, the Varid argument must be omitted.

Explanation of the Structure Tags

DataType

A string describing the data type of the variable. The string will be one of the following: `BYTE', `CHAR', `INT', `LONG', `FLOAT', or `DOUBLE'.

Length

The number of values stored in the attribute. If the attribute is a string, the number of values indicates one more character than the string length to include the terminating null character. This is the NetCDF convention, as demonstrated in the example below.

Example

Open two netCDF files:

id = NCDF_CREATE('test.nc', /CLOBBER)  ;Open a new netCDF file.

id2 = NCDF_CREATE('test2.nc', /CLOBBER)  ;Open a second file.

Create two global attributes TITLE and DATE:

NCDF_ATTPUT, id, /GLOBAL, 'TITLE', 'MY TITLE'
;Insert a global attribute.

NCDF_ATTPUT, id, /GLOBAL, 'DAY', 'July 1,1996'
;Insert a global attribute.

Suppose we wanted to use DATE instead of DAY. We could use ATTRENAME to rename the attribute:

NCDF_ATTRENAME, id, 'DAY', 'DATE', /GLOBAL

Next, copy both attributes into a duplicate file:

result = NCDF_ATTCOPY(id, 'TITLE', id2, /IN_GLOBAL, /OUT_GLOBAL)

result2 = NCDF_ATTCOPY(id, 'DATE', id2, /IN_GLOBAL, /OUT_GLOBAL)

NCDF_CONTROL, id, /ENDEF	;Put the file into data mode.

name = NCDF_ATTNAME(id, /GLOBAL, 1)	;Get the second attribute's name.

NCDF_ATTGET, id, /GLOBAL, name, date	;Retrieve the date.

result = NCDF_ATTINQ(id, /GLOBAL, name)	;Get info about the attribute.

HELP, name, date, result, /STRUCTURE

IDL prints:

NAME            STRING    = `DATE'

DATE            BYTE      = Array(12)

** Structure <400dac30>, 2 tags, length=12, refs=1:

   DATATYPE        STRING    `BYTE'

   LENGTH          LONG                12

Note the length includes the NCDF standard NULL terminator

PRINT, date

IDL prints:

74 117 108 121  32  49  44  49  57  57  54   0

PRINT, STRING(date)

IDL prints:

July 1,1996

NCDF_DELETE, id	;Close the netCDF files.

NCDF_DELETE, id2

See Also

NCDF_ATTDEL, NCDF_ATTGET, NCDF_ATTNAME, NCDF_ATTPUT


NCDF_ATTNAME

The NCDF_ATTNAME function returns the name of an attribute in a netCDF file given its ID. The NULL string ("") is returned if there is no such attribute.

Calling Sequence

Result = NCDF_ATTNAME(Cdfid, [Varid,] Attnum)

Arguments

Cdfid

The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

Varid

The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable. If the GLOBAL keyword is set, this argument must be omitted.

Attnum

An expression containing the number of the desired attribute. The attributes for each variable are numbered from 0 to the number-of-attributes minus 1. Note that the number of attributes can be found using NCDF_VARINQ or NCDF_INQUIRE (to find the number of global variables).

Keywords

GLOBAL

Set this keyword to return the name of one of the global attributes.

See Also

NCDF_ATTINQ


NCDF_ATTPUT

The NCDF_ATTPUT procedure creates an attribute in a netCDF file. If the attribute is new, or if the space required to store the attribute is greater than before, the netCDF file must be in define mode.

Calling Sequence

NCDF_ATTPUT, Cdfid, [Varid,] Name, Value

Arguments

Cdfid

The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

Varid

The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable. If the GLOBAL keyword is set, this argument must be omitted.

Name

A scalar string containing the attribute name.

Value

An expression containing the data to be written. Although this procedure checks that there are a sufficient number of bytes of data, the data type is not checked or altered.

Keywords

GLOBAL

Set this keyword to create a global attribute.

LENGTH

Use this keyword to override the default length (the whole value). Set this keyword to a value less than or equal to the number of elements in Value. For example:

ATTR_ID = NCDF_ATTPUT(CDFID, VARID, 'Attr1', $

          INDGEN(10), LENGTH=5

writes Attr1 as [0,1,2,3,4].

The following keywords specify a non-default data type for the variable. By default, NCDF_ATTPUT chooses one based upon the type of data. If a data type flag is specified, the data supplied in Value is converted to that data type before being written to the file. Only one of these keywords can be used in a single call to NCDF_ATTPUT.

BYTE

Set this keyword to indicate that the data is composed of bytes.

CHAR

Set this keyword to indicate that the data is composed of bytes (assumed to be ASCII).

DOUBLE

Set this keyword to indicate that the data is composed of 8-byte floating point numbers (doubles).

FLOAT

Set this keyword to indicate that the data is composed of 4-byte floating point numbers (floats).

LONG

Set this keyword to indicate that the data is composed of 4-byte integers (longs).

SHORT

Set this keyword to indicate that the data is composed of 2-byte integers.

Example

NCDF_ATTPUT, cdfid, /GLOBAL, "Title", "My Favorite Data File"

NCDF_ATTPUT, cdfid, "data", "scale_factor", 12.5D"

See Also

NCDF_ATTINQ


NCDF_ATTRENAME

The NCDF_ATTRENAME procedure renames an attribute in a netCDF file.

Calling Sequence

NCDF_ATTRENAME, Cdfid, [Varid,] Oldname, Newname

Arguments

Cdfid

The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

Varid

The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable. If the GLOBAL keyword is set, this argument must be omitted.

OldName

A scalar string containing the attribute's current name.

NewName

A scalar string containing the attribute's new name.

Keywords

GLOBAL

Set this keyword to rename a global attribute.

See Also

NCDF_ATTINQ


NCDF_CLOSE

The NCDF_CLOSE procedure closes an open netCDF file. If a writable netCDF file is not closed before exiting IDL, the disk copy of the netCDF file may not reflect recent data changes or new definitions.

Calling Sequence

NCDF_CLOSE, Cdfid

Arguments

Cdfid

The netCDF ID of the file to be closed, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

See Also

NCDF_ATTINQ


NCDF_CONTROL

The NCDF_CONTROL procedure performs miscellaneous netCDF operations.

Different options are controlled by keywords. Only one keyword can be specified in any call to NCDF_CONTROL, unless the OLDFILL keyword is specified.

Calling Sequence

NCDF_CONTROL, Cdfid

Arguments

Cdfid

The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

Keywords

ABORT

Set this keyword to close a netCDF file that is not in define mode. If the file is being created and is still in define mode, the file is deleted. If define mode was entered by a call to NCDF_CONTROL with the REDEF keyword, the netCDF file is restored to its state before definition mode was entered, and the file is closed.

ENDEF

Set this keyword to take an open netCDF file out of define mode (and into data mode).

FILL

Set this keyword so that data in the netCDF file is pre-filled with default fill values. The default values (which cannot be changed) are:

Table 4-1: Default Fill Values for netCDF Files

Data Type	Fill Value
BYTE	0
CHAR	0
SHORT	-32767
LONG	-2147483647
FLOAT	9.96921E+36
DOUBLE	9.96921E+36
NOFILL

Set this keyword so that data in the netCDF file is not pre-filled. This option saves time when it is certain that variable values will be written before a read is attempted.

NOVERBOSE

Set this keyword to suppress the printing of netCDF error messages. Cdfid is required but not used.

OLDFILL

This keyword specifies a named variable in which the previous fill value is returned. This keyword can only be used in combination with the FILL or NOFILL keywords. For example:

NCDF_CONTROL, id, FILL=1, OLDFILL=previous_fill

REDEF

Set this keyword to put an open netCDF file into define mode.

SYNC

Set this keyword to update the disk copy of a netCDF file that is open for writing. The netCDF file must be in data mode. A netCDF file in define mode will be updated only when NCDF_CONTROL is called with the ENDEF keyword.

VERBOSE

Set this keyword to cause netCDF error messages to be printed. Cdfid is required but not used. For example:

NCDF_CONTROL, 0, /VERBOSE

is a valid command even if 0 is not a valid NetCDF file ID.

Example

See the examples under NCDF_ATTINQ and NCDF_VARPUT.

See Also

NCDF_CLOSE, NCDF_CREATE, NCDF_OPEN


NCDF_CREATE

The NCDF_CREATE function creates a new netCDF file. If successful, the netCDF ID for the file is returned. The newly-created netCDF file is automatically placed into define mode. If you do not have write permission to create the specified Filename, NCDF_CREATE returns an error message instead of a netCDF file ID.

Calling Sequence

Result = NCDF_CREATE(Filename)

Arguments

Filename

A scalar string containing the name of the file to be created

Keywords

CLOBBER

Set this keyword to erase the existing file (if the file already exists) before creating the new version.

NOCLOBBER

Set this keyword to create a new netCDF file only if the specified file does not already exist. This is the default.

Example

id = NCDF_CREATE('test.nc',/CLOBBER)	;Open a new NetCDF File and destroy test.nc if it already exists.

id2 = NCDF_CREATE('test.nc', /NOCLOBBER)
;This attempt to create a new version of the file test.nc produces the following error because the NOCLOBBER keyword was set.

IDL prints:

nccreate: filename "test.nc": File exists

% NCDF_CREATE: Operation failed

% Execution halted at $MAIN$   (NCDF_CREATE).

See Also

NCDF_CLOSE, NCDF_CONTROL, NCDF_OPEN


NCDF_DIMDEF

The NCDF_DIMDEF function defines a dimension in a netCDF file given its name and size. If successful, the dimension ID is returned.

Calling Sequence

Result = NCDF_DIMDEF(Cdfid, DimName, Size)

Arguments

Cdfid

The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

DimName

A scalar string containing the name of the dimension being defined.

Size

The size of the dimension. Size can be any scalar expression. If the UNLIMITED keyword is used, the Size parameter should be omitted.

Keywords

UNLIMITED

Set this keyword to create a dimension of unlimited size. Note that only one dimension in a netCDF file can be unlimited.

Example

See "NCDF_VARPUT" on page 257.


NCDF_DIMID

The NCDF_DIMID function returns the ID of a netCDF dimension, given the name of the dimension. This function returns -1 if the dimension does not exist.

Calling Sequence

Result = NCDF_DIMID(Cdfid, DimName)

Arguments

Cdfid

The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

DimName

A scalar string containing the dimension name.

Example

See "NCDF_VARPUT" on page 257.


NCDF_DIMINQ

The NCDF_DIMINQ procedure retrieves the name and size of a dimension in a netCDF file, given its ID. The size for the unlimited dimension, if any, is the maximum value used so far in writing data for that dimension.

Calling Sequence

NCDF_DIMINQ, Cdfid, Dimid, Name, Size

Arguments

Cdfid

The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

Dimid

The netCDF dimension ID, returned from a previous call to NCDF_DIMID or NCDF_DIMDEF or the name of the dimension.

Name

A named variable in which the dimension name is returned (a scalar string).

Size

A named variable in which the size of the dimension is returned (a scalar longword integer)

Example

See "NCDF_VARPUT" on page 257.


NCDF_DIMRENAME

The NCDF_DIMRENAME procedure renames an existing dimension in a netCDF file which has been opened for writing. If the new name is longer than the old name, the netCDF file must be in define mode. You cannot rename one dimension to have the same name as another dimension.

Calling Sequence

NCDF_DIMRENAME, Cdfid, Dimid, NewName

Arguments

Cdfid

The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

Dimid

The netCDF dimension ID, returned from a previous call to NCDF_DIMID or NCDF_DIMDEF, or the name of the dimension.

NewName

A scalar string containing the new name for the dimension.

Example

See "NCDF_VARPUT" on page 257.


NCDF_EXISTS

The NCDF_EXISTS function returns true if the Network Common Data Format (netCDF) scientific data format library is supported on the current IDL platform.

This routine is written in the IDL language. Its source code can be found in the file ncdf_exists.pro in the lib subdirectory of the IDL distribution.

Calling Sequence

Result = NCDF_EXISTS()

Example

The following IDL command prints an error message if the NetCDF library is not available:

IF NCDF_EXISTS() EQ 0 THEN PRINT, 'NCDF not supported.'


NCDF_INQUIRE

The NCDF_INQUIRE function returns a structure that contains information about an open netCDF file. This structure of the form:

{ NDIMS:0L, NVARS:0L, NGATTS:0L, RECDIM:0L }

The structure tags are described below.

Calling Sequence

Result = NCDF_INQUIRE(Cdfid)

Arguments

Cdfid

The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

Explanation of the Structure Tags

Ndims

The number of dimensions defined for this netCDF file.

Nvars

The number of variables defined for this netCDF file.

Ngatts

The number of global attributes defined for this netCDF file.

RecDim

The ID of the unlimited dimension, if there is one, for this netCDF file. If there is no unlimited dimension, RecDim is set to -1.

Example

See "NCDF_VARDEF" on page 250.


NCDF_OPEN

The NCDF_OPEN function opens an existing netCDF file. If successful, the netCDF ID for the file is returned.

Calling Sequence

Result = NCDF_OPEN(Filename)

Arguments

Filename

A scalar string containing the name of the file to be opened.

Keywords

NOWRITE

Set this keyword to open an existing netCDF file as read only. This is the default.

WRITE

Set this keyword to open an existing netCDF file for both writing and reading.

See Also

NCDF_ATTINQ


NCDF_VARDEF

The NCDF_VARDEF function adds a new variable to an open netCDF file in define mode. If successful, the variable ID is returned.

Calling Sequence

Result = NCDF_VARDEF(Cdfid, Name [, Dim])

Arguments

Cdfid

The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

Name

A scalar string containing the variable name.

Dim

An optional vector containing the dimension IDs corresponding to the variable dimensions. If the ID of the unlimited dimension is included, it must be the rightmost element in the array. If Dim is omitted, the variable is assumed to be a scalar.

Keywords

The following keywords specify the data type for the variable. Only one of these keywords can be used. If no data type keyword is specified, FLOAT is used by default.

BYTE

Set this keyword to indicate that the data is composed of bytes.

CHAR

Set this keyword to indicate that the data is composed of bytes (assumed to be ASCII).

DOUBLE

Set this keyword to indicate that the data is composed of double-precision floating-point numbers.

FLOAT

Set this keyword to indicate that the data is composed of floating-point numbers.

LONG

Set this keyword to indicate that the data is composed of longword integers.

SHORT

Set this keyword to indicate that the data is composed of 2-byte integers.

Example

id = NCDF_CREATE('test.nc', /CLOBBER)	;Create the netCDF file.

NCDF_ATTPUT, id, 'TITLE', 'Incredibly Important Data', /GLOBAL

NCDF_ATTPUT, id, 'GALAXY', 'Milky Way', /GLOBAL

NCDF_ATTPUT, id, 'PLANET', 'Earth', /GLOBAL

xid = NCDF_DIMDEF(id, 'x', 100)	;Define the X dimension.

yid = NCDF_DIMDEF(id, 'y', 200)	;Define the Y dimension.

zid = NCDF_DIMDEF(id, 'z', /UNLIMITED)	;Define the Z dimension.

vid0 = NCDF_VARDEF(id, 'image0', [yid, xid], /FLOAT)

vid1 = NCDF_VARDEF(id, 'image1', [yid, xid], /FLOAT)

Rename image0 to dist_image:

dist_id = NCDF_VARID(id, 'image0')	;Demonstrate usage of NCDF_VARID

NCDF_VARRENAME, id, vid0, 'dist_image'

NCDF_ATTPUT, id, vid, 'TITLE', 'DIST_IMAGE'

NCDF_CONTROL, id, /ENDEF  	;Put the file into data mode.

image = CONGRID(DIST(200), 200, 100)

NCDF_VARPUT, id, vid, image

INQ_VID = NCDF_VARINQ(id, 'dist_image')

HELP, INQ_VID, /STRUCTURE

IDL prints:

** Structure <400ec678>, 5 tags, length=32, refs=1:

   NAME            STRING    `dist_image'

   DATATYPE        STRING    `FLOAT'

   NDIMS           LONG                 2

   NATTS           LONG                 1

   DIM             LONG      Array(2)

file_inq = NCDF_INQUIRE(id)

HELP, file_inq, /STRUCTURE

IDL prints:

** Structure <400ebdf8>, 4 tags, length=16, refs=1:

   NDIMS           LONG                 3

   NVARS           LONG                 2

   NGATTS          LONG                 3

   RECDIM          LONG                 2

NCDF_CLOSE, id	;Close the NetCDF file.


NCDF_VARGET

The NCDF_VARGET procedure retrieves a hyperslab of values from a netCDF variable. The netCDF file must be in data mode to use this procedure.

Calling Sequence

NCDF_VARGET, Cdfid, Varid, Value

Arguments

Cdfid

The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

Varid

The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable.

Value

A named variable in which the values are returned. NCDF_VARGET sets Value's size and data type as appropriate.

Keywords

COUNT

An optional vector containing the counts to be used in reading Value. The default count vector is that for a single read, [1, 1, ...], as in NCDF_VARGET1.

OFFSET

An optional vector containing the starting position for the read. The default start position is [0, 0, ...].

STRIDE

An optional vector containing the strides, or sampling intervals, between accessed values of the netCDF variable. The default stride vector is that for a contiguous read, [1, 1, ...].

Example

Suppose that a 230 by 230 image is saved in the netCDF file dave.nc. The following commands extract both the full image and a 70x70 sub-image starting at [80,20] sampling every other X pixel and every third Y pixel:

offset = [80, 20]	;A variable that contains the offset for the sub-image.

count = [70, 70]	;The dimensions of the sub-image.

stride = [2, 3]	;Create a variable to be used as a value for the STRIDE keyword. Every other X element and every third Y element will be sampled.

id = NCDF_OPEN('dave.nc')	;Open the NetCDF file.

image = NCDF_VARID(id, 'image')	;Get the variable ID for the image.

NCDF_VARGET, id, image, fullimage	;Get the full image.

NCDF_VARGET, id, image, subimage, $

             COUNT=count, STRIDE=stride, OFFSET=offset
;Extract the sub-sampled image.

NCDF_CLOSE, id	;Close the NetCDF file.

See Also

NCDF_VARGET1, NCDF_VARID, NCDF_VARINQ, NCDF_VARPUT


NCDF_VARGET1

The NCDF_VARGET1 procedure retrieves one element from a netCDF variable. The netCDF file must be in data mode to use this procedure.

Calling Sequence

NCDF_VARGET1, Cdfid, Varid, Value

Arguments

Cdfid

The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

Varid

The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable.

Value

A named variable in which the value of the variable is returned. NCDF_VARGET1 sets Value's size and data type as appropriate.

Keywords

OFFSET

A vector containing the starting position of the read. The default starting position is [0, 0, ...].

Example

Suppose that the file dave.nc contains an image saved with the netCDF variable name "dave". The following commands extract the value of a single pixel from the image:

offset = [180,190]	;The location of the single element (pixel) whose value we will retrieve.

id = NCDF_OPEN('dave.nc')	;Open the netCDF file.

varid = NCDF_VARID(id, 'dave')	;Get the variable ID for variable "dave".

NCDF_VARGET1, id, varid, single_pixel, OFFSET=offset
;Extract the element and return the value in the variable single_pixel.

NCDF_CLOSE, id	;Close the netCDF file.

See Also

NCDF_VARGET, NCDF_VARID, NCDF_VARINQ, NCDF_VARPUT


NCDF_VARID

The NCDF_VARID function returns the ID of a netCDF variable. This function returns -1 if the variable does not exist.

Calling Sequence

Result = NCDF_VARID(Cdfid, Name)

Arguments

Cdfid

The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

Name

A scalar string containing the variable name.

Example

See "NCDF_VARDEF" on page 250.


NCDF_VARINQ

The NCDF_VARINQ function returns a structure that contains information about a netCDF variable, given its ID. This structure has the form:

{ NAME:"", DATATYPE:"", NDIMS:0L, NATTS:0L, DIM:LONARR(NDIMS) }

This structure is described below.

Calling Sequence

Result = NCDF_VARINQ(Cdfid, Varid)

Arguments

Cdfid

The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

Varid

The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable.

Explanation of the Structure Tags

Name

The name of the variable.

DataType

A string describing the data type of the variable. The string will be one of the following: 'BYTE', 'CHAR', 'INT', 'LONG', 'FLOAT', or 'DOUBLE'.

Ndims

The number of dimensions.

Natts

The number of attributes assigned to this variable.

Dim

A vector of the dimension IDs for the variable dimensions.

Example

See "NCDF_VARDEF" on page 250.


NCDF_VARPUT

The NCDF_VARPUT procedure writes a hyperslab of values to a netCDF variable. The netCDF file must be in data mode to use this procedure.

Calling Sequence

NCDF_VARPUT, Cdfid, Varid, Value

Arguments

Cdfid

The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

Varid

The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable.

Value

Data values to be written to the netCDF file. If the data type of Value does not match that of the netCDF variable, it is converted to the correct data type before writing. Value must have a dimensionality less than or equal to that of the variable being written.

Keywords

COUNT

An optional vector containing the counts to be used in writing Value. Note that counts do not have to match the dimensions of Value. The default count vector is the dimensionality of Value.

OFFSET

An optional vector containing the starting position to write. The default start position is [0, 0, ...].

STRIDE

An optional vector containing the strides, or writing intervals, between written values of the netCDF variable. The default stride vector is that for a contiguous write, [1, 1, ...].

Example

Suppose that you wish to create a 100x100 byte (0 & 1) checker board. In this case:

offset_even = [0,0] & offset_odd = [1,1]
;Create offsets for even and odd rows.

count = [50,50] & stride = [2,2]	;Create count and stride values.

black = BYTARR(50,50) > 1B	;Make the "black" spaces of the checker board.

id = NCDF_CREATE('checker.nc', /CLOBBER)
;Create the netCDF file.

NCDF_CONTROL, id, /FILL	;Fill the file with BYTE zeros.

xid = NCDF_DIMDEF(id, 'x', 100)	;Define the X dimension.

yid = NCDF_DIMDEF(id, 'y', 100)	;Define the Y dimension.

zid = NCDF_DIMDEF(id, 'yy', /UNLIMITED)	;Define the Z dimension, UNLIMITED.

vid = NCDF_VARDEF(id, 'board', [yid, xid], /BYTE)
;Define a variable with the name "board".

NCDF_DIMRENAME, id, zid, 'z'	;Rename 'yy' to 'z' as the zid dimension name.

NCDF_CONTROL, id, /ENDEF	;Put the file into data mode.

Use NCDF_DIMID and NCDF_DIMINQ to verify the name and size of the zid dimension:

check_id = NCDF_DIMID(id,'z')

NCDF_DIMINQ, id, check_id, dim_name, dim_size

HELP, check_id, dim_name, dim_size

IDL prints:

CHECK_ID     LONG            =   2

DIM_NAME     STRING          = 'z'

DIM_SIZE     LONG            =   0

Note that the DIM_SIZE is 0 because no records have been written yet for this dimension.

NCDF_VARPUT, id, vid, black, $

             COUNT=count, STRIDE=stride, OFFSET=offset_even

NCDF_VARPUT, id, vid, black, $

             COUNT=count, STRIDE=stride, OFFSET=offset_odd

NCDF_VARGET, id, vid, output	;Get the full image.

WINDOW, XSIZE=100, YSIZE=100	;Create a window for displaying the image.

TVSCL, output	;Display the image.

stride = [2,3]	;Make stride larger than possible.

NCDF_VARPUT, id, vid, black, $

             COUNT=count, STRIDE=stride, OFFSET=offset_odd
;As an experiment, attempt to write to an array larger than the one we previously allocated with NCDF_VARDEF.

IDL prints::

% NCDF_VARPUT: Requested write is larger than the available data area.

You will need to change the OFFSET/COUNT/STRIDE, or redefine the variable dimensions. You attempted to access 150 elements in a 100 array.

NCDF_CLOSE, id	;Close the netCDF file.

See Also

NCDF_VARGET, NCDF_VARGET1, NCDF_VARID, NCDF_VARINQ


NCDF_VARRENAME

The NCDF_VARRENAME procedure renames a netCDF variable.

Calling Sequence

NCDF_VARRENAME, Cdfid, Varid, Name

Arguments

Cdfid

The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE.

Varid

The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable.

Name

A scalar string containing the new name for the variable.

Example

See "NCDF_VARDEF" on page 250.