tcgetcp (BPX1TGC, BPX4TGC) — Get terminal code page names

Function

The tcgetcp callable service gets the terminal session code page names and Code Page Change Notification (CPCN) capability.

Requirements

Operation Environment
Authorization: Supervisor or problem state, any PSW key
Dispatchable unit mode: Task
Cross memory mode: PASN = HASN
AMODE (BPX1TGC): 31-bit
AMODE (BPX4TGC): 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 BPX1TGC,(File_descriptor,
              Termcp_length,
              Termcp_structure,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4TGC 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 you want to get the code page names and data conversion environment.

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
Returned parameter
Type:
Structure
Length:
Specified by Termcp_length.

The name of an area where the tcgetcp service returns the Termcp_structure. 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 tcgetcp service returns one of the following:
  • 1, if the terminal device supports a capability of forward code page names only
  • 2, if the terminal device supports a capability of forward code page names and tables
  • -1, if the request is not successful
Return_code
Returned parameter
Type:
Integer
Length:
Fullword
The name of a fullword in which the tcgetcp service stores the return code. The tcgetcp 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 tcgetcp 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.
EINVAL One of the parameters contains a value that is not correct. Consult Reason_Code returned to determine the exact reason the error occurred.
ENODEV One of the following error conditions exists:
  • The terminal device driver does not support CPCN functions.
  • CPCN functions have not been enabled. For a pseudoterminal device file, issue the tcsetcp (BPX1TSC, BPX4TSC) callable service against the master pty first, to enable CPCN support.
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 tcgetcp service stores the reason code. The tcgetcp 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

  1. For terminal devices that support forward code page names only CPCN capability, use the tcsetcp (BPX1TSC, BPX4TSC) callable service to change the terminal session data conversion environment.

    The pseudoterminal device driver supports this CPCN capability.

  2. For terminal devices that support forward code page names and tables CPCN capability, use the tcsettables (BPX1TST, BPX4TST) callable service to change the terminal session code conversion environment.

    The OCS remote-tty device driver supports this CPCN capability.

  3. In the returned Termcp_structure, if the TCCPBINARY flag is set, the code page names should not be used. BINARY indicates that the data conversion point is to perform no data conversion for the terminal session.
  4. For pseudoterminal support, the tcsetcp (BPX1TSC, BPX4TSC) callable service must be against the pty master terminal device for CPCN functions to be enabled.
  5. In the returned Termcp_structure, if the TCCPFASTP flag is set, the data conversion that is specified by the source and target code page names can be performed locally to the data conversion application. This is valid any time that a table-driven conversion can be performed. For example, the data conversion point (application) could use the z/OS UNIX iconv() service to build local data conversion tables and perform all data conversion using the local tables, instead of using iconv() all in subsequent conversions. This provides for better-performing data conversion.
  6. 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 should be terminated by a NUL (X'00') character.
    • The code page names that are contained in TCCPSRCNAME and TCCPTRGNAME are case sensitive.

Related services

Characteristics and restrictions

The tcgetcp service is supported by the pseudoterminal and (OCS) remote terminal device drivers.

Examples

For an example using this callable service, see BPX1TGC (tcgetcp) example.

Parent topic: Callable services descriptions