tcsetcp (BPX1TSC, BPX4TSC) — Set terminal code page names

Function

The tcsetcp callable service sets the terminal session code page names 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 (BPX1TSC): 31-bit
AMODE (BPX4TSC): 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

The syntax format is as follows:
CALL BPX1TSC,(File_descriptor,
              Termcp_length,
              Termcp_structure,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4TSC 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 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 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).

Return_value
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the tcsetcp 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 tcsetcp service stores the return code. The tcsetcp service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The tcsetcp 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 parameters contains a value that is not correct. Consult Reason_Code returned to determine the exact reason the error occurred.
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 One of the following error conditions exists:
  • CPCN functions have not been enabled. tcsetcp must be issued against the master pty before any CPCN function can be issued against the slave pty.
  • The terminal device driver does not support the forward code page names only 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 tcsetcp service stores the reason code. The tcsetcp 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 used for the session is not encoded to the specified source (ASCII) and target (EBCDIC) code pages.
  1. Use the tcsetcp callable service to send new code page names to the terminal session data conversion point to change the data conversion environment.

    The tcsetcp callable service is used with terminal devices that support the forward code page names only CPCN capability. Use the tcgetcp (BPX1TGC, BPX4TGC) callable service to determine the terminal device CPCN capability.

  2. 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.
  3. The tcsetcp callable service is supported by the pseudoterminal (pty) device driver. For terminal sessions that use pty support, the data conversion point is the application that uses the master pty. An example data conversion point is the rlogin server. Here, rlogin uses CPCN functions to change the ASCII source or EBCDIC target code pages to use in its data conversion for the terminal session.

    During its processing of the tcsetcp service, the pty device driver applies the new code page names once the pty outbound data queue is drained. When this occurs, the pty input data queue is also flushed, and a TIOCXPKT_CHCP packet exception event is generated (if extended packet mode is enabled) to notify the master pty application that the code page names have been changed. The master pty application can then use the tcgetcp (BPX1TGC, BPX4TGC) callable service to retrieve the new code page names and establish the new data conversion environment.

    The tcsetcp service is supported by both the master and slave pty device drivers. However, CPCN functions must first be enabled by the application that uses the master pty; enabling CPCN functions is performed by the system during the initial tcsetcp invocation against the master pty device. When the tcsetcp invocation is performed against the master pty it may be subsequently issued against the slave pty.

  4. 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.
  5. Use the tcsetcp 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 from their current values.
    Attention: 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.
  6. Use the TCCPFASTP flag to indicate to the data conversion point (such as rlogin) that the data conversion that is specified by the source and target code page names can be performed locally to the application. This is valid any time that a table-driven conversion can be performed. For example, the data conversion point (application) could use the iconv() command to build the local data conversion tables and perform all data conversion using the local tables, instead of using iconv() in subsequent conversions. This provides for better-performing data conversion.
  7. The following table defines the processing of the SIGTTOU signal when the tcsetcp 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.
    Ignored or blocked

    The SIGTTOU signal is not sent.
    The function continues normally.

Related services

Characteristics and restrictions

The tcsetcp service is supported by the pseudoterminal device driver.

Examples

For an example using this callable service, see BPX1TSC (tcsetcp) example.

Parent topic: Callable services descriptions