hdfpt

HDF-EOS 点对象的接口

语法

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

说明

hdfpt 是 HDF-EOS C 库中的 Point 函数的 MATLAB^® 入口，由 EOSDIS（地球观测系统数据和信息系统）开发和维护。点数据集包含（可能）在不规则时间区间和分散的地理位置获取的一系列数据记录。每个数据记录都包含一个由一个或多个数据值构成的集合，表示时间和/或空间中点的状态。

[out1,...,outN] = hdfpt(funcstr,input1,...,inputN) 返回与 HDF-EOS 库中由 functstr 指定的 Point 函数对应的一个或多个输出。

HDF-EOS C 库中的 PT 函数与 funcstr 的有效值之间存在一对一的对应关系。例如，hdfpt('detach',point_id) 对应于 C 库调用 PTdetach(point_id)。

编程模型

通过 hdfpt 访问点数据集的编程模型如下所示：

通过从文件名中获取文件 id 来打开文件并初始化 PT 接口。
通过从点名称中获取点 id 来打开或创建一个点数据集。
对数据集执行需要的操作。
通过处置点 id 来关闭点数据集。
通过处置文件 id 来终止对文件的点访问。

要访问 HDF-EOS 文件中已存在的单个点数据集，请使用以下 MATLAB 命令：

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

要同时访问多个文件，请为每个打开的文件获取一个单独的文件标识符。要访问多个点数据集，请为每个数据集获取一个单独的点 id。

务必正确处置点 id 和文件 id，以便缓冲的操作完全写入磁盘。如果退出 MATLAB 或清除所有 MEX 文件，但仍打开 PT 标识符，则 MATLAB 将发出警告并自动处置这些标识符。

请注意，hdfpt 返回的文件标识符不可与任何其他 HDF-EOS 或 HDF 函数返回的文件标识符互换。

访问例程

访问例程初始化以及终止对 PT 接口和点数据集的访问（包括打开和关闭文件）。

`funcstr` 的值	函数语法	描述
`'open'`	`file_id = hdfpt('open',filename,access)`	在给定了文件名和需要的访问模式的情况下，打开或创建一个 HDF 文件，以便创建、读取或写入点。`access` 可以是 `'read'`、`'readwrite'` 或 `'create'`。如果操作失败，则 `file_id` 为 -1。
`'create'`	`point_id = hdfpt('create',file_id,pointname)`	创建一个具有指定名称的点数据集。`pointname` 是包含该点数据集名称的字符向量或字符串标量。如果操作失败，则 `point_id` 为 -1。
`'attach'`	`point_id = hdfpt('attach',file_id,pointname)`	附加到文件中的现有点数据集。如果操作失败，则 `point_id` 为 -1。
`'detach'`	`status = hdfpt('detach',point_id)`	与点数据集分离。
`'close'`	`status = hdfpt('close',file_id)`	关闭文件。

定义例程

定义例程允许用户设置一个点数据集的主要功能。

`funcstr` 的值	函数语法	描述
`'deflevel'`	`status = hdfpt('deflevel',point_id,levelname,... fieldList,fieldTypes,fieldOrders)`	在点数据集中定义一个新级别。`levelname` 是要定义的级别的名称。`fieldList` 是一个字符向量元胞数组或字符串数组，包含新级别中的字段名称。`fieldTypes` 也是一个字符向量元胞数组或字符串数组，包含 `fieldList` 中每个字段的数值类型。有效的数值类型包括 `'uchar8'`、`'uchar'`、`'char8'`、`'char'`、`'double'`、`'uint8'`、`'uint16'`、`'uint32'`、`'float'`、`'int8'`、`'int16'` 和 `'int32'`。`fieldOrders` 是包含每个字段的顺序的向量。
`'deflinkage'`	`status = hdfpt('deflinkage',point_id,parent,child,linkfield)`	定义一个介于两个相邻级别之间的链接字段。`parent` 是父级别的名称。`child` 是子级别的名称。`linkfield` 是同时在这两个级别定义的字段的名称。

基本 I/O 例程

基本 I/O 例程读取数据和元数据并将其写入到一个点数据集。

`funcstr` 的值	函数语法	描述
`'writelevel'`	`status = hdfpt('writelevel',point_id,level,data)`	将新记录追加到点数据集中的指定级别。`level` 是需要的级别索引（从 0 开始）。`data` 必须为 `P`×1 元胞数组，其中 `P` 是为指定级别定义的字段数。`data` 的每个元胞必须包含一个 `M(k)`×`N` 数据矩阵，其中 `M(k)` 是第 `k` 个字段的阶数（字段中标量值的数目），`N` 是记录数。元胞的 MATLAB 类必须与为对应字段定义的 HDF 数据类型匹配。MATLAB 中的文本数据将会自动转换，以便与任何 HDF 字符类型匹配。其他数据类型必须完全匹配。
`'readlevel'`	`[data,status] = hdfpt('readlevel',point_id,... level,fieldList,records)`	读取点数据集中给定级别的数据。`level` 是所需级别的索引（从 0 开始）。`fieldList` 是一个字符向量元胞数组或字符串数组，指定要读取的字段的列表。`records` 是一个向量，包含要读取的记录的索引（从 0 开始）。`data` 是一个 `P`×1 元胞数组，其中 `P` 是所请求字段的数目。`data` 的每个元胞包含一个 `M(k)`×`N` 数据矩阵，其中 `M(k)` 是第 `k` 个字段的阶数，`N` 是记录数或 `length(records)`。
`'updatelevel'`	`status = hdfpt('updatelevel',point_id,... level,fieldList,records,data)`	更新（更正）点数据集特定级别的数据。`level` 是所需级别的索引（从 0 开始）。`fieldList` 是一个字符向量元胞数组或字符串数组，指定要更新的字段名称的列表。`records` 是一个向量，包含要更新的记录的索引（从 0 开始）。`data` 是一个 `P`×1 元胞数组，其中 `P` 是所指定字段的数目。`data` 的每个元胞必须包含一个 `M(k)`×`N` 数据矩阵，其中 `M(k)` 是第 `k` 个字段的阶数（字段中标量值的数目），`N` 是记录数或 `length(records)`。元胞的 MATLAB 类必须与为对应字段定义的 HDF 数据类型匹配。MATLAB 中的文本数据将会自动转换，以便与任何 HDF 字符类型匹配。其他数据类型必须完全匹配。
`'writeattr'`	`status = hdfpt('writeattr',point_id,attrname,data)`	使用指定的名称写入或更新该点数据集属性。如果该属性不存在，则创建它。
`'readattr'`	`[data,status] = hdfpt('readattr',point_id,attrname)`	读取指定属性中的属性数据。

查询例程

查询例程返回有关点数据集中包含的数据的信息。

`funcstr` 的值	函数语法	描述
`'nlevels'`	`nlevels = hdfpt('nlevels',point_id)`	返回一个点数据集中的级别数目。如果操作失败，则 `nlevels` 为 -1。
`'nrecs'`	`nrecs = hdfpt('nrecs',point_id,level)`	返回指定级别中的记录数。如果操作失败，则 `nrecs` 为 -1。
`'nfields'`	`[numfields,strbufsize] = hdfpt('nfields',point_id,level)`	返回指定级别的字段数目。`strbufsize` 是包含字段名称的数组的长度。如果操作失败，则 `numfields` 为 -1，`strbufsize` 为 `[]`。
`'levelinfo'`	`[numfields,fieldList,field Type,fieldOrder] = ... hdfpt('levelinfo',point_id,level)`	返回有关指定级别的字段的信息。`fieldList` 是一个字符向量元胞数组或字符串数组，其中包含字段名称。`fieldType` 也是一个字符向量元胞数组，定义每个字段的数据类型。`fieldOrder` 是一个向量，包含与每个字段关联的顺序（标量值编号）。如果操作失败，则 `numfields` 为 -1，其他输出为空。
`'levelindx'`	`level = hdfpt('levelindx',point_id,levelname)`	返回具有指定名称的级别的级别索引（从 0 开始）。如果操作失败，则 `level` 为 -1。
`'bcklinkinfo'`	`[linkfield,status] = hdfpt('bcklinkinfo',point_id,level)`	返回上一级别的链接字段。如果操作失败，则 `status` 为 -1，`linkfield` 为 `[]`。
`'fwdlinkinfo'`	`[linkfield,status] = hdfpt('fwdlinkinfo',point_id,level)`	返回以下级别的链接字段。如果操作失败，则 `status` 为 -1，`linkfield` 为 `[]`。
`'getlevelname'`	`[levelname,status] = hdfpt('getlevelname',point_id,level)`	返回具有给定级别索引的级别的名称。如果操作失败，则 `status` 为 -1，`levelname` 为 `[]`。
`'sizeof'`	`[byteSize,fieldLevels] = hdfpt('sizeof',point_id,fieldList)`	返回指定字段的大小（以字节为单位）和字段级别。`fieldList` 是一个字符向量元胞数组或字符串数组，其中包含字段名称。`byteSize` 是指定字段的字节总数。`fieldLevels` 是一个向量，包含与每个字段对应的级别索引。如果操作失败，则 `byteSize` 为 -1，`fieldLevels` 为 `[]`。
`'attrinfo'`	`[numberType,count,status] = ... hdfpt('attrinfo',point_id,attrname)`	返回指定属性的数值类型和大小（以字节为单位）。`attrname` 是属性的名称。`numberType` 是一个字符向量，包含与该属性对应的 HDF 数据类型的名称。`count` 是属性数据使用的字节数。如果操作失败，则 `status` 为 -1，`numberType` 和 `count` 为 `[]`。
`'inqattrs'`	`[nattrs,attrnames] = hdfpt('inqattrs',point_id)`	检索有关点数据集中定义的属性的信息。`nattrs` 和 `attrnames` 分别是所有定义的属性的编号和名称。如果操作失败，则 `nattrs` 为 -1，`attrnames` 为 `[]`。
`'inqpoint'`	`[numpoints,pointnames] = hdfpt('inqpoint',filename)`	检索 HDF-EOS 文件中定义的点数据集的数目和名称。`pointnames` 是一个字符向量元胞数组，其中包含点名称。如果操作失败，则 `numpoints` 为 -1，`pointnames` 为 `[]`。

实用工具例程

占位符。

`funcstr` 的值	函数语法	描述
`'getrecnums'`	`[outRecords,status] = hdfpt('getrecnums',... point_id,inLevel,outLevel,inRecords)`	返回 `outLevel` 中对应于级别 `inLevel` 中 `inRecords` 指定的记录组的记录数。`inLevel` 和 `outLevel` 参数是从 0 开始的级别索引。`inRecords` 是包含从 0 开始的记录索引的向量。如果操作失败，则 `status` 为 -1，`outRecords` 为 `[]`。

子集例程

通过子集例程可以读取指定地理区域中的数据。

`funcstr` 的值	函数语法	描述
`'defboxregion'`	`region_id = hdfpt('defboxregion',point_id,cornerLon,cornerLat)`	为点定义一个经纬度框区域。`cornerLon` 是一个二元素向量，包含相对框角的经度。`cornerLat` 是一个二元素向量，包含相对框角的纬度。如果操作失败，则 `region_id` 为 -1。
`'defvrtregion'`	`period_id = hdfpt('defvrtregion',point_id,region_id,... vert_field,range)`	定义一个点的垂直区域。`vert_field` 是要设置子集的字段的名称。`range` 是一个二元素向量，包含最小和最大垂直值。如果操作失败，则 `period_id` 为 -1。
`'regioninfo'`	`[byteSize,status] = hdfpt('regioninfo',point_id,... region_id,level,fieldList)`	返回指定级别的子集时间段的数据大小（以字节为单位）。`fieldlist` 是一个字符向量元胞数组或字符串数组，指定要提取的字段列表。如果操作失败，则 `status` 和 `byteSize` 为 -1。
`'regionrecs'`	`[numRec,recNumbers,status] = hdfpt('regionrecs',... point_id,region_id,level)`	返回指定级别的子区域内的记录数。如果操作失败，则 `status` 和 `numrec` 为 -1，`recNumbers` 为 `[]`。
`'extractregion'`	`[data,status] = hdfpt('extractregion',point_id,... region_id,level,fieldList)`	读取指定子集区域中的数据。`fieldList` 是一个字符向量元胞数组或字符串数组，指定所请求字段的列表。`data` 是一个 `P`×1 元胞数组，其中 `P` 是所请求字段的数目。`data` 的每个元胞包含一个 `M(k)`×`N` 数据矩阵，其中 `M(k)` 是第 `k` 个字段的阶数，`N` 是记录数。如果操作失败，则 `status` 为 -1 并且 `data` 为 `[]`。
`'deftimeperiod'`	`period_id = hdfpt('deftimeperiod',point_id,startTime,stopTime)`	为点数据集定义一个时间段。如果操作失败，则 `period_id` 为 -1。
`'periodinfo'`	`[byteSize,status] = hdfpt('periodinfo',point_id,... period_id,level,fieldList)`	检索子时间段的大小（以字节为单位）。`fieldList` 是一个字符向量元胞数组或字符串数组，指定字段名称的列表。如果操作失败，则 `byteSize` 和 `status` 为 -1。
`'periodrecs'`	`[numRec,recNumbers,status] = hdfpt('periodrecs',... point_id,period_id,level)`	返回指定级别的子时间段内的记录数。如果操作失败，则 `numRec` 和 `status` 为 -1。
`'extractperiod'`	`[data,status] = hdfpt('extractperiod',... point_id,period_id,level,fieldList)`	读取指定子时间段中的数据。`fieldList` 是一个字符向量元胞数组或字符串数组，指定所请求字段的列表。`data` 是一个 `P`×1 元胞数组，其中 `P` 是所请求字段的数目。`data` 的每个元胞包含一个 `M(k)`×`N` 数据矩阵，其中 `M(k)` 是第 `k` 个字段的阶数，`N` 是记录数。如果操作失败，则 `status` 为 -1 并且 `data` 为 `[]`。

输入/输出参数

大多数例程返回标志 status，当例程成功时，其值为 0，当例程失败时，其值为 -1。具有不包含 status 的语法的例程在其一个输出中返回失败信息，如函数语法中所示。

levelName 是一个字符向量或字符串标量。

某些 C 库函数接受根据 C 宏定义的输入值。例如，C PTopen() 函数需要访问模式输入，可以是 DFACC_READ、DFACC_RDWR 或 DFACC_CREATE，这些符号在相应的 C 头文件中定义。当在 C 库中使用宏定义时，等效的 MATLAB 语法使用从宏名称取得的文本。您可以使用包含整个宏名称的文本，也可以省略常用前缀。可以使用大写或小写。例如，此 C 函数调用：

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

等效于以下 MATLAB 函数调用：

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')