FNC Library Routines That Support the DATASET Type

Teradata Vantageā„¢ DATASET Data Type

brand
Software
Teradata Vantage
prodname
Teradata Database
Teradata Vantage NewSQL Engine
vrm_release
16.20
category
Programming Reference
featnum
B035-1198-162K

When developing UDFs or external stored procedures defined with DATASET type parameters or return values, use the following DATASET type interface functions to access or set the values of the DATASET type parameters, or to get information about a DATASET type instance.

FNC Library Routine Description
FNC_GetDatasetInfo Identifies the maximum length, in-line length, schema length, raw data length, whether the schema and/or data is a LOB, and storage format of any DATASET data type instance so users can write a generic routine to handle cases.
FNC_GetDatasetInputLob Reads DATASET data stored as a LOB using the existing LOB FNC routines.

The CSV value is returned in a LOB, but does not include an optional schema.

FNC_GetDatasetResultLob Writes DATASET data to a LOB associated with any DATASET instance.

The CSV value is written to the result LOB, but does not include an optional schema.

FNC_GetDatasetSchema Retrieves the schema for any DATASET data type instance, regardless of storage format. The schema is returned as encoded in UTF-8 or UTF-16, depending on what the user specifies.
FNC_GetDatasetSchemaLob Reads the schema of a DATASET instance stored as a LOB using the existing LOB FNC routines. The schema is returned as encoded in UTF-8 or UTF-16, depending on what the user specifies.
FNC_GetInternalValue Retrieves non-LOB data from a DATASET instance.

The CSV value is returned, but does not include an optional schema.

FNC_SetDatasetLob Passes a LOB_LOCATOR that references a UTF-8 encoded schema, null-terminated, followed by the binary-encoded value to a DATASET data type instance. The data must conform to the transform format of the storage format of the DATASET instance.
FNC_SetInternalValue Sets non-LOB data of a DATASET instance. When it is known that the data for a particular instance is not stored as a LOB, this routine can set the data. The data must conform to the transform format of the storage format of the DATASET instance.

The CSV value is passed to this function, but it does not include an optional schema.

Use the DATASET_HANDLE data type to pass a DATASET type instance as an argument to an external routine or UDF. Similarly, use DATASET_HANDLE to return a DATASET type result from an external routine. DATASET_HANDLE is defined in sqltypes_td.h as follows:
typedef int DATASET_HANDLE;

Some FNC calls require that you specify encoding for the schema text being handled. Because of this, the following enum and types are defined in sqltypes_td.h:

typedef enum dataset_schema_encoding_en  {
	datasetSchemaUTF8 = 0,
	datasetSchemaUTF16 = 1
} dataset_schema_encoding_en;
typedef Byte dataset_schema_encoding_t;

The CSV enum field in dataset_storage_et is called DATASET_CSV_EN=1.

The DATASET data type may not be used as an attribute of a structured UDT or as the base type of a Teradata Distinct UDT or ARRAY type.

For details about the DATASET type interface functions, see Teradata Vantageā„¢ SQL External Routine Programming , B035-1147 .