# 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,...` | 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,...` | 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,...` | 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] = ...` | 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] = ...` | 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',...` | 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,...` | 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,...` | 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',...` | 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,...` | 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,...` | 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',...` | 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',...` | 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)

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**