tpf_dfdl_initialize_handle: Initialize a DFDL API handle

This function initializes a DFDL API handle, which is required to use the z/TPF DFDL APIs.

Last updated

  • Changed in 2022 (information only; no code change).
  • Changed for PUT14 (information only; no code change).
  • Added for PUT11.

Format

LIBS := DFDL

#include <tpf/cdfdl.h>

void tpf_dfdl_initialize_handle(DFDLHandle *dfdlhdl, 
                                char       *schema_file, 
                                char       *root_element, 
                                int        options);
dfdlhdl
A pointer to the location to store the DFDL API handle that is associated with the DFDL structure to be processed. This function initializes the handle and allocates the required ECB heap storage for the handle.
schema_file
A pointer to the name of the DFDL schema file that was loaded to the /sys/tpf_pbfiles/tpf-fdes directory by using common deployment.
root_element
A pointer to the name of a complex element within the DFDL schema file that defines the binary data to be processed. The root element denotes the starting and ending point of the binary data.
options
Specifies the processing options for this function. Specify one of the following values:
TPF_DFDL_VERIFY
Verify that the external references in the DFDL schema file are valid. Specifying this parameter ensures that all DFDL schema files that compose the data description are loaded to the z/TPF system by using common deployment. This parameter also ensures that the referenced complex type names exist.
0
No special processing is requested.

Normal return

None.

Error return

None.

Exceptions

If an error occurs, one of the following exceptions is issued:
  • std::bad_alloc
  • std::invalid_argument

Programming considerations

  • You must call the tpf_dfdl_initialize_handle function before you use any other z/TPF DFDL APIs.
  • 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.
  • Enter ZMDES DISPLAY FILE-schema_file to verify that the DFDL schema file is loaded by using common deployment.

Example

The following example reads data from a socket and maps the data area to a DFDL description that is described by the specified element in the sample.lib.dfdl.xsd file. This example is based on the following the DFDL description: <xsd:element name="MsgData" dfdl:lengthKind="implicit" type="_msgdata"/>.
#include <sys/socket.h>
#include <tpf/cdfdl.h>
#include <stdlib.h>

#define MAX_BUF_SIZE 200
⋮

int nbytes, sock;
DFDLHandle dfdlhdl;

void *buffer = calloc(1, MAX_BUF_SIZE);

nbytes = read(sock, buffer, MAX_BUF_SIZE);

if (nbytes > 0) {
      try {
            tpf_dfdl_initialize_handle(&dfdlhdl, "sample.lib.dfdl.xsd", "MsgData", 0);  		

            tpf_dfdl_setData(dfdlhdl, buffer, (unsigned int) nbytes); 	
      } 	
      catch (...) {
             // handle error
      }
}