There are four steps to calling a compiler-generated C XML decode function:

Before a C XML decode function can be called; the user must initialize a context variable. This is a variable of type OSCTXT. This variable holds all of the working data used during the decoding of a message. The context variable is declared as a normal automatic variable within the top-level calling function. It must be initialized before use. This can be accomplished by using the rtXmlInitContext function:

       OSCTXT ctxt;        // context variable

       if (rtXmlInitContext (&ctxt) != 0) {
           /* initialization failed, could be a license problem */
           printf ("context initialization failed (check license)\n");
           return -1;
        }

The next step is to create a stream object within the context. This object is an abstraction of the input device from which the XML data will be read and parsed. Calling one of the following functions initializes the stream:

The flags parameter of these functions should be set to the OSRTSTRMF_INPUT constant value to indicate an input stream is being created.

A decode function can then be called to decode the message. If the return status indicates success (0), then the message will have been decoded into the given XSD type variable. The decode function may automatically allocate dynamic memory to hold variable length items during the course of decoding. This memory will be tracked in the context structure, so the programmer does not need to worry about freeing it. It will be released when the context is freed.

The final step of the procedure is to close the stream and free the context block. The function to close the stream is rtxStreamClose . The function to free the context is rtxFreeContext .

A program fragment that could be used to decode an employee record is as follows:

   #include employee.h          /* include file generated by XBinder */

   main ()

   {
       int stat;
       OSCTXT ctxt;
       PersonnelRecord employee;
       const char* filename = "message.xml";

       /* Step 1: Init context structure */

       if (rtXmlInitContext (&ctxt) != 0) return -1;

       Init_PersonnelRecord (&ctxt, &employee);

       /* Step 2: Open a stream */

       stat = rtxStreamFileOpen (&ctxt, filename, OSRTSTRMF_INPUT);
       if (stat != 0) {
            rtxErrPrint (&ctxt);
            return -1;
       }

       /* Step 3: decode the record */

       stat = XmlD_personnelRecord (&ctxt, &employee);
       if (stat == 0) {
            if (trace) {
                 printf ("Decode of PersonnelRecord was successful\n");
                 printf ("Decoded record:\n");
                 Print_PersonnelRecord ("Employee", &employee);
            }
       }
       else {
            printf ("decode of PersonnelRecord failed\n");
            rtxErrPrint (&ctxt);
            rtxStreamClose (&ctxt);
            return -1;
       }

       /* Step 4: Close the stream and free the context. */

       rtxStreamClose (&ctxt);
       rtxFreeContext (&ctxt);

       return 0;
   }

When calling a C XML decode function for WSDL operation output, the user must initialize a fault variable. This is a variable of type Oper_Fault, where Oper is the operation name.

The following code snippet could be used to decode an Add operation output for example CalcWSDL:

   Add_Fault fault;
   ...
   stat = Init_Add_Fault (&ctxt, &fault);
   if (0 != stat) {
      printf ("fault initialization failed\n");
      return stat;
   }
   ...
   /* Decode */
   stat = XmlD_Add_Output (&ctxt, &response, &fault);

   if (stat == 0) {
      printf ("Decode of response message was successful\n");
      Print_Add_Output("response", &response);
   }
   else if (stat == RTERR_SOAPFAULT) {
      printf ("Decode of fault message was successful\n");
      Print_Add_Fault("fault", &fault);
   }
   else {
      printf ("decode failed\n");
      rtxErrPrint (&ctxt);
      return stat;
   }