Pull-Parser Based Decode Functions

An XML pull-parser works by allowing a user to "pull" selected events from an XML stream as it is parsed. This differs from the SAX model which is sometimes referred to as a "push" parser because event callbacks are executed (pushed) as the stream is parsed. The pull model offers significant advantages for a data binding type application because it is easier to maintain state between operations. This results in less required code to do the decoding which in turn leads to improved performance. It is also conceptually easier to understand because the function call model more closely approximates the model used for encoding.

Generated C Function Format for XSD Types

Generated C pull-parser decode functions are written to a .c file with a name of the following format:

       <xsdFileName>Dec.c or
       <wsdlFileName>WSDLDec.c

where <xsdFileName> is the base name of the XSD file being parsed; and <wsdlFileName> is the base name of the WSDL file being parsed. For example, if code is being generated for file x.xsd, decode functions for each type and global element defined in the specification will be written to xDec.c . If the file being processed is a WSDL file, the suffix would be WSDLDec.c (for example, x.wsdl would produce xWSDLDec.c ).

The format of the name of each generated XML decode function is as follows:

     [<ns>]XmlDT_<typeName>

where <typeName>is the name of the C type for which the function is being generated and <ns>is an optional namespace setting that can be used to disambiguate element names from multiple sources (note: this should not be confused with XML namespaces which are different).

The calling sequence for each decode function is as follows:

     stat = <decodeFunc> (OSCTXT* pctxt, <typeName>* pvalue);

In this definition, <decodeFunc> denotes the decode function name defined above.

The pctxtargument is used to hold a context pointer to keep track of decode parameters. This is a basic "handle" variable that is used to make the function reentrant so it can be used in an asynchronous or threaded application. The user is required to supply a pointer to a variable of this type declared somewhere in his or her program.

The p valueargument is a pointer to a variable of the decode function type to receive the decoded data.

The function result variable statreturns the status of the decode operation. Status code 0 (zero) indicates the function was successful. A negative value indicates decoding failed. Return status values are defined in the rtxErrCodes.h include file. The error text and a stack trace can be displayed using the rtxErrPrint function.

A key difference between SAX-based functions and pull-parser based is that a decode function is not generated for all types in the SAX case. That is because of the overhead invlolved in setting up the SAX parser to decode simple types. Most simple types are decoded inline as part of more complex types. This is an example of a case where the pull-parser model more closely follows the encode model.

Generated C Function Format for XSD Global Elements

The generated C function format for global elements is identical to that of the SAX case:

       [<ns>]XmlD_<elemName>

The calling arguments are also the same:

       stat = <decodeFunc> (OSCTXT* pctxt, <typeName>* pvalue);

This allows pull-parser or SAX-based decoding to be interchanged with minimal code changes.

The procedure for calling this type of decode function is described below in the section entitled "Procedure for Calling C Decode Functions". The procedure for calling pull-parser based functions is the same as was the case for SAX-based functions.

Generated C Function Format for Project Level Factory Function

The generated C factory decode function format is similar to that of the global element decode function:

       [<ns>]XmlD_Project_<prjName>

The calling arguments are :

       stat = <decodeFunc> (OSCTXT* pctxt, <prjName>_message*
pvalue);

The procedure for calling this factory decode function is described below in the section entitled "Procedure for Calling C Decode Functions".

Generated C Decode Functions for WSDL Operations

Web service description language (WSDL) documents may contain operation definitions in portType and binding sections. A decode function is generated for each operation input and output in the following format:

    [<ns>]XmlD_<operName>_Input
    [<ns>]XmlD_<operName>_Output

where <operName>is the name of the WSDL operation name and <ns>is an optional namespace setting that can be used to disambiguate element names from multiple sources (note: this should not be confused with XML namespaces which are different). Note: if there are duplicate operation names in one WSDL source file, the first operation uses only the operation name, and other operation(s) with the duplicate names use a fully qualified name which is consist of operation name, input name and output name.

When Request-response primitives are used, the calling sequence for a WSDL input operation decode function is as follows:

    status = <decodeFunc> (OSCTXT* pctxt, <name>* pvalue);

The calling sequence for a WSDL output operation decode function is as follows:

    status = <decodeFunc> (OSCTXT* pctxt, <name>* pvalue,
                             <fault name>* pfault);

In this definition, <decodeFunc> denotes the decode function name defined above. The pctxtargument is used to hold a context pointer to keep track of decode parameters. This is a basic "handle" variable that is used to make the function reentrant so it can be used in an asynchronous or threaded application. The user is required to supply a pointer to a variable of this type declared somewhere in his or her program.

The pvalue argument is a pointer to a variable of the decode function type (either operation input or output) to receive the decoded input/output data. The pfault argument is a pointer to a variable of the operation fault type to receive the decoded SOAP Fault data.

The WSDL output operation decode function is used to decode a response from a Web Service server. If the response is a SOAP Fault message, the returned value status is RTERR_SOAPFAULT, and the decoded data is saved in pfault . If the response is a normal SOAP message, the returned status value is zero and the decoded data is saved in pvalue . A negative return value indicates decoding failed. Return status values are defined in the rtxErrCodes.h include file. The error text and a stack trace can be displayed using the rtxErrPrint function.