hdfpt

Gateway to HDF-EOS Point interface

Syntax

[out1,...,outN] = hdfpt(funcstr,input1,...,inputN)

Description

hdfpt is the MATLAB^® gateway to the Point functions in the HDF-EOS C library, which is developed and maintained by EOSDIS (Earth Observing System Data and Information System). A Point data set comprises a series of data records taken at (possibly) irregular time intervals and at scattered geographic locations. Each data record consists of a set of one or more data values representing the state of a point in time and/or space.

[out1,...,outN] = hdfpt(funcstr,input1,...,inputN) returns one or more outputs corresponding to the Point function in the HDF-EOS library specified by functstr.

There is a one-to-one correspondence between PT functions in the HDF-EOS C library and valid values for funcstr. For example, hdfpt('detach',point_id) corresponds to the C library call PTdetach(point_id).

Programming Model

The programming model for accessing a point data set through hdfpt is as follows:

Open the file and initialize the PT interface by obtaining a file id from a file name.
Open or create a point data set by obtaining a point id from a point name.
Perform desired operations on the data set.
Close the point data set by disposing of the point id.
Terminate point access to the file by disposing of the file id.

To access a single point data set that already exists in an HDF-EOS file, use the following MATLAB commands:

fileid = hdfpt('open',filename,access);
pointid = hdfpt('attach',fileid,pointname);
    
% Optional operations on the data set...
    
status = hdfpt('detach',pointid);
status = hdfpt('close',fileid);

To access several files at the same time, obtain a separate file identifier for each file to be opened. To access more than one point data set, obtain a separate point id for each data set.

It is important to properly dispose of point id's and file id's so that buffered operations are written completely to disk. If you quit MATLAB or clear all MEX-files with PT identifiers still open, MATLAB issues a warning and automatically disposes of them.

Note that file identifiers returned by hdfpt are not interchangeable with file identifiers returned by any other HDF-EOS or HDF function.

Access Routines

Access routines initialize and terminate access to the PT interface and point data sets (including opening and closing files).

Value of `funcstr`	Function Syntax	Description
`'open'`	`file_id = hdfpt('open',filename,access)`	Given the filename and desired access mode, opens or creates an HDF file in order to create, read, or write a point. `access` can be `'read'`, `'readwrite'`, or `'create'`. `file_id` is -1 if the operation fails.
`'create'`	`point_id = hdfpt('create',file_id,pointname)`	Creates a point data set with the specified name. `pointname` is a character vector or string scalar containing the name of the point data set. `point_id` is -1 if the operation fails.
`'attach'`	`point_id = hdfpt('attach',file_id,pointname)`	Attaches to an existing point data set within the file. `point_id` is -1 if the operation fails.
`'detach'`	`status = hdfpt('detach',point_id)`	Detaches from point data set.
`'close'`	`status = hdfpt('close',file_id)`	Closes file.

Definition Routines

Definition routines allow the user to set key features of a point data set.

Value of `funcstr`	Function Syntax	Description
`'deflevel'`	`status = hdfpt('deflevel',point_id,levelname,... fieldList,fieldTypes,fieldOrders)`	Defines a new level within a point data set. `levelname` is the name of the level to be defined. `fieldList` is a cell array of character vectors or string array containing field names in the new level. `fieldTypes` is also a cell array of character vectors or string array containing the number type for each field in the `fieldList`. Valid number types include `'uchar8'`, `'uchar'`, `'char8'`, `'char'`, `'double'`, `'uint8'`, `'uint16'`, `'uint32'`, `'float'`, `'int8'`, `'int16'`, and `'int32'`. `fieldOrders` is a vector containing the order for each field.
`'deflinkage'`	`status = hdfpt('deflinkage',point_id,parent,child,linkfield)`	Defines a linkfield between two adjacent levels. `parent` is the name of the parent level. `child` is the name of the child level. `linkfield` is the name of a field that is defined at both levels.

Basic I/O Routines

Basic I/O routines read and write data and metadata to a point data set.

Value of `funcstr`	Function Syntax	Description
`'writelevel'`	`status = hdfpt('writelevel',point_id,level,data)`	Appends new records to the specified level in a point data set. `level` is the desired level index (zero-based). `data` must be a `P`-by-1 cell array where `P` is the number of fields defined for the specified level. Each cell of `data` must contain an `M(k)`-by-`N` matrix of data, where `M(k)` is the order of the `k`-th field (the number of scalar values in the field) and `N` is the number of records. The MATLAB class of the cells must match the HDF data type defined for the corresponding fields. Text data in MATLAB is automatically converted to match any of the HDF char types. Other data types must match exactly.
`'readlevel'`	`[data,status] = hdfpt('readlevel',point_id,... level,fieldList,records)`	Reads data from a given level in a point data set. `level` is the index (zero-based) of the desired level. `fieldList` is a cell array of character vectors or string array specifying the list of the fields to read. `records` is a vector containing the indices (zero-based) of the records to read. `data` is a `P`-by-1 cell array where `P` is the number of requested fields. Each cell of `data` contains an `M(k)`-by-`N` matrix of data where `M(k)` is the order of the `k`-th field and `N` is the number of records, or `length(records)`.
`'updatelevel'`	`status = hdfpt('updatelevel',point_id,... level,fieldList,records,data)`	Updates (corrects) data in a particular level of a point data set. `level` is the index (zero-based) of the desired level. `fieldList` is a cell array of character vectors or string array specifying the list of field names to update. `records` is a vector containing the indices (zero-based) of the records to update. `data` is a `P`-by-1 cell array where `P` is the number of specified fields. Each cell of `data` must contain an `M(k)`-by-`N` matrix of data, where `M(k)` is the order of the `k`-th field (the number of scalar values in the field) and `N` is the number of records, or `length(records)`. The MATLAB class of the cells must match the HDF data type defined for the corresponding fields. Text data in MATLAB is automatically converted to match any of the HDF char types. Other data types must match exactly.
`'writeattr'`	`status = hdfpt('writeattr',point_id,attrname,data)`	Writes or updates the point data set attribute with the specified name. If the attribute does not already exist, it is created.
`'readattr'`	`[data,status] = hdfpt('readattr',point_id,attrname)`	Reads the attribute data from the specified attribute.

Inquiry Routines

Inquiry routines return information about data contained in a point data set.

Value of `funcstr`	Function Syntax	Description
`'nlevels'`	`nlevels = hdfpt('nlevels',point_id)`	Returns the number of levels in a point data set. `nlevels` is -1 if the operation fails.
`'nrecs'`	`nrecs = hdfpt('nrecs',point_id,level)`	Returns the number of records in the specified level. `nrecs` is -1 if the operation fails.
`'nfields'`	`[numfields,strbufsize] = hdfpt('nfields',point_id,level)`	Returns the number of fields in the specified level. `strbufsize` is the length of array containing the field names. `numfields` is -1 and `strbufsize` is `[]` if the operation fails.
`'levelinfo'`	`[numfields,fieldList,field Type,fieldOrder] = ... hdfpt('levelinfo',point_id,level)`	Returns information on fields for a specified level. `fieldList` is a cell array of character vectors or string array containing the field names. `fieldType` is a cell array of character vectors that defined the data type for each field. `fieldOrder` is a vector containing the order (number of scalar values) associated with each field. If the operation fails, `numfields` is -1 and the other outputs are empty.
`'levelindx'`	`level = hdfpt('levelindx',point_id,levelname)`	Returns the level index (zero-based) of the level with the specified name. `level` is -1 if the operation fails.
`'bcklinkinfo'`	`[linkfield,status] = hdfpt('bcklinkinfo',point_id,level)`	Returns the linkfield to the previous level. `status` is -1 and `linkfield` is `[]` if the operation fails.
`'fwdlinkinfo'`	`[linkfield,status] = hdfpt('fwdlinkinfo',point_id,level)`	Returns the linkfield to the following level. `status` is -1 and `linkfield` is `[]` if the operation fails.
`'getlevelname'`	`[levelname,status] = hdfpt('getlevelname',point_id,level)`	Returns the name of a level given the level index. `status` is -1 and `levelname` is `[]` if the operation fails.
`'sizeof'`	`[byteSize,fieldLevels] = hdfpt('sizeof',point_id,fieldList)`	Returns the size in bytes and field levels of the specified fields. `fieldList` is a cell array of character vectors or string array containing the field names. `byteSize` is the total size of bytes of the specified fields, and `fieldLevels` is a vector containing the level index corresponding to each field. `byteSize` is -1 and `fieldLevels` is `[]` if the operation fails.
`'attrinfo'`	`[numberType,count,status] = ... hdfpt('attrinfo',point_id,attrname)`	Returns the number type and size in bytes of the specified attribute. `attrname` is the name of the attribute. `numberType` is a character vector containing the name of the corresponding HDF data type of the attribute. `count` is the number of bytes used by the attribute data. `status` is -1 and `numberType` and `count` are `[]` if the operation fails.
`'inqattrs'`	`[nattrs,attrnames] = hdfpt('inqattrs',point_id)`	Retrieve information about attributes defined in a point data set. `nattrs` and `attrnames` are the number and names of all the defined attributes, respectively. If the operation fails, `nattrs` is -1 and `attrnames` is `[]`.
`'inqpoint'`	`[numpoints,pointnames] = hdfpt('inqpoint',filename)`	Retrieve number and names of point data sets defined in an HDF-EOS file. `pointnames` is a cell array of character vectors containing a the point names. `numpoints` is -1 and `pointnames` is `[]` if the operation fails.

Utility Routines

Placeholder.

Value of `funcstr`	Function Syntax	Description
`'getrecnums'`	`[outRecords,status] = hdfpt('getrecnums',... point_id,inLevel,outLevel,inRecords)`	Returns the record numbers in `outLevel` corresponding the group of records specified by `inRecords` in level `inLevel`. The `inLevel` and `outLevel` arguments are zero-based level indices. `inRecords` is a vector of zero-based record indices. `status` is -1 and `outRecords` is `[]` if the operation fails.

Subset Routines

Subset routines allow reading of data from a specified geographic region.

Value of `funcstr`	Function Syntax	Description
`'defboxregion'`	`region_id = hdfpt('defboxregion',point_id,cornerLon,cornerLat)`	Defines a longitude-latitude box region for a point. `cornerLon` is a two-element vector containing the longitudes of opposite box corners. `cornerLat` is a two-element vector containing the latitudes of opposite box corners. `region_id`is -1 if the operation fails.
`'defvrtregion'`	`period_id = hdfpt('defvrtregion',point_id,region_id,... vert_field,range)`	Defines a vertical region for a point. `vert_field` is the name of the field to subset. `range` is a two-element vector containing the minimum and maximum vertical values. `period_id` is -1 if the operation fails.
`'regioninfo'`	`[byteSize,status] = hdfpt('regioninfo',point_id,... region_id,level,fieldList)`	Returns the data size in bytes of the subset period of the specified level. `fieldlist` is a cell array of character vectors or string array specifying the list of fields to extract. `status` and `byteSize` are -1 if the operation fails.
`'regionrecs'`	`[numRec,recNumbers,status] = hdfpt('regionrecs',... point_id,region_id,level)`	Returns the records numbers within the subsetted region of the specified level. `status` and `numrec` are -1 and `recNumbers` is `[]` if the operation fails.
`'extractregion'`	`[data,status] = hdfpt('extractregion',point_id,... region_id,level,fieldList)`	Reads data from the specified subset region. `fieldList` is a cell array of character vectors or string array specifying the list of requested fields. `data` is a `P`-by-1 cell array where `P` is the number of requested fields. Each cell of `data` contains an `M(k)`-by-`N` matrix of data where `M(k)` is the order of the `k`-th field and `N` is the number of records. `status` is -1 and `data` is `[]` if the operation fails.
`'deftimeperiod'`	`period_id = hdfpt('deftimeperiod',point_id,startTime,stopTime)`	Defines a time period for a point data set. `period_id` is -1 if the operation fails.
`'periodinfo'`	`[byteSize,status] = hdfpt('periodinfo',point_id,... period_id,level,fieldList)`	Retrieves the size in bytes of the subsetted period. `fieldList` is a cell array of character vectors or string array specifying the list of field names. `byteSize` and `status` are -1 if the operation fails.
`'periodrecs'`	`[numRec,recNumbers,status] = hdfpt('periodrecs',... point_id,period_id,level)`	Returns the records numbers within the subsetted time period of the specified level. `numRec` and `status` are -1 if the operation fails.
`'extractperiod'`	`[data,status] = hdfpt('extractperiod',... point_id,period_id,level,fieldList)`	Reads data from the specified subsetted time period. `fieldList` is a cell array of character vectors or string array specifying the list of requested fields. `data` is a `P`-by-1 cell array where `P` is the number of requested fields. Each cell of `data` contains an `M(k)`-by-`N` matrix of data where `M(k)` is the order of the `k`-th field and `N` is the number of records. `status` is -1 and `data` is `[]` if the operation fails.

Input/Output Arguments

Most routines return the flag, status, which is 0 when the routine succeeds and -1 when the routine fails. Routines with syntaxes which do not contain status return failure information in one of its outputs as notated in the function syntaxes.

levelName is a character vector or string scalar.

Some of the C library functions accept input values that are defined in terms of C macros. For example, the C PTopen() function requires an access mode input that can be DFACC_READ, DFACC_RDWR, or DFACC_CREATE, where these symbols are defined in the appropriate C header file. Where macro definitions are used in the C library, the equivalent MATLAB syntaxes use text derived from the macro names. You can either use text containing the entire macro name, or you can omit the common prefix. You can use either upper or lower case. For example, this C function call:

status = PTopen("PointFile.hdf",DFACC_CREATE)

is equivalent to these MATLAB function calls:

status = hdfpt('open','PointFile.hdf','DFACC_CREATE')
status = hdfpt('open','PointFile.hdf','dfacc_create')
status = hdfpt('open','PointFile.hdf','CREATE')
status = hdfpt('open','PointFile.hdf','create')

In cases where a C function returns a value with a macro definition, the equivalent MATLAB function returns the value as text containing the lowercase short form of the macro.

HDF number types are specified as: 'uchar8', 'uchar', 'char8', 'char', 'double', 'uint8', 'uint16', 'uint32', 'float', 'int8', 'int16', and 'int32'.

In cases where the HDF-EOS library accepts NULL, use an empty matrix ([]).

Version History

Introduced before R2006a