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:
See also What is the Best Internationalization Approach to use?
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
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
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.
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.
This section covers the following topics:
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".
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.
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.
This section covers the following topics:
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".
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 EXX951.SRCE. See Contents of Mainframe Installation Medium.
The user exit provides two separate functions, CONVERT and
GETLENGTH. The field UE$FCT indicates the function to
execute.
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.
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.
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.
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 |
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:
UE$DLEN. If the output buffer in the CONVERT function
is too small, error 9999 must be returned to the caller.
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=EXB951.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
User-written ICU converters (codepages) are not supported under z/OS.