Initialize an OSR generator instance. This establishes a context within which the OSR generator performs operations on schemas, Optimized Schema Representations (OSRs), and StringID tables. This context is defined by the OSR generator Instance Memory Area (OIMA).
The OIMA must be initialized before any OSR generation operations are performed. If operations are to be performed on different OSRs, the caller may enhance performance by resetting the OIMA through a control operation (see gxluControlOSRG), rather than terminating the generator instance and re-initializing. There are implications for memory consumption that must be considered when multiple OSRs are created from the same generator instance. See the usage notes below.
|
A pointer to an OSR generator Instance Memory Area (OIMA). This area must be at least GXLHXEC_MIN_OIMA_SIZE bytes long. It is used as the work area for the OSR generator.
The length of the OSR generator Instance Memory Area (OIMA) pointed to by the oima_p parameter.
A pointer to an area which is passed to all system service exits, handlers, and resolvers. This provides for communication between the caller of the z/OS® XML OSR generator and its exit routines. Specify the NULL pointer if no parameter is required for communication.
A pointer to an area where the service stores the return code.
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 return code (see below).
Return and Reason Codes:
On return from a call to this utility, register 15 will contain the return code. The return and reason code are both also 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.
#include <stdlib.h>
#include <gxlhosrg.h>
#include <gxlhxec.h>
void * oima_p;
unsigned long oima_l;
char handler_parms[128];
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);
/* Use the OSR generation instance to perform schema operations … */
} /* oima malloc succeeded */When creating multiple OSRs, the best practice will usually be to initialize one generator instance, and use it for all of the generation operations, with control requests to reset the generator between OSRs. This will consume fewer CPU cycles, and provide better overall performance than initializing and terminating a generator instance for each OSR being created or operated upon. However, all generated OSRs will remain in memory for the duration of the generator instance. If memory constraints are a concern, or you plan to generate OSRs for either a large number of schemas, or for schemas that are very large, you may need to terminate and re-initialize the OSR generator.