tpf_doc_buildDocument, tpf_doc_buildXMLdocument: Build a document

This function traverses a tree structure from the beginning and builds a formatted document based on the designed parser type.

Last updated

  • Changed for PUT11.
  • Changed for PUT07.
  • Changed for PUT06.
  • Added for PUT02.

Format

LIBS := CXAP
#include  <tpf/c_node.h>  
                               
char *tpf_doc_buildDocument (XMLHandle api_handle,
                                int *doc_length,
                                int processing_ind)

char *tpf_doc_buildXMLdocument (XMLHandle api_handle,
                                int *doc_length,
                                int processing_ind);
api_handle
The parser API handle associated with the tree structure that is being processed.
doc_length
A pointer to the location to store the length of the document that is built.
processing_ind
Reserved for future use. You must specify 0 for this parameter.

Normal return

A pointer to the document that was built.

Error return

A null pointer is returned.

The tpf_doc_buildDocument 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 or the parser API handle represents a document that has been parsed.
EINVAL
One of the following:
  • The encoding of a binary data content type of TYPE_HEX_BINARY or TYPE_BASE64_BINARY failed.
  • The processing_ind parameter was not set to 0.
ENOMEM
There is not enough storage available.

Programming considerations

  • The tpf_doc_buildDocument function can be called only by using a parser API handle that was used for creating a tree structure; that is, the tpf_doc_createStructure function was called.
  • The tpf_doc_buildDocument function traverses the tree structure sequentially to build the document. All suitable markup is added.
  • The application is responsible for releasing the storage (by calling the free function) that was allocated for building the document. The location of the storage to be released is identified by the address returned from the tpf_doc_buildDocument function.
  • If the tpf_doc_buildDocument function is called for large tree structures, the ECB might exit with a 000010 system error. If this occurs, you might need to enable time slicing for the application by calling the tmslc function.
  • If any of the data in the tree structure is marked as nondisplayable, it will be added to the document as nondisplayable.
  • If a JSON tree structure is used, the document is produced in the CCSID that is specified on the tpf_doc_createJSONstructure function or determined by the tpf_doc_parseDocument function.

Examples

The following example builds an XML document from the XML structure. 
#include <tpf/c_node.h>

char *responseXML;
int  messageLen;

/* 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         */

responseXML = tpf_doc_buildXMLdocument (api_handle, &messageLen, 0);

⋮