tcsettables (BPX1TST, BPX4TST) — Set terminal code page names and conversion tables

Function

The tcsettables callable service sets the terminal session code page names and conversion tables to the specified values.

Requirements

Operation	Environment
Authorization:	Supervisor or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1TST):	31-bit
AMODE (BPX4TST):	64-bit
ASC mode:	Primary mode
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPX1TST,(File_descriptor,
              Termcp_length,
              Termcp_structure,
              Srctable,
              Trgtable,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4TST with the same parameters.

Parameters

File_descriptor

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the file descriptor of the terminal for which the code page names and data conversion tables are to be set.

Termcp_length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of the fullword that contains the length of the Termcp_structure. The Termcp_structure is mapped by BPXYTCCP, and has a length of TCCP#LENGTH. See BPXYTCCP — Map the terminal control code page structure.

Termcp_structure

Supplied parameter

Type:: Structure
Length:: Specified by Termcp_length.

The name of an area that contains the code page information that is to be set. This structure contains the source (ASCII) code page name, target (EBCDIC) code page name, and control flags. The Termcp_structure is mapped by the BPXYTCCP macro (see BPXYTCCP — Map the terminal control code page structure).

Srctable

Supplied parameter

Type:: Character string
Character set:: No restriction
Length:: 256 bytes

The name of a field that contains a 256-byte data conversion table for the source-to-target (ASCII to EBCDIC) data conversion. The byte offset into this table corresponds to the character code from the source (ASCII) code page. The data value at each offset is the converted target (EBCDIC) character code.

Trgtable

Supplied parameter

Type:: Character string
Character set:: No restriction
Length:: 256 bytes

The name of a field that contains a 256-byte data conversion table for the target-to-source (EBCDIC to ASCII) data conversion. The byte offset into this table corresponds to the character code from the target (EBCDIC) code page. The data value at each offset is the converted source (ASCII) character code.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the tcsettables service returns 0 if the request is successful, or -1 if it is not successful.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the tcsettables service stores the return code. The tcsettables service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The tcsettables service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EBADF	File_descriptor is an incorrect open file descriptor.
EINTR	A signal interrupted the call.
EINVAL	One of the following error conditions exists: The value of `Termcp_length` was not valid. An incorrect combination of multi-byte code page names was specified in the Termcp_structure. One of the following applies: The source code page that was specified in TCCPSRCNAME specified a supported ASCI multi-byte code page, and the TCCPTRGNAME did not specify a supported EBCDIC multi-byte code page. The target code page that was specified in TCCPTRGNAME specified a supported EBCDIC multi-byte code page, and the TCCPSRCNAME did not specify a supported ASCII multi-byte code page.
EIO	The process group of the process that is issuing the function is an orphaned, background process group, and the process that is issuing the function is not ignoring or blocking SIGTTOU.
ENODEV	The terminal device driver does not support the forward code page names and tables CPCN capability.
ENOTTY	The file that is associated with the file descriptor is not a terminal device.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the tcsettables service stores the reason code. The tcsettables service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

Usage notes

Attention: Use this service carefully. By changing the code pages for the data conversion, you may cause unpredictable behavior in the terminal session if the actual data that is used for the session is not encoded to the specified source (ASCII) and target (EBCDIC) code pages.

Use the tcsettables callable service to send new code page names and data conversion tables to the terminal session data conversion point to change the data conversion environment.
The tcsettables callable service is used with terminal devices that support the forward code page names and tables CPCN capability. Use the tcgetcp (BPX1TGC, BPX4TGC) callable service to determine the terminal device CPCN capability.
The BPXYTCCP macro should be used to map the Termcp_structure and define the equates for the flag byte values. Note the following about BPXYTCCP:
- BPXYTCCP can be used to define either a DSECT or an inline structure. This is determined by the DSECT= keyword.
- The code page names that are contained in TCCPSRCNAME and TCCPTRGNAME must be terminated by a NUL (X'00') character.
- The code page names that are contained in TCCPSRCNAME and TCCPTRGNAME are case sensitive.
The OCS remote-tty (rty) device driver supports this function. For OCS terminal sessions, the data conversion is performed by OCS outboard on the AIX® server system. Use the tcsettables service to specify new code pages and conversion tables that are to be used in the data conversion.
During its processing of the tcsettables service, the OCS rty device driver applies the new code page names when the outbound data queue is drained. When this occurs, the rty input data queue is also flushed, and the new conversion environment takes effect.
The Srctable and Trgtable parameters are used as follows:
- If the code page names that are specified in the Termcp_structure are for supported double-byte data conversion the SrcTable and TrgTable arguments are not used. The following double-byte translation is supported for OCS sessions:
  Source (ASCII) code page Target (EBCDIC) code page
  
  IBM-eucJP IBM-939
  
  IBM-932 IBM-939
- If TCCPSRCNAME specifies ISO8859-1 and TCCPTRGNAME specifies IBM-1047, OCS uses its own data conversion tables and the Srctable and Trgtable parameters are not used.
- Otherwise the conversion tables in Srctable and Trgtable are used.
The data conversion for a terminal session is performed on a session (terminal file) basis. If you change the data conversion characteristics for one file descriptor, the new data conversion applies to all open file descriptors that are associated with this terminal file.
Use the tcsettables callable service to notify the data conversion point to stop data conversion. This is done by setting the TCCPBINARY flag. If this flag is set, the source and target code page names (TCCPSRCNAME and TCCPTRGNAME, respectively) are not changed; the Srctable and Trgtable parameters are not used.
Note: Use this option carefully. When the data conversion is disabled, the z/OS shell cannot be used until the data conversion is reenabled, using valid code pages for the terminal session.
The TCCPFASTP flag is not used by the OCS rty device driver. The value of this flag has no effect and is ignored.
The following table defines the processing of the SIGTTOU signal when the tcsettables service is called from a background process group against its controlling terminal:
SIGTTOU processing Expected behavior

Default or signal handler The SIGTTOU signal is generated. The function is not performed. Return_value is set to -1, and Return_code is set to EINTR.

Source (ASCII) code page	Target (EBCDIC) code page
IBM-eucJP	IBM-939
IBM-932	IBM-939

SIGTTOU processing	Expected behavior
Default or signal handler	The SIGTTOU signal is generated. The function is not performed. Return_value is set to -`1`, and Return_code is set to EINTR.

Characteristics and restrictions

None.

Examples

For an example using this callable service, see BPX1TST (tcsettables) example.