Procedure for Calling C Validation Functions

---

There are three steps to calling a compiler-generated C XML validation function:

1. Prepare a context variable for decoding/validation;

2. Open a stream;

3. Call the appropriate compiler-generated validation function to validate the message;

Before a C XML validation 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:

rtxStreamFileOpen

rtxStreamFileAttach

rtxStreamSocketAttach

rtxStreamMemoryCreate

rtxStreamMemoryAttach

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

A validation function can then be called to validate the message. If the boolean return code is true, then the message is valid; otherwise, one or more validation errors occurred. The validation errors are stored in the error list within the context. The rtxErr run-time functions can be used to process the error list. The simplest way to get validation error information is to call rtxErrPrint which will print information on all of the errors to stderr.

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 validate an employee record is as follows:

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

 
main ()
 
{
 
	int     stat;
 
	OSCTXT  ctxt;
 
	OSBOOL valid;
 
	const char* filename = "message.xml";
 

 
	/* Step 1: Init context structure */
 

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

 
	/* Step 2: Open a stream */
 

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

 
	/* Step 3: validate the record */
 

 
	valid = XmlV_personnelRecord (&ctxt);
 
	if (valid) {
 
		if (trace) {
 
			printf ("PersonnelRecord is valid\n");
 
		}
 
	}
 
	else {
 
		printf ("PersonnelRecord is not valid\n");
 
		rtxErrPrint (&ctxt);
 
		rtxStreamClose (&ctxt);
 
		return -1;
 
	}
 

 
	/* Close the stream and free the context. */   
 

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

 
	return 0;
 
}