tpf_doc_initialize_handle: Initialize a parser API handle

This function initializes a parser application programming interface (API) handle, which is required when you are using the z/TPF parser APIs.

Last updated

  • Changed for PUT11.
  • Changed for PUT07 (information only; no code change).
  • Changed for PUT06.
  • Added for PUT02.

Format

LIBS := CXAP
#include  <tpf/c_node.h>                             
int tpf_doc_initialize_handle(PXMLHandle xmlapi_ptr, 
                              XML_PARSER parser_type,
                              void *xml_ptr);
xmlapi_ptr
A pointer to the location to store the parser API handle. This API initializes the handle based on the type of parser that is indicated by the parser_type parameter and allocates the required ECB heap storage for the handle.
parser_type
The parser that was used to parse the document if the tree structure exists and contains parsed data, or the parser that will be used to parse the document if no tree structure exists. The values that are permitted for this parameter are defined in enumerated data type XML_PARSER in the tpf/c_node.h header file.
xml_ptr
The pointer to the tree structure that was created by the parser indicated by the parser_type parameter if the document has already been parsed, or NULL if the document has not been parsed or this z/TPF parser API handle will be used to create a document.
Notes:
  1. If the document has been parsed already, specify the pointer to the tree structure for the xml_ptr parameter and specify the parser that was used for the parser_type parameter.
  2. If the document has not been parsed, set the xml_ptr parameter to NULL and specify the parser that you will use for the parser_type parameter.
  3. If the document has been packed using the tpf_doc_packXMLstructure function:
    • Specify the pointer to the packed tree structure for the xml_ptr parameter and specify PACKED_XML_STRUCTURE for the parser_type parameter.
    • The packed structure must remain in malloc storage.
  4. The tpf_doc_initialize_handle with the PACKED_XML_STRUCTURE value specified will unpack, or recreate, the contents of the original parser API handle and the corresponding tree structure.
  5. If you are creating a document, set the xml_ptr parameter to NULL and specify NO_PARSER for the parser_type parameter.

Normal return

A value of 0.

Error return

A value of -1.

The tpf_doc_initialize_handle function also sets the errno C/C++ language variable to indicate the specific error:
ENOMEM
There is not enough storage available.
EFAULT
One of the following:
  • The xml_ptr parameter does not refer to a valid tree structure or the parser_type parameter does not refer to a valid parser type.
  • An address in the packed structure is NULL.
EEXIST
The parser API handle was initialized already for the specified tree structure.
EINVAL
The parser versions are not compatible.

Programming considerations

  • You must call the tpf_doc_initialize_handle function for each document that will be processed or created by using the z/TPF parser APIs.
  • If you call the tpf_doc_initialize_handle function more than once for the same tree structure, it returns the same value for the parser API handle. The position pointer is not changed.
  • All of the z/TPF parser APIs for a specific document must use the parser API handle for the corresponding tree structure.
  • You must call the tpf_doc_terminate_handle function after the last z/TPF parser API so that any storage that was obtained during any of the z/TPF parser APIs is released.
  • The tpf_doc_initialize_handle function initializes the position pointer field in the parser API handle to point before the root, or document, element in the tree structure.

Examples

The following example shows a parser API handle being initialized to be used with an existing tree structure. 
#include <tpf/c_node.h>
#include <stdio.h>

/* This example assumes that nodes_ptr is a ptr to an existing XML */
/* structure created by the B2B scanner                            */

XMLHandle api_handle = 0;
infoNodes *xml_ptr = nodes_ptr;  
int retCode;

retCode = tpf_doc_initialize_handle(&api_handle,
                                    B2B_XML_SCANNER,
                                    xml_ptr);

if (api_handle == 0 || retCode != 0)
{
     printf ("Error creating parser API handle - , errno);
}
else 
{
       ⋮  /* Use z/TPF parser APIs with api_handle */
  
}

See z/TPF Web Services Support for more information about z/TPF parser APIs.