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 list of return code values, see Return codes (errnos) in 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 a list of reason codes, see Reason codes in z/OS UNIX System Services Messages and Codes.
Usage notes
- 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.
- 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:
- 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.
Characteristics and restrictions
None.