6.7.10SHOW MASK

#Syntax

#Description

Show (i.e. get) the (filter) mask of an HDF5 dataset named dataset_name. If dataset_name was not found or its mask could not be obtained (due to its storage type not being HDFQL_CHUNKED or for unknown/unexpected reasons), an error is raised.

#Parameter(s)

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

dataset_name – mandatory string that specifies the name of the HDF5 dataset whose (filter) mask is to be obtained.

chunk_number – optional integer that specifies the number of the chunk whose (filter) mask is to be obtained. If chunk_number is specified, it must either be between 0 and the storage dimension in question - 1 (otherwise an error is raised) or negative (in this case, its value will be the last position of the storage dimension in question minus the absolute value of chunk_number). If not specified, the masks of all existing chunks are obtained instead.

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

The (filter) mask of an HDF5 dataset as an HDFQL_UNSIGNED_INT.

#Example(s)

# create a chunked (size 2) HDF5 dataset named "my_dataset" of data type int of one dimension (size 6)
CREATE CHUNKED(2) DATASET my_dataset AS INT(6)

# insert (i.e. write) values 60 and 61 directly into chunk #0 of dataset "my_dataset" using a (filter) mask equal to 8
INSERT DIRECTLY MASK 8 INTO my_dataset VALUES(60, 61)

# insert (i.e. write) values 62 and 63 directly into chunk #1 of dataset "my_dataset" using a (filter) mask equal to 255 (i.e. 0xFF)
INSERT DIRECTLY MASK 0xFF INTO my_dataset[1] VALUES(62, 63)

# insert (i.e. write) values 64 and 65 directly into chunk #2 of dataset "my_dataset" using a (filter) mask equal to 0 (i.e. default value)
INSERT DIRECTLY INTO my_dataset[2] VALUES(64, 65)

# select (i.e. read) data from dataset "my_dataset" and populate cursor in use with it (should return 60, 61, 62, 63, 64, 65)
SELECT FROM my_dataset

# show (i.e. get) (filter) mask of chunk #0 of dataset "my_dataset" and populate cursor in use with it (should return 8)
SHOW MASK my_dataset[0]

# show (i.e. get) (filter) mask of chunk #1 of dataset "my_dataset" and populate cursor in use with it (should return 255)
SHOW MASK my_dataset[1]

# show (i.e. get) (filter) mask of chunks #0, #1, and #2 (i.e. all existing chunks) of dataset "my_dataset" and populate cursor in use with it (should return 8, 255, 0)
SHOW MASK my_dataset