STTRAN - Set Character Translation

Use the STTRAN macro instruction to initiate the use of user-specified translation tables, to modify specific character translations in active translation tables, to remove character modifications made to user-specified translation tables, and to terminate the use of user-specified translation tables. Translation tables allow characters entered at the terminal to be interpreted as other characters when they are received by TSO/E, and characters sent by TSO/E to be interpreted as other characters when they are received at the terminal.

Translation tables are built and used in pairs: one for input and one for output. Each pair is a control section consisting of a fullword containing the address of the output table, followed by a 256-byte EBCDIC table for translating the inbound characters, followed by a 256-byte EBCDIC table for translating the outbound characters. Each character in an input table must have a counterpart in its companion output table, and the characters must have the same relative position in both tables. See z/OS TSO/E Customization for instructions on building translation tables.

A translation table translates inbound data after the system translates the line code to EBCDIC characters. A translation table translates outbound data before the system translates EBCDIC characters to line code.

The STTRAN macro instruction can be used only in a VTAM® time-sharing environment. It is ignored if VTAM is not active when the macro instruction is issued.

Figure 1 shows the format of the STTRAN macro instruction. Each of the operands is explained following the figure.

Figure 1. The STTRAN macro instruction

  [symbol]     STTRAN     [ { {TABLE=address,NAME=address }} ]
                          [ { {NOTRAN                     }} ]
                          [ {                              } ]
                          [ { {TCHAR=address,SCHAR=address}} ]
                          [ { {NOCHAR,NAME=address        }} ]

                              [MF={L            } ]
                              [   {(E,ctrl addr)} ]

TABLE=address

specifies the address of a pair of user-written translation tables.

NAME=address

specifies the address of an 8-byte area containing an EBCDIC character string. (The string is left-justified and padded to the right with blanks if it is less than eight characters long.) The character string consists of the name of a member in a load module that contains user-written translation tables.

When NAME is used with NOCHAR, the STTRAN macro instruction causes the Command Processor to store the member name in the 8-byte area.

NOTRAN

specifies that the use of user-written translation tables be discontinued.

TCHAR=address

specifies the address of a 1-byte area containing the EBCDIC representation of a character as it appears at the terminal.

SCHAR=address

specifies the address of a 1-byte area containing the EBCDIC representation of a character as it appears to the system.

NOCHAR

specifies that current TCHAR and SCHAR values are no longer in effect.

MF=L | (E,ctrl addr)

indicates the form of the STTRAN macro instruction.

L: specifies the list form.
(E,ctrl addr): specifies the execute form and the address of the list form.

When control is returned to the user, register 15 contains one of the following return codes:

Table 1. Return codes from STTRAN
Return code dec(Hex)	Meaning
0(0)	Successful.
4(4)	NOTRAN or NOCHAR was specified but translation was not in effect.
8(8)	TABLE or NOCHAR was specified but the NAME operand did not specify an address.
12(C)	An internal error occurred - an unidentifiable flag was set in input register 0.