tpf_doc_packXMLstructure: Create a packed XML structure

This function packs an existing parser API handle and its underlying XML structure so that the packed XML structure can be called again without having to create and parse a complete XML document.

Last updated

  • Changed for PUT11.
  • Added for PUT06.

Format

LIBS := CXAP
#include <tpf/c_node.h> 
                           
int tpf_doc_packXMLstructure(XMLHandle api_handle,
                             PPackedXML packed_xml)
api_handle
The parser API handle associated with the XML structure that is being processed.
packed_xml
A pointer to the location to store the packed XML structure.

Normal return

An integer greater than 0 indicates the length of the data pointed to by the packed_xml parameter.

Error return

A value of -1.

The tpf_doc_packXMLstructure function also sets the errno C/C++ language variable to indicate the specific error:
EFAULT
The api_handle parameter does not refer to a valid parser API handle.
EINVAL
The packed_xml parameter was set to null.
ENOMEM
There is not enough storage available.

Programming considerations

  • The tpf_doc_packXMLstructure function will populate a contiguous storage area that represents the XML document being processed. The storage can then be filed to a z/TPF database, transmitted to another z/TPF system, or in some other way passed to another z/TPF process for further processing.
  • The tpf_doc_initialize_handle function (with the parser_type parameter set to PACKED_XML_STRUCTURE) can be used with the packed XML structure to recreate the contents of the original parser API handle and the corresponding XML structure.
  • The application is responsible for releasing the storage (by calling the free function) that was allocated for building the packed XML structure if it is not used by this process on a subsequent call to the tpf_doc_initialize_handle.
  • Calling the tpf_doc_packXMLstructure function for large XML structures might result in the ECB exiting with a 000010 system error. If this occurs, you might need to enable time slicing for the application by calling the tmslc function.

Examples

The following example creates a packed XML structure from an XML structure that was in use.
#include <tpf/c_node.h>

int retCode;
PPackedXML *packedXMLstruct;
int fd;

/* This example assumes all nodes have been created     */
/* and that the api_handle has already been initialized */
/* by a prior call to tpf_doc_initialize_handle         */

retCode = tpf_doc_packXMLstructure (api_handle,
                                    &packedXMLstruct);

if (retCode != 0)
{
⋮   /* error processing */
}
else 
{
    /* Terminate the api_handle since it is no longer   */
    /* needed now that we packed the XML structure      */

    tpf_doc_terminate_handle (&api_handle);

    fd = open ("/tmp/myPackedFile.tmp", O_RDWR|O_CREAT,
               S_IRUSR|S_IWUSR|S_IRGRP|S_IROTH);

    if (fd != -1)
    {
       write (fd, packedXMLstruct, packedXMLstruct->len);
       close (fd);

       free (packedXMLstruct);
    }
}
⋮