When option -genKeyTest is specified, XBinder generates xsd:key related identity constraint test functions for global elements. These functions are used to validate the structure of data to ensure it is compliant with xsd:key, xsd:keyref, and xsd:unique constraints defined within the schema. These functions may be called prior to encoding a document or after decoding to validate constraint compliance. Calls to these functions are also added to generated reader/writer/rwtest code if this option is specified.

The generated key test functions are written to a .c file with a name of the following format:

   <xsdFileName>KeyTest.c

where <xsdFileName> is the base name of the XSD file being parsed. For example, if code is being generated for file x.xsd and -genKeyTest is specified, test functions will be written to xKeyTest.c .

The format of the name of each generated key test function is as follows:

   [<ns>]XmlKeyTest_<elemName>

where <elemName>is the name of the XSD global element for which the function is being generated and <ns>is an optional namespace setting that can be used to disambiguate names from multiple sources (note: this should not be confused with XML namespaces which are different). Note that key test routines are generated only for global elements within a specification.

The calling sequence for each generated test function is as follows:

    int stat = <keyTestFunc> (OSCTXT* pctxt, <typeName>*
pvalue)

In this definition, <keyTestFunc> denotes the formatted function name defined above.

The pctxtargument is used to hold a context pointer to keep track of dynamic memory allocation parameters. This is a basic "handle" variable that is used to make the function reentrant so that 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 variable must be initialized using either the rtxInitContext or rtXmlInitContext run-time function before use.

The pvalueargument is a pointer to a populated global element data structure. This variable is of the type generated for the XSD global element. The key test function checks identity constraints on the data within the structure. In encoding, it should be called after the structure is populated, and before the calling of encode function; in decoding, it should be called after decode function.

Note: if a data structure is filled with randomly-generated test data (with the -genTest option), it will most likely fail validation. This is because the identity constraints are not taken into consideration when generating test data.

The key test function returns 0 status if validation is successful. The following error codes will be returned when validation fails:

   XML_E_KEYNOTFOU - matching keyref constraints not present in array
   XML_E_DUPLKEY - key or unique constraint has duplicate key
   XML_E_FLDABSENT - incomplete key from key constraint, some field is
absent
   XML_E_DUPLFLD - key has duplicate field

Note: the identity constraint test functions are currently generated for C only.