Main Content

hdfpt

Interface to HDF-EOS Point object

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:

  1. Open the file and initialize the PT interface by obtaining a file id from a file name.

  2. Open or create a point data set by obtaining a point id from a point name.

  3. Perform desired operations on the data set.

  4. Close the point data set by disposing of the point id.

  5. 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 funcstrFunction SyntaxDescription
'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 funcstrFunction SyntaxDescription
'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 funcstrFunction SyntaxDescription
'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 funcstrFunction SyntaxDescription
'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 funcstrFunction SyntaxDescription
'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 funcstrFunction SyntaxDescription
'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_idis -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