6.4.5CREATE ATTRIBUTE
Syntax
CREATE [TRUNCATE] ATTRIBUTE [file_name] attribute_name [, [file_name] attribute_name]*
[AS data_type [(attribute_dim [, attribute_dim]*)] [SIZE compound_size]]
[TAG tag_value]
[VALUES {([initial_value] [, [initial_value]]*) | input_redirecting_option}]
data_type := [NATIVE | LITTLE ENDIAN | BIG ENDIAN | ASCII | UTF8] {TINYINT | UNSIGNED TINYINT | SMALLINT | UNSIGNED SMALLINT | INT | UNSIGNED INT | BIGINT | UNSIGNED BIGINT | FLOAT | DOUBLE | {CHAR [NULLTERM | NULLPAD | SPACEPAD]} | VARTINYINT | UNSIGNED VARTINYINT | VARSMALLINT | UNSIGNED VARSMALLINT | VARINT | UNSIGNED VARINT | VARBIGINT | UNSIGNED VARBIGINT | VARFLOAT | VARDOUBLE | {VARCHAR [NULLTERM | NULLPAD | SPACEPAD]} | OPAQUE | enumeration | compound}
enumeration := [TINYINT | SMALLINT | INT | BIGINT] ENUMERATION(member_name [AS member_value] [, member_name [AS member_value]]*)
compound := COMPOUND(member_name AS data_type [(member_dim [, member_dim]*)] [SIZE compound_size] [OFFSET member_offset] [TAG tag_value] [, member_name AS data_type [(member_dim [, member_dim]*)] [SIZE compound_size] [OFFSET member_offset] [TAG tag_value]]*)
Description
Create an HDF5 attribute named attribute_name. Multiple attributes can be created at once by separating their names with a comma (,). If attribute_name already exists, it is not overwritten, no subsequent attributes are created, and an error is raised. To overwrite an existing attribute, specify the keyword TRUNCATE (all data stored in the attribute will be permanently lost).
Parameter(s)
file_name – optional string that specifies the name of the HDF5 file in which the attribute is to be created. If file_name is specified, the file is opened on the fly, the attribute is created within it, and the file is subsequently closed. If not specified, the file currently in use is used instead. As a general rule, in case file_name contains spaces or special characters, it should be enclosed in double quotes (“). Otherwise, if it is not enclosed in double quotes, the attribute is not created, and an error is raised. This rule also applies to any other HDFql operation that works with file names (e.g. RENAME FILE).
attribute_name – mandatory string that specifies the name of the HDF5 attribute to create. As a general rule, in case attribute_name contains spaces or special characters, it should be enclosed in double quotes (“). Otherwise, if it is not enclosed in double quotes, the attribute is not created, and an error is raised. This rule also applies to any other HDFql operation that works with attribute names (e.g. RENAME ATTRIBUTE).
data_type – optional keyword that specifies the data type of the HDF5 attribute (or of the member that composes it) to create. If not specified, HDFql will automatically infer an appropriate data type for the attribute based on the characteristics (i.e. type and dimensions) of the data to be written into it (if neither direct values nor an input redirecting option is specified, the attribute is not created, and an error is raised).
member_name – mandatory string that specifies the name of the member that composes the HDF5 attribute of data type HDFQL_ENUMERATION or HDFQL_COMPOUND. As a general rule, in case member_name contains spaces or special characters, it should be enclosed in double quotes (“). Otherwise, if it is not enclosed in double quotes, the attribute is not created, and an error is raised. This rule also applies to any other HDFql operation that works with member names (e.g. SHOW MEMBER).
member_value – optional integer that specifies the value to assign to the member that composes the HDF5 attribute of data type HDFQL_ENUMERATION. If not specified, its value defaults to the value assigned to the previous member incremented by one. Of note, the default value assigned to the first member (of the enumeration) is zero (unless explicitly specified).
member_dim – optional integer that specifies the size of the dimension of the member that composes the HDF5 attribute of data type HDFQL_COMPOUND.
attribute_dim – optional integer that specifies the size of the dimension.
compound_size – optional integer that specifies the size (in bytes) of the HDF5 (nested) compound attribute. If not specified, HDFql will automatically calculate the size by either (1) summing the size (in bytes) of all members of the compound if member_offset is not specified or (2) taking the highest sum of the member’s offset with its size (in bytes) if member_offset is specified. Of note, the specification of a size is only available for an attribute of data type HDFQL_COMPOUND (any other data type will raise an error).
member_offset – optional integer that specifies the (memory) member offsets that compose the HDF5 attribute. If specified, the attribute is assumed to store a C padded struct data type (i.e. its members may not be contiguous in memory due to padding between them) and is used as such by HDFql. If not specified, the attribute is assumed to store a C primitive or packed struct data type (i.e. its members are contiguous in memory and have no padding between them) and is used as such by HDFql. Of note, the specification of an offset is only available for an attribute of data type HDFQL_COMPOUND (any other data type will raise an error).
tag_value – optional string that specifies the value of a tag attached to the HDF5 attribute or to its member(s). Of note, the specification of a tag is only available for an attribute or a member of data type HDFQL_OPAQUE (any other data type will raise an error).
initial_value – optional integer, float, or string to write into the HDF5 attribute to create. In case initial_value is not specified, the element in question will be zeroed or emptied, depending on whether the attribute is a number or a string, respectively. input_redirecting_option – optional option that specifies the cursor in use, a (text, binary, or Excel) file, or memory (i.e. a user-defined variable) to read data from in order to write it into the HDF5 attribute to create (please refer to the subsection FROM for additional information).
Return
Nothing
Example(s)
# create an HDF5 attribute named "my_attribute0" of data type int (the attribute will not be overwritten if it already exists)
CREATE ATTRIBUTE my_attribute0 AS INT
# create an HDF5 attribute named "my_attribute1" of data type char in a root object (either a group or dataset) named "my_object" (the attribute will not be overwritten if it already exists)
CREATE ATTRIBUTE /my_object/my_attribute1 AS CHAR
# create two HDF5 attributes named "my_attribute2" and "my_attribute3" of data type short (both attributes will be overwritten if they already exist)
CREATE TRUNCATE ATTRIBUTE my_attribute2, my_attribute3 AS SMALLINT
# create an HDF5 attribute named "this is a long attribute name" of data type float (the attribute will not be overwritten if it already exists)
CREATE ATTRIBUTE "this is a long attribute name" AS FLOAT# create an HDF5 attribute named "my_attribute4" of data type unsigned long long using the big endian representation
CREATE ATTRIBUTE my_attribute4 AS BIG ENDIAN UNSIGNED BIGINT
# create an HDF5 attribute named "my_attribute5" of data type int using the little endian representation with an initial value of 80178
CREATE ATTRIBUTE my_attribute5 AS LITTLE ENDIAN INT VALUES(80178)
# create an HDF5 attribute named "my_attribute6" of data type char using an UTF-8 representation
CREATE ATTRIBUTE my_attribute6 AS UTF8 CHAR# create an HDF5 attribute named "my_attribute7" of data type float of one dimension (size 512)
CREATE ATTRIBUTE my_attribute7 AS FLOAT(512)
# create an HDF5 attribute named "my_attribute8" of data type unsigned char of two dimensions (size 500x1000)
CREATE ATTRIBUTE my_attribute8 AS UNSIGNED TINYINT(500, 1000)# create an HDF5 attribute named "my_attribute9" of data type variable-length float
CREATE ATTRIBUTE my_attribute9 AS VARFLOAT
# create an HDF5 attribute named "my_attribute10" of data type variable-length short of one dimension (size 5) with initial values from a text file named "my_file.txt"
CREATE ATTRIBUTE my_attribute10 AS VARSMALLINT(5) VALUES FROM FILE my_file.txt
# create an HDF5 attribute named "my_attribute11" of data type variable-length char with an initial value of "Hierarchical Data Format"
CREATE ATTRIBUTE my_attribute11 AS VARCHAR VALUES("Hierarchical Data Format")# create an HDF5 attribute named "my_attribute12" of data type opaque
CREATE ATTRIBUTE my_attribute12 AS OPAQUE
# create an HDF5 attribute named "my_attribute13" of data type opaque of one dimension (size 6) with initial (ASCII) values 72, 68, 70, 0, 113, and 108 (i.e. "HDF\0ql")
CREATE ATTRIBUTE my_attribute13 AS OPAQUE(6) VALUES(72, 68, 70, 0, 113, 108)
# create an HDF5 attribute named "my_attribute14" of data type opaque of two dimensions (size 10x1024) with a tag value "Raw data"
CREATE ATTRIBUTE my_attribute14 AS OPAQUE(10, 1024) TAG "Raw data"# create an HDF5 attribute named "my_attribute15" of data type enumeration composed of three members named "Lisbon" (with value 0), "New York" (with value 1), and "Tokyo" (with value 2)
CREATE ATTRIBUTE my_attribute15 AS ENUMERATION(Lisbon, "New York", Tokyo)
# create an HDF5 attribute named "my_attribute16" of data type enumeration composed of three members named "red" (with value 0), "green" (with value 15), and "blue" (with value 16)
CREATE ATTRIBUTE my_attribute16 AS ENUMERATION(red, green AS 15, blue)
# create an HDF5 attribute named "my_attribute17" of data type enumeration of two dimensions (size 4x5) composed of two members named "car" (with value 10) and "plane" (with value 20)
CREATE ATTRIBUTE my_attribute17 AS ENUMERATION(car AS 10, plane AS 20)(4, 5)
# create an HDF5 attribute named "my_attribute18" of data type compound composed of three members named "person" (of data type variable-length char), "age" (of data type unsigned int), and "weight" (of data type float)
CREATE ATTRIBUTE my_attribute18 AS COMPOUND(person AS VARCHAR, age AS UNSIGNED INT, weight AS FLOAT)
# create an HDF5 attribute named "my_attribute19" of data type compound composed of four members named "id" (of data type long long), "description" (of data type variable-length char), "position" (of data type compound composed of two members named "x" (of data type short) and "y" (of data type short)), and "temperature" (of data type enumeration composed of three members named "cold" (with value 0), "warm" (with value 1), and "hot" (with value 10))
CREATE ATTRIBUTE my_attribute19 AS COMPOUND(id AS BIGINT, description AS VARCHAR, position AS COMPOUND(x AS SMALLINT, y AS SMALLINT), temperature AS ENUMERATION(cold, warm, hot AS 10))
# create an HDF5 attribute named "my_attribute20" of data type compound of one dimension (size 5) composed of three members named "state" (of data type enumeration composed of two members named "off" (with value 0) and "on" (with value 1)), "readings" (of data type int of two dimensions (size 3x4)), and "factors" (of data type compound composed of two members named "first" (of data type float) and "second" (of data type double))
CREATE ATTRIBUTE my_attribute20 AS COMPOUND(state AS ENUMERATION(off, on), readings AS INT(3, 4), factors AS COMPOUND(first AS FLOAT, second AS DOUBLE))(5)# use (i.e. open) an HDF5 file named "my_file.h5"
USE FILE my_file.h5
# create an HDF5 attribute named "my_attribute21" of data type double in the HDF5 file currently in use (i.e. file "my_file.h5")
CREATE ATTRIBUTE my_attribute21 AS DOUBLE
# close HDF5 file currently in use (i.e. file "my_file.h5")
CLOSE FILE
# create an HDF5 attribute named "my_attribute21" of data type int in file "my_file.h5"
CREATE ATTRIBUTE my_file.h5 my_attribute21 AS INT