6.7.17SHOW ORDER

#Syntax

#Description

Show (i.e. get) the (creation) order strategy of an HDF5 group or dataset named object_name. Multiple objects’ order strategies can be obtained at once by separating their names with a comma (,). If object_name was not found or its order strategy could not be obtained (due to unknown/unexpected reasons), no subsequent objects are checked, and an error is raised. By default, the returned order strategy refers to objects (i.e. groups, datasets, (soft) links, and external links) within a group; to return the order strategy of attributes of a group or dataset, the keyword ATTRIBUTE must be specified.

#Parameter(s)

file_name – optional string that specifies the name of the HDF5 file storing the group or dataset whose (creation) order strategy is to be obtained. If file_name is specified, the file is opened on the fly, the order strategy of the group or dataset is obtained, and the file is subsequently closed. If not specified, the file currently in use is used instead.

object_name – mandatory string that specifies the name of the HDF5 group or dataset whose (creation) order strategy is to be obtained.

post_processing_option – optional option that transforms the result set according to the programmer’s needs, such as ordering or truncating (please refer to the section PROCESSING for additional information).

output_redirecting_option – optional option that specifies the cursor in use, an HDF5 object (i.e. dataset or attribute), a (text, binary, or Excel) file, or memory (i.e. user-defined variable) to write the result set into (please refer to the subsection INTO for additional information). If not specified, the cursor in use is populated with the result set instead (please refer to the chapter CURSOR for additional information).

#Return

If the keyword BY NAME is not specified, it returns the (creation) order strategy of an HDF5 group or dataset as an HDFQL_INT, which can be HDFQL_TRACKED, HDFQL_INDEXED, or HDFQL_UNDEFINED depending on whether the order is tracked, indexed, or undefined (i.e. the group or dataset was created without any order strategy), respectively. Otherwise, if the keyword BY NAME is specified, it returns the (creation) order strategy of a group or dataset as an HDFQL_VARCHAR, which can be “TRACKED”, “INDEXED”, or “UNDEFINED”.

#Example(s)

# create an HDF5 group named "my_group0" 
CREATE GROUP my_group0

# show (i.e. get) (creation) order strategy of objects within group "my_group0" (should return -1 (i.e. HDFQL_UNDEFINED))
SHOW ORDER my_group0

# show (i.e. get) (creation) order strategy of attributes of group "my_group0" (should return -1 (i.e. HDFQL_UNDEFINED))
SHOW ATTRIBUTE ORDER my_group0

# create an HDF5 group named "my_group1" that tracks both the objects’ (i.e. groups and datasets) and the attributes’ creation order within the group
CREATE GROUP my_group1 ORDER TRACKED ATTRIBUTE ORDER INDEXED

# show (i.e. get) (creation) order strategy of objects within group "my_group1" (should return 1 (i.e. HDFQL_TRACKED))
SHOW ORDER my_group1

# show (i.e. get) (creation) order strategy of attributes of group "my_group1" (should return 2 (i.e. HDFQL_INDEXED))
SHOW ATTRIBUTE ORDER my_group1

# create an HDF5 dataset named "my_dataset0" of data type int that tracks the attributes’ creation order within the dataset
CREATE DATASET my_dataset0 AS INT ATTRIBUTE ORDER TRACKED

# show (i.e. get) (creation) order strategy of attributes of dataset "my_dataset0" (should return 1 (i.e. HDFQL_TRACKED))
SHOW ATTRIBUTE ORDER my_dataset0

# show (i.e. get) (creation) order strategy of attributes of both group "my_group1" and dataset "my_dataset0" at once (should return 2, 1)
SHOW ATTRIBUTE ORDER my_group1, my_dataset0