6.7.12SHOW CHARSET

#Syntax

#Description

Show (i.e. get) the charset of an HDF5 dataset or attribute or of its members named object_name. In case a dataset and an attribute with identical names (object_name) are stored in the same location (i.e. group) and neither the keyword DATASET nor ATTRIBUTE is specified, the charset returned belongs to the dataset. To explicitly get the charset of object_name according to its type, the keyword DATASET or ATTRIBUTE must be specified. If object_name ends with “/” and is of data type HDFQL_COMPOUND, the charsets of members of object_name are returned instead.

#Parameter(s)

file_name – optional string that specifies the name of the HDF5 file storing the dataset or attribute whose charset is to be obtained. If file_name is specified, the file is opened on the fly, the charset of the dataset or attribute 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 dataset or attribute whose charset is to be obtained, or the charsets of its members if the name ends with “/” and the dataset or attribute is of data type HDFQL_COMPOUND.

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 charset of an HDF5 dataset or attribute as an HDFQL_INT, which can be HDFQL_ASCII, HDFQL_UTF8, or HDFQL_UNDEFINED depending on whether the charset is ASCII, UTF-8, or undefined (i.e. the dataset or attribute is neither of data type HDFQL_CHAR nor HDFQL_VARCHAR), respectively. Otherwise, if the keyword BY NAME is specified, it returns the charset of a dataset or attribute as an HDFQL_VARCHAR, which can be “ASCII”, “UTF8”, or “UNDEFINED”.

#Example(s)

# create an HDF5 dataset named "my_dataset0" of data type char 
CREATE DATASET my_dataset0 AS CHAR

# show (i.e. get) charset of dataset "my_dataset0" (should return 1 (i.e. HDFQL_ASCII)) 
SHOW CHARSET my_dataset0

# create an HDF5 dataset named "my_dataset1" of data type char of one dimension (size 20) using the UTF-8 representation
CREATE DATASET my_dataset1 AS UTF8 CHAR(20)

# show (i.e. get) charset of dataset "my_dataset1" (should return 2 (i.e. HDFQL_UTF8)) 
SHOW CHARSET my_dataset1

# create an HDF5 attribute named "my_attribute0" of data type compound composed of three members named "m0" (of data type char), "m1" (of data type int), and "m2" (of data type variable-length char using the UTF-8 representation)
CREATE ATTRIBUTE my_attribute0 AS COMPOUND(m0 AS CHAR, m1 AS INT, m2 AS UTF8 VARCHAR)

# show (i.e. get) charset of attribute "my_attribute0" (should return -1 (i.e. HDFQL_UNDEFINED))
SHOW CHARSET my_attribute0

# show (i.e. get) charset of members of attribute "my_attribute0" (should return 1 (i.e. HDFQL_ASCII), -1 (i.e. HDFQL_UNDEFINED), 2 (i.e. HDFQL_UTF8))
SHOW CHARSET my_attribute0/

# create an HDF5 dataset named "my_common" of data type char using the UTF-8 representation 
CREATE DATASET my_common AS UTF8 CHAR

# create an HDF5 attribute named "my_common" of data type variable-length char using the ASCII representation
CREATE ATTRIBUTE my_common AS ASCII VARCHAR

# show (i.e. get) charset of dataset "my_common" (should return 2 (i.e. HDFQL_UTF8)) 
SHOW CHARSET my_common

# show (i.e. get) charset of dataset "my_common" (should return 2 (i.e. HDFQL_UTF8)) 
SHOW CHARSET DATASET my_common

# show (i.e. get) charset of attribute "my_common" (should return 1 (i.e. HDFQL_ASCII)) 
SHOW CHARSET ATTRIBUTE my_common