GXLESTRI

Restrictions: The following restrictions apply to this example:
  • This sample was designed to be a basic example of a StringID service exit, and was not designed with other system considerations in mind, such as the z/OS XML parser running in cross memory mode, SRB mode, or in a different key, for instance.
  • This sample is not designed to work with any other service exits. The exit workarea is assumed to be used by this service exit only. As a result, this memory service exit can only work independently, with no other service exits running.
This sample does the following:
  • Initializes the structure (referred to herein as XSI).
  • Searches for a string in the list and then returns its ID if the string is found.
  • Inserts new strings.
  • Validates memory requirements based on user input.
  • Defines the default values.
  • Initializes all variables in XSI.
The purpose of this StringID service exit routine is to demonstrate how a combination of Language Environment/Metal C StringID service exits could be written for the z/OS XML parserand the OSR generator.
Guidelines for using this exit with the z/OS XML parser: When this StringID service exit routine is used as an exit to the z/OS XML parser, the following guidelines apply:
  • A prolog and epilog are required. This is used to set up DSA linkage. More details are below.
  • The work area must be large enough to accommodate a DSA at the head of the work area, along with space for the stack frames. (This sample contains a main routine, a few local variables, and calls a subroutine on the first call for initialization.)
  • The work area and immediately following the DSA and the stack space contains the storage that will be mapped to the XSI structure.
Guidelines for using this exit with the OSR generator: When this StringID service exit routine is used as an exit to the OSR generator, the following guidelines apply:
  • A prolog and epilog are NOT required.
  • The main routine name must be exported.
  • The entire work area is mapped to the XSI structure defined here and must be large enough to accommodate this.
The user must pass in the value of available storage space for the XSI structure to this exit via the storage_size member in the XSI structure. Here is an example, when using the exit for the z/OS XML parser: 
       // Allocate storage. 
       stringIDArea = malloc(40960); 
       // Clear storage. 
       memset(stringIDArea,0,40960); 
       // Adjust pointer past DSA/frame(s) to beginning   
       // of storage available to the XSI structure. 
       ptr_val = (unsigned long)(stringIDArea); 
       ptr_val += XSI_DSA_SPACE; 
       XSI xsi_ptr = (XSI)(ptr_val) ; 
       // Set storage size and adjust for DSA/frame(s). 
       xsi_ptr->storage_space = 40960; 
       xsi_ptr->storage_space -= XSI_DSA_SPACE;
When using the exit for the OSR generator, use the following example: 
       // Allocate storage. 
       stringIDArea = malloc(40960); 
       // Clear storage. 
       memset(stringIDArea,0,40960); 
       XSI xsi_ptr = (XSI)(stringIDArea) ; 
       // Set storage size. 
       xsi_ptr->storage_space = 40960;

Register 14 is used to store the return address, which must be kept intact in order to exit this subroutine correctly.

This example assumes register one, which is passed in from the caller, contains the address of the parameter list. The following variables are used in the example:
SYS_SVC_PARM
A pointer to the address of the storage to be used for this exit.
STRING
The string passed in from the OSR generator.
STR_LEN
The value of the string length passed in from the OSR generator.
STRINGID
The value of the string ID set by this exit.
CCSID
The Coded Character Set Identifier passed in from the OSR Generator.
DIAG_CODE
The diagnostic code set by this exit.
RETURN_CODE
The return code set by this exit.
A description of the XSI structure is provided below. The XSI structure includes the XSI header and StringID array list.
EYE_CATCHER
The eye catcher for this structure. Used to confirm initialization.
VERSION
The version number for this exit.
STORAGE_SPACE
The value of the size of storage allocated for this exit.
DIAG_CODE
The diagnostic code set by the exit.
NEXT_ID
The next available value for the StringID.
INDEX
The index of the next XSI_NODE to update.
STRINGLIST
An array of XSI_NODE that is populated with the StringID, strings and their lengths.
A description of the prolog and epilog is provided below: 
Prolog for AMODE 31, Changes for AMODE 64 are in parenthesis 
        ST(G)M   14,12,12(13)    Save entry regs in callers area   
        L(G)     15,0(1)         Load address of Users storage     
        L(G)     15,0(15)        Load the actual storage           
        ST(G)    15,8(,13)       Save caller DSA in prev           
        ST(G)    13,4(,15)       Save current DSA in callers       
        LR(G)    13,15           Set start of storage to DSA       
        MEND                                                   
Epilog for AMODE 31, Changes for AMODE 64 are in parenthesis     
        L(G)     13,4(13)        Load the previous DSA                                         
        LM(G)    14,12,12(13)    Restore the registers                                   
        BR       14              Return                                   
        MEND
Parent topic: Exit examples