gxluGenOSR — generate an Optimized Schema Representation (OSR)

Description

This utility generates an optimized representation of one or more XML schemas.

Performance Implications

There are no performance implications.

Syntax

unsigned int gxluGenOSR(void * oima_p,
                void ** schema_osr_p_p,
                int * rc_p,
                int * rsn_p)

Parameters

oima_p

Supplied parameter

Type:: void *

A pointer to an OSR generator Instance Memory Area (OIMA).

schema_osr_p_p

Returned parameter

Type:: void **

A pointer to an area to receive the address of the optimized schema representation generated by this utility. See the usage notes below for important details about this parameter.

rc_p

Returned parameter

Type:: int *

A pointer to an area where the utility stores the return code.

rsn_p

Returned parameter

Type:: int *

A pointer to an area where the utility stores the reason code. The reason code is only relevant if the return code is not XRC_SUCCESS.

All parameters in the parameter list are required.

Return Value:

The value returned by this utility is the length of the OSR buffer returned to the caller through the schema_osr_p parameter. If there is a problem during the generation of the OSR, the value returned will be zero. See the usage notes below for more information about this value and the OSR buffer returned.

Return and Reason Codes:

Register 15 will contain the return value of this utility. The return and reason code are both set as output parameters. The value of the reason code is undefined when the return code has no associated reasons. Return and reason codes are defined in the header file gxlhxr.h (see gxlhxr.h (GXLYXR) - defines the return codes and reason codes). For reason code descriptions, also see Reason codes listed by value.

Example

#include <stdlib.h>
#include <stdio.h>
#include <gxlhosrg.h>
#include <gxlhxec.h>

void *        oima_p;
unsigned long oima_l;
char          handler_parms[128];
char          schema_uri[URI_LEN] = “file:///u/user01/myschema.xsd”;
void *        osr_p;
int           osr_l;
int           rc, rsn;

if (oima_p = malloc(GXLHXEC_MIN_OIMA_SIZE))
      { /* oima malloc succeeded   */
      oima_l = GXLHXEC_MIN_OIMA_SIZE;

 gxluInitOSRG(oima_p, oima_l,
         0,
         (void *)handler_parms,
         &rc, &rsn);
    }  /* oima malloc succeeded   */

                   
/* Load a schema and create an OSR from it. */
                
if ((oima_p > 0) && (rc == GXLHXRC_SUCCESS))
    {  /* generator initialized */
    gxluLoadSchema(oima_p,
               schema_uri,
               &rc, &rsn);

    if (rc == GXLHXRC_SUCCESS)
       { /* schema load succeeded   */

       /* Generate the OSR */
       osr_l = gxluGenOSR(oima_p,
                          &osr_p,
                          &rc, &rsn);

       if (osr_l > 0) then
        {  /* OSR generate succeeded  */ 

   <write the OSR out to a persistent repository>
   <like a file or a database so that it can be>
   <used later for parsing a document>
 
           ...
           }      /* OSR generate succeeded  */     
       ...
       }  /* schema load succeeded   */
    
      ...
      } /* generator initialized */

Usage notes

This utility generates Optimized Schema Representations in a manner similar to the xsdosrg command (see xsdosrg command reference). It provides additional flexibility and control by allowing the caller to use the following handlers to augment the default generator behavior:

StringID handler: This handler generates and/or returns an integer identifier that serves as a handle for a given string. These strings are most often the components of qualified names that are encountered in the schema text during processing. This must be implemented as a C routine, and built for the C Language Environment®. If no StringID handler is specified, then StringIDs will not be used during the generation of the OSR. All qualified names and other strings for which IDs could be used will instead be present in the OSR in their text form. The same handler may be used by the validating parser when built for the Metal C environment.
entity resolver: A Java™ routine that receives control when a reference to an external entity is made from one schema to another through an include, import, or redefine XML Schema construct. It acquires the external schema from an appropriate source, and returns it to the OSR generator for further processing. If no entity resolver is specified, the default entity resolver from the XML4J parser is used.

One or both of these routines may be specified to the OSR generator through the gxluSetStringID (gxluSetStrIDHandler — specify the StringID handler for OSR generation) and gxluSetEntityResolver (gxluSetEntityResolver — specify the entity resolver for OSR generation) utilities. Once set, the generator will make use of them until they are changed to a different value.

This utility will allocate the buffer used to receive the generated OSR, and will return the length of the buffer as its return value. The maximum length of an OSR that will be returned is 2 GB. The buffer remains allocated for the duration of the OSR generator instance, and gets freed when the instance is terminated. The caller may use or copy the OSR to another location as long as the instance is active. Referencing the OSR buffer after the generator instance has been terminated may result in unpredictable results. This buffer may also be written to a permanent location, such as a z/OS® UNIX file or an MVS™ data set, so that it can be used again at some point in the future.