
	Version 9.6	SEARCH CONTENTS \| PDF BOOKS \| HOME UP PREV NEXT

— Administration under z/OS —

Configuring Broker for Internationalization

It is assumed that you have read the document Internationalization with EntireX and are familiar with the various internationalization approaches described there.

This document explains in detail how to configure the broker for the various internationalization approaches, how to write a translation user exit and how to write a SAGTRPC user exit. It covers the following topics:

Configuring Translation
Configuring Translation User Exits
Configuring ICU Conversion
Configuring SAGTRPC User Exits
Writing Translation User Exits
Writing SAGTRPC User Exits
Building and Installing ICU Custom Converters

Configuring Translation

To configure translation

In the Broker attribute file, set the service-specific or topic-specific broker attribute TRANSLATION to SAGTCHA as the name of the translation routine. Example:
```
TRANSLATION=SAGTCHA
```

Configuring Translation User Exits

To configure translation user exits

As a prerequisite, the user-written translation module must be accessible to the Broker worker threads.

Copy the user-written translation module into any library of the Broker's steplib concatenation.
In the Broker attribute file, set the service-specific or topic-specific broker attribute TRANSLATION to the name of the user-written translation routine. Example:
```
TRANSLATION=MYTRANS
```

Configuring ICU Conversion

To configure ICU conversion

In the Broker attribute file, set the service-specific or topic-specific broker attribute CONVERSION. Examples:
- ICU Conversion with SAGTCHA for ACI-based Programming:
```
CONVERSION=(SAGTCHA,TRACE=1,OPTION=SUBSTITUTE)
```
- ICU Conversion with SAGTRPC for RPC-based Components and Reliable RPC:
```
CONVERSION=(SAGTRPC,TRACE=2,OPTION=STOP)
```
We recommend always using SAGTRPC for RPC data streams. Conversion with Multibyte, Double-byte and other Complex Codepages will always be correct, and Conversion with Single-byte Codepages is also efficient because SAGTRPC detects single-byte codepages automatically. See Conversion Details.
Optionally configure a CONVERSION OPTION to tune error behavior to meet your requirements; see OPTION Values for Conversion.
For the Broker attribute, check if ICU conversion is possible, that is, the attribute ICU-CONVERSION is either
- not defined, its default is YES
- set to YES

To configure locale string defaults (optional)

If the broker's locale string defaults do not match your requirements (see Broker's Locale String Defaults), we recommend you assign suitable locale string defaults for your country and region, see the respective attribute in Codepage-specific Attributes under Broker Attributes for how to customize the broker's locale string defaults.

To customize mapping of locale strings (optional)

If the built-in locale string mapping mechanism does not match your requirements, you can assign specific codepages to locale strings. See Broker's Built-in Locale String Mapping and locale-string for information on customizing the mapping of locale strings to codepages.

Configuring SAGTRPC User Exits

To configure SAGTRPC user exits

As a prerequisite, the user-written conversion module must be accessible to the Broker worker threads.

Copy the user-written conversion module into any library of the Broker's steplib concatenation.
In the Broker attribute file, set the service-specific or topic-specific broker attribute CONVERSION to the name of the user-written SAGTRPC user exit routine. Example:
```
CONVERSION=(MYTRANS,TRACE=1)
```

To configure locale string defaults

If the broker's locale string defaults do not match your requirements, we recommend you assign suitable locale string defaults for your country and region. See the appropriate attribute under Codepage-specific Attributes under Broker Attributes for information on customizing broker's locale string defaults, and also Locale String Mapping.

To customize mapping of locale strings

If the broker's built-in locale string mechanism does not match your requirements, you can assign specific codepages to locale strings. See Broker's Built-in Locale String Mapping and the appropriate attribute under Codepage-specific Attributes under Broker Attributes for information on customizing broker's locale string defaults.

Writing Translation User Exits

This section covers the following topics:

Introduction
Structure of the TRAP Control Block
Using the TRAP Fields

Introduction

EntireX Broker provides an interface to enable user-written translation routines in the programming language Assembler. It contains three parameters:

The address of the TRAP control block (TRAP = Translation Routine / Area for Parameters).
The address of a temporary work area. It is aligned to fullword / long integer boundary (divisible by 4). The work area can only be used for temporary needs and is cleared after return.
A fullword (long integer) that contains the length of the work area.

Note:
Names for user-written translation routines starting with "SAG" are reserved for Software AG usage and must not be used, e.g. "SAGTCHA" and "SAGTRPC".

Structure of the TRAP Control Block

The Assembler dummy section TR$TRAP covers the layout of the TRAP control block:

TR$TRAP  DSECT ,
TR$TYPE  DS       F            TRAP type
TR$TYP2  EQU      2            TRAP type ETB 121
TR$ILEN  DS       F            Input buffer length
TR$IBUF  DS       A            Address of input buffer
TR$OLEN  DS       F            Output buffer length
TR$OBUF  DS       A            Address of output buffer
TR$DLEN  DS       F            Length of data returned:
*                              Should be set to the minimum value of TR$ILEN 
*                              and TR$OLEN.
TR$SHOST DS       F            Sender's host:
*                              x'00000000' = little endian
*                              x'00000001' = big endian
TR$SCODE DS       F            Sender's character set:
SEBCIBM  EQU      X'00000022'  EBCDIC (IBM)
SEBCSNI  EQU      X'00000042'  EBCDIC (SNI)
SA88591  EQU      X'00000080'  ASCII
TR$RHOST DS       F            Receiver's host     --> see TR$SHOST
TR$RCODE DS       F            Receiver's char set --> see TR$SCODE
TR$BHOST DS       F            BROKER host         --> see TR$SHOST
TR$BCODE DS       F            BROKER char set     --> see TR$SCODE
TR$SENVA DS       F            Sender's ENVIRONMENT field supplied:
OFF      EQU      X'00000000'  ENVIRONMENT field not set
ON       EQU      X'00000001'  ENVIRONMENT field set
*
TR$RENVA DS       F            Receiver's ENVIRONMENT field supplied:
*                              --> see TR$SENVA
TR$SENV  DS       CL32         Sender's ENVIRONMENT field
TR$RENV  DS       CL32         Receiver's ENVIRONMENT field
TR$LEN   EQU      *-TR$TRAP    Length of TRAP

The translation routine USRTCHA is an example of the translation user exit, it is contained in the EntireX Common source library.

Using the TRAP Fields

The TR$DLEN must be supplied by the user-written translation routine. It tells the Broker the length of the message of the translation. In our example its value is set to the minimum length of the input and output buffer.

All other TRAP fields are supplied by the Broker and must not be modified by the user-written translation routine.

The incoming message is located in a buffer pointed to by TR$IBUF. The length (not to be exceeded) is supplied in TR$ILEN. The character set information from the send buffer can be taken from TR$SCODE.

The outgoing message must be written to the buffer pointed to by TR$OBUF. The length of the output buffer is given in the field TR$OLEN. The character set is specified in TR$RCODE. If the addresses given in TR$IBUF and TR$OBUF point to the same location, it is not necessary to copy the data from the input buffer to the output buffer.

The environment fields TR$SENVA and TR$RENVA are provided to handle site-dependent character set information. For the SEND and/or RECEIVE functions, you can specify data in the ENVIRONMENT field of the Broker ACI control block. This data is translated into the codepage of the platform where EntireX Broker is running (see field TR$BCODE) and is available to the TR$SENV or TR$RENV field in the TRAP control block. TR$SENVA or TR$RENVA are set to ON if environmental data is available.

The sample source USRTCHA contains a section to handle the ENVIRONMENT value *NONE. The translation will be skipped if *NONE is supplied by the sender or receiver. Any values given in the API field ENVIRONMENT must correspond to the values handled in the translation routine.

Writing SAGTRPC User Exits

This section covers the following topics:

Introduction
Structure of the User Exit Control Block
Using the User Exit Interface Fields
Character Set and Codepage

Introduction

EntireX Broker provides an interface to SAGTRPC user exit routines written in the programming language Assembler. The interface contains three parameters:

The address of the UE (user exit) control block.
The address of a temporary work area. It is aligned to a fullword / long-integer boundary (divisible by 4). The work area can only be used temporarily and is cleared after return.
A fullword (long integer) that contains the length of the work area.

Note:
Names for conversion routines starting with "SAG" are reserved for Software AG usage and must not be used, e.g. "SAGTCHA" and "SAGTRPC".

Structure of the User Exit Control Block

The Assembler dummy section UE$CB shows the layout of the user exit control block.

UE$CB    DSECT , ...... User Exit Control Block                          
*                       ***********************                          
*                                                            Direction   
*                                                            ---------   
UE$VERS  DS    F        UECB version                          input      
UE$VER1  EQU   1        UECB version 1                                   
UE$IBUF  DS    A        Address of input buffer               input      
UE$ILEN  DS    F        Input buffer length                   input      
UE$OBUF  DS    A        Address of output buffer              input      
UE$OLEN  DS    F        Output buffer length                  input      
UE$DLEN  DS    F        Length of data returned               output     
*                                                                        
UE$SHOST DS    F        Senders host:                         input      
*                       x'00000000' = little endian                      
*                       x'00000001' = big endian                         
*                                                                        
UE$SCODE DS    F        Senders character set:                input      
SEBCIBM EQU X'00000022' EBCDIC (IBM)                                     
SEBCSNI EQU X'00000042' EBCDIC (SNI)                                     
SA88591 EQU X'00000080' ASCII
*                                                                    
UE$RHOST DS    F        Receivers host      --> see UE$SHOST  input  
UE$RCODE DS    F        Receivers char set  --> see UE$SCODE  input  
UE$BHOST DS    F        BROKER host         --> see UE$SHOST  input  
UE$BCODE DS    F        BROKER char set     --> see UE$SCODE  input  
*                                                                    
UE$SCP   DS    F        Sender   Codepage number                 
UE$RCP   DS    F        Receiver Codepage number                 
UE$BCP   DS    F        Broker   Codepage number                 
*                                                                    
UE$FCT   DS    CL1      Function                              input  
FCTCONV  EQU   C'C'     Function CONVERT                             
FCTGLEN  EQU   C'L'     Function GETLENGTH                           
UE$DIR   DS    CL1      Direction                             input  
DIRS2B   EQU   C'1'     Direction Sender to Broker                   
DIRS2R   EQU   C'2'     Direction Sender to Receiver                 
DIRB2R   EQU   C'3'     Direction Broker to Receiver                 
UE$FMT   DS    CL2      Format                                input  
FMTUSER  EQU   C'01'    User Data like User ID, Program, Library      
FMTMETA  EQU   C'02'    Meta Data Header                             
FMTFB    EQU   C'03'    Format Buffer  
FMTSB    EQU   C'04'    String Buffer 
FMTVBN   EQU   C'05'    Meta data value buffer 
FMTPRE   EQU   C'99'    Preview format buffer                        
FMTA     EQU   C'A '    Data Type A                                  
FMTAV    EQU   C'AV'    Data Type AV                                 
FMTB     EQU   C'B '    Data Type B                                  
FMTBV    EQU   C'BV'    Data Type BV                                 
FMTD     EQU   C'D '    Data Type D                                  
FMTF4    EQU   C'F4'    Data Type F4                                 
FMTF8    EQU   C'F8'    Data Type F8                                 
FMTI1    EQU   C'I1'    Data Type I1                                 
FMTI2    EQU   C'I2'    Data Type I2                                 
FMTI4    EQU   C'I4'    Data Type I4                                 
FMTK     EQU   C'K '    Data Type K                                  
FMTKV    EQU   C'KV'    Data Type KV                                 
FMTL     EQU   C'L '    Data Type L                                  
FMTN     EQU   C'N '    Data Type N                                  
FMTP     EQU   C'P '    Data Type P                                  
FMTT     EQU   C'T '    Data Type T                                  
FMTU     EQU   C'U '    Data Type U                                  
FMTUV    EQU   C'UV'    Data Type UV                                 
UE$ETXT  DS    CL40     Error Text output                            
UE$LEN   EQU   *-UE$CB  Length of UECB                               
         SPACE ,

The user-written conversion exit example USRTRPC is delivered in the EntireX common source library EXX960.SRCE. See Contents of Mainframe Installation Medium.

Using the User Exit Interface Fields

The user exit provides two separate functions, CONVERT and GETLENGTH. The field UE$FCT indicates the function to execute.

Errors

Both functions can send an error, using register 15 in the range 1 to 9999 to SAGTRPC together with an error text in the field UE$ETXT.

A value of 0 returned in register 15 means successful response.
Error 9999 is reserved for output buffer overflow. See CONVERT Function.
When an error occurs, the conversion of the message will be aborted and the error text will be sent to the receiver (client or server). The error is prefixed with the error class 1011. See Message Class 1011 - User-definable SAGTRPC Conversion Exit.

Example:

The user exit returns 1 in register 15 and the message "Invalid Function" in UE$ETXT. The receiver gets the error message 10110001 Invalid Function.

CONVERT Function

This function has to be executed when the contents of UE$FCT match the definition FCTCONV.

UE$DLEN must be supplied by SAGTRPC's user-written conversion exit. Its value must be set to the length of the output buffer.

All other interface fields are supplied by the Broker and must not be modified by SAGTRPC's user-written conversion exit.

The incoming data is located in a buffer pointed to by UE$IBUF. UE$ILEN defines the length.

The outgoing converted message must be written to the buffer pointed to by UE$OBUF. The field TR$OLEN defines the maximum length available.

For variable length data such as AV and KV, an output buffer overflow can occur if the message size increases after conversion or the receiver's receive buffer is too small. In this case error 9999 "output buffer overflow" must be returned, which calls the GETLENGTH Function for the remaining fields.

GETLENGTH Function

The GETLENGTH function evaluates the needed length of the output buffer after conversion. An actual conversion must not be performed. The length needed must be returned in the field UE$OLEN.

The GETLENGTH function is called for remaining fields after the CONVERT function returned the error 9999 "output buffer overflow".

The purpose of this function is to evaluate the length needed by the receiver's receive buffer. This length is returned to the receiver in the ACI field RETURN-LENGTH. The receiver can then use the Broker ACI function RECEIVE with the option LAST together with a receive buffer large enough to reread the message.

Character Set and Codepage

The character-set information used is the same as in the user-written translation routine and is taken from UE$SCODE (for the sender), UE$RCODE (for the receiver) and UE$BCODE (for the Broker). The character-set information depends on the direction information given in the field UE$DIR. See the following table:

`UE$DIR`	From Character Set	To Character Set
`DIRS2B` (Sender to Broker)	`UE$SCODE`	`UE$BCODE`
`DIRS2R` (Sender to Receiver)	`UE$SCODE`	`UE$RCODE`
`DIRB2R` (Broker to Receiver)	`UE$BCODE`	`UE$RCODE`

Alternatively, the codepage as derived from the locale string mapping process is provided in UE$SCP (sender codepage), UE$RCP (receiver codepage) and UE$BCP (Broker codepage), and can be used to find the correct conversion table. See the following table and also Locale String Mapping.

`UE$DIR`	From Codepage	To Codepage
`DIRS2B` (Sender to Broker)	`UE$SCP`	`UE$BCP`
`DIRS2R` (Sender to Receiver)	`UE$SCP`	`UE$RCP`
`DIRB2R` (Broker to Receiver)	`UE$BCP`	`UE$RCP`

Software AG IDL Data Types to Convert

The field UE$FMT provides the SAGTRPC user-written conversion exit with the information on the IDL data types to convert. Each data type can be handled independently.

`UE$FMT`	Data to be converted	Notes
`FMTA`	IDL data type A	1, 3, 4
`FMTAV`	IDL data type AV	4, 5
`FMTB`	IDL data type B	1, 2, 7
`FMTBV`	IDL data type BV	1, 2, 7
`FMTD`	IDL data type D	1, 2, 7
`FMTF4`	IDL data type F4	1, 2, 7
`FMTF8`	IDL data type F8	1, 2, 7
`FMTI1`	IDL data type I1	1, 2, 7
`FMTI2`	IDL data type I2	1, 2, 7
`FMTI4`	IDL data type I4	1, 2, 7
`FMTK`	IDL data type K	1, 3, 4
`FMTKV`	IDL data type KV	4, 5
`FMTL`	IDL data type L	1, 2, 7
`FMTN`	IDL data type N	1, 2, 7
`FMTP`	IDL data type P	1, 2, 7
`FMTT`	IDL data type T	1, 2, 8
`FMTU`	IDL data type U	1, 2, 7
`FMTUV`	IDL data type UV	1, 2, 7
`FMTUSER`	RPC user data such as user ID, library, program...	1, 3, 4
`FMTMETA`	RPC metadata	1, 2, 7
`FMTFB`	RPC format buffer	1, 2, 7
`FMTSB`	RPC metadata variable length	4, 5, 7
`FMTPRE`	Preview data	4, 6, 7

Notes:

Field length is constant.
The field content length must not increase or decrease during conversion. If this happens, the user exit should produce an error.
If the field content length decreases during the conversion, suitable padding characters (normally blanks) have to be used.
If the field content length increases during conversion and exceeds the field length, the contents must be truncated or, alternatively, the conversion can be aborted and an error produced.
If the contents are truncated, character boundaries are the responsibility of the user exit. Complete valid characters after conversion have to be guaranteed. This may be a complex task for codepages described under Conversion with Multibyte, Double-byte and other Complex Codepages. For Conversion with Single-byte Codepages it is simple because the character boundaries are the same as the byte boundaries.
The field length can decrease or increase during the conversion up to the output buffer length. The new field length must be returned in UE$DLEN. If the output buffer in the CONVERT function is too small, error 9999 must be returned to the caller.
The field buffer should continue to be converted until the output buffer is full or the input buffer has been processed. If the field content length increases or truncations occur, no error should be produced. If the field content length decreases, there should be no padding. The new field length should simply be returned to the caller.
Codepages used for RPC data streams must meet several requirements. See Codepage Requirements for RPC Data Stream Conversions. If these are not met, the codepage cannot be used to convert RPC data streams.

To assemble and link the SAGTRPC user-written conversion exit

Assemble the conversion exit to a module named USRTRPC. This name cannot be changed.

Link the USRTRPC module to the supplied SAGTRPC module. You can give the resulting load module any name that does not begin with "SAG". Names starting with "SAG", such as "SAGTCHA" and "SAGTRPC", are reserved for Software AG. In the example below, the module is named "USRTRANS".

//LKED    EXEC PGM=HEWL,                                   
//   PARM='LET,LIST,MAP,AMODE(31),XREF,CALL,RENT' 
//SYSUT1   DD UNIT=<unit>,SPACE=(CYL,(1,1))
//SYSUT2   DD UNIT=<unit>,SPACE=(CYL,(1,1))               
//SYSPRINT DD SYSOUT=*
//EXBLOAD  DD DISP=SHR,DSN=EXB960.LOAD(SAGTRPC)
//USRLOAD  DD DISP=SHR,DSN=<MyLoadLib>(USRTRPC)
//SYSLIN   DD *
 INCLUDE EXBLOAD(SAGTRPC)  
 INCLUDE USRLOAD(USRTRPC) 
 ORDER CEESTART             
 ENTRY CEESTART             
 NAME USRTRANS(R)           
/*
//SYSLMOD  DD DISP=SHR,DSN=. . . .(USRTRANS)
//SYSIN    DD DUMMY

Building and Installing ICU Custom Converters

User-written ICU converters (codepages) are not supported under z/OS.

SEARCH CONTENTS | PDF BOOKS | HOME UP PREV NEXT