tpf_dfdl_serializeDoc: Serialize a document to a data stream by using a DFDL schema

This function uses a Data Format Description Language (DFDL) schema to serialize a formatted document to a data stream.

Last updated

Changed in 2024.
Changed in 2023.
Changed in 2022.
Changed in 2019.
Added for PUT15.

Format

LIBS := DFDL

#include <tpf/cdfdl.h>

void *tpf_dfdl_serializeDoc(DFDLHandle dfdlhdl,
                            char *document,
                            int doc_length,
                            DFDLFormat doc_type,
                            unsigned int *data_length,
                            char *start_element,
                            int options);

dfdlhdl

A DFDL API handle that is associated with a data stream and a DFDL structure to be processed.

document

A pointer to the document that is to be serialized.

doc_length

The length of the document that is to be serialized.

doc_type

The type of the document that is to be serialized. Specify one of the following values:

TPF_DFDL_BSON: A BSON document.
TPF_DFDL_CSV: A CSV document.
TPF_DFDL_JSON: A JSON document.
TPF_DFDL_PROP: A Java properties document.
TPF_DFDL_XML: An XML document.

data_length

A pointer to the location to store the size of the data stream that is serialized. Specify NULL for this parameter if the size of the data stream is not needed.

start_element

The name or absolute path of the element that serialization starts at in the document. The absolute path of the element uses the XML path language (XPath) notation. If you specify NULL for this parameter, serialization starts at the beginning of the document.

Start of change For BSON and CSV documents, you must set the start_element parameter to NULL. End of change

options

Specifies the processing options for this function. Specify any of the following values:

0: No special processing is requested.
TPF_DFDL_REALLOC: If the buffer area that was previously set by the tpf_dfdl_setData function is too small to contain the data stream contents, the DFDL parser reallocates the buffer area.
TPF_DFDL_ROWVAL: Each element and value of an element appear on a separate row. If an element and the value of the element are not defined in a DFDL schema, processing stops and an error is returned. You can specify this value only for CSV documents.
TPF_DFDL_STRICT: If the document contains data that is not defined in a DFDL schema, processing stops and an error is returned. You can specify this value only for CSV documents.
TPF_DFDL_UNORDERED: Indicates that the elements might be in a different order from the DFDL schema. This option is not supported for CSV documents.
TPF_DFDL_XTAGS: All element tags are excluded from the document. You can specify this value only for CSV documents.
TPF_DFDL_VERIFY: Verify whether the data conforms to the DFDL schema restrictions. Data that does not conform to the DFDL schema restrictions causes a std::runtime_error exception to be thrown.

Normal return

The address of the data stream that contains the serialized data.

Error return

None.

Exceptions

If an error occurs, one of the following exceptions is issued:

std::bad_alloc
std::invalid_argument
std::length_error
std::logic_error
std::runtime_error

Programming considerations

You must initialize the DFDL handle by calling the tpf_dfdl_initialize_handle or tpf_dfdl_createChildHandle function.
You must call the free function to release the storage that was allocated for serializing the document. The storage location to be released is identified by the address that the tpf_dfdl_serializeDoc function returns.
If the tpf_dfdl_serializeDoc function is called to serialize large documents, the ECB might exit with a 000010 system error. If the error occurs, you can enable time slicing for the application by calling the tmslc function.
The order of elements in the document must match the order of elements in the DFDL schema that is referenced by the DFDL API handle unless the Java properties format or the TPF_DFDL_UNORDERED option is specified.
You must call the tpf_dfdl_terminate_handle function after the last z/TPF DFDL API call to release any storage that was obtained when any of the z/TPF DFDL APIs were used.
The formatted document is in UTF-8 encoding.

Example

The following example shows how to serialize a JSON document into a data stream.

#include <tpf/cdfdl.h>
#include <exception>
...
#define DFDL_FILE "mydata.gen.dfdl.xsd"
#define DFDL_ROOT "mydata"

DFDLHandle dh = 0;
char *JSONdoc;
int docLen;
struct mydata *buf;
...
try {
   tpf_dfdl_initialize_handle(&dh, DFDL_FILE, DFDL_ROOT, 0);
   buf = (struct mydata *)
         tpf_dfdl_serializeDoc(dh, JSONdoc, docLen,
                               TPF_DFDL_JSON, NULL, NULL, 0);
}
catch (std::exception &e) {
   // error message in e.what()
}

if (dh) tpf_dfdl_terminate_handle(dh);