gxluControlOSRG — perform an OSR generator control operation

Description

This is a general purpose utility which provides operations for controlling the z/OS® XML OSR generator. The operation performed is selected by setting the ctl_option parameter using the constants defined in gxlhxoc.h and gxlhxec.h. These functions include:

GXLHXEC_OSR_CTL_FIN: The caller has finished working with a particular OSR. Reset the necessary structures so that the OIMA can be reused for subsequent generator operations on a different OSR. Receive extended diagnostic information about the current context of the OSR generator.
GXLHXEC_OSR_CTL_DIAG: The caller has finished working with a particular OSR. Receive extended diagnostic information about the current context of the OSR generator.

Performance Implications

The finish-and-reset function allows the caller to re-initialize the OIMA to make it ready to handle a new OSR. This re-initialization path enables the z/OS XML OSR generator to avoid one-time initialization pathlength that’s performed by the initialization service.

Syntax

int gxluControlOSRG(void * oima_p,
                  int ctl_operation,
                  void * ctl_data_p,                   
                  int *  rc_p,
                  int * rsn_p)

Parameters

oima_p

Supplied parameter

Type:: void *

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

ctl_operation

Supplied parameter

Type:: int

The name of the parameter containing an integer value representing one of the following operations:

GXLHXEC_OSR_CTL_FIN: This indicates that the caller wants to end processing on the current OSR. The OIMA is re-initialized to allow it to be used to process a new, different OSR. This operation will also return the extended diagnostic information area that is mapped by the gxlhosrd.h header. This includes problem determination information relevant to the current context of the OSR generator.
GXLHXEC_OSR_CTL_DIAG: This indicates that the caller wants to end processing on the current OSR. This operation will return the extended diagnostic information area that is mapped by the gxlhosrd.h header. This includes problem determination information relevant to the current context of the OSR generator.

ctl_data_p

Supplied and returned parameter

Type:: void *

A pointer to an area that will be used for a purpose that depends on the control operation being performed:

GXLHXEC_OSR_CTL_FIN: A pointer to an area that will receive the address of the extended diagnostic area mapped by gxlhosrd.h. If NULL is specified for this parameter, no extended diagnostic information will be returned. See the usage notes for more about how to use this area.
GXLHXEC_OSR_CTL_DIAG: A pointer to an area that will receive the address of the extended diagnostic area mapped by gxlhosrd.h. If NULL is specified for this parameter, no extended diagnostic information will be returned. See the usage notes for more about how to use this area.

rc_p

Returned parameter

Type:: int *

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

rsn_p

Returned parameter

Type:: int *

A pointer to an area where the service 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 service 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.

Example

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

void *        oima_p;
unsigned long oima_l;
char          handler_parms[128];
GXLHOSRD *    XDArea_p;
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   */

/* Now perform operations using the generator instance. */

if ((oima_p > 0) && (rc == GXLHXRC_SUCCESS))

  { /* generator ininitialized */

/* generate or load an OSR, generate a StringID table, etc */  

   gxluControlOSRG(oima_p,
             GXLHXEC_OSR_CTL_FIN,
             (void *)&XDArea_p,
             &rc, &rsn);

if (rc == GXLHXRC_SUCCESS)
    { /* reset succeeded    */

if (XDArea_p->strID_RC != 0)
     {  /* StringID exit failure   */
      fprintf(stderr,”StringID exit failure: %08x\n”,
              XDArea_p->strID_RC);
      ...
      } /* StringID exit failure   */

     } /* reset succeeded         */

    ...

  } /* generator ininitialized */

Usage notes

The purpose of the finish-and-reset operation of this service is to reset the necessary structures and fields within the OIMA to prepare the generator instance for reuse without the overhead of full initialization. This reset operation uses fewer CPU cycles than terminating and re-initializing from scratch. However, all schemas that are loaded, and all OSRs and StringID tables that are generated, remain in memory for the duration of the OSR generation instance. If you have a large number of schemas to process, or if the schemas are very large in size, memory constraints may become an issue. In this case, it will be necessary to terminate and re-initialize the OSR generator instance.

The extended diagnostic area returned by the GXLHXEC_OSR_CTL_FIN and GXLHXEC_OSR_CTL_DIAG operations are mapped by gxlhosrd.h. The structure in this header contains assorted diagnostic information about the particular phase of OSR generation that may have failed. The fields of this structure may be used for the duration of the OSR generator instance, but must not be referenced after the instance is terminated. Doing so may result in unpredictable results.