__tcsettables() — Set terminal code page names and conversion tables
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
z/OS® UNIX | both |
Format
#define _OPEN_SYS_PTY_EXTENSIONS
#include <termios.h>
int __tcsettables(int fildes, size_t termcplen,
const struct __termcp *termcpptr,
const char atoe[256],
const char etoa[256]);
General description
The __tcsettables() function changes the data conversion environment for terminal sessions that support the “forward code page names and tables” Code Page Change Notification (CPCN) capability. The OCS remote-tty (rty) device driver supports this capability.
- fildes
- The file descriptor of the terminal for which you want to set the code page names and data conversion tables.
- termcplen
- The length of the passed termcp structure.
- termcpptr
- A pointer to a __termcp structure. A __termcp structure contains
the following members:
- __tccp_flags
- Flags. The following symbols are defined as bitwise distinct
values. Thus, __tccp_flags is the bitwise inclusive-OR of these symbols:
- Symbol
- Meaning
- _TCCP_BINARY
- Use _TCCP_BINARY to notify the data conversion point to stop
data conversion. If this flag is set the source and target code page
names (__tccp_fromname and __tccp_toname respectively) are not changed,
and the data conversion tables atoe and etoa are
not used.
Attention: Use this option carefully. Once the data conversion is disabled the z/OS shell cannot be used until the data conversion is re-enabled, using valid code pages for the terminal session.
- _TCCP_FASTP
- Use _TCCP_FASTP to indicate to the data conversion point that
the data conversion specified by the source and target code page names
can be performed locally by the application that performs the data
conversion. This is valid any time that a table-driven conversion
can be performed.
This value is not used by the OCS rty device driver and thus has no effect.
- __tccp_fromname
- The source code page name; typically this is the ASCII code
page name. __tccp_fromname is a NULL-terminated string with a maximum
length of _TCCP_CPNAMEMAX, including the NULL (\00) character.
__tccp_fromname is case-sensitive.
- __tccp_toname
- The target code page name; typically this is the EBCDIC code
page name. __tccp_toname is a NULL-terminated string with a maximum
length of _TCCP_CPNAMEMAX, including the NULL (\00) character.
__tccp_toname is case-sensitive.
- const char atoe[256]
- 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.
- const char etoa[256]
- 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.
For terminal sessions that use the OCS rty device driver, the ASCII/EBCDIC data conversion is performed outboard by OCS on the AIX server system. Use the __tcsettables() function to specify new code pages and conversion tables to be used in the data conversion.
During its processing of the __tcsettables() function, the OCS rty device driver applies the new code page names once the outbound data queue is drained. When this occurs, the rty input data queue is also flushed and the new conversion environment takes effect.
- If the code page names specified in the __termcp structure are for supported double-byte data conversion then the atoe and etoa arguments are not used. The following double-byte translation is supported for OCS sessions:
- If __fromname specifies ISO8859-1 and __toname specifies IBM-1047 then OCS uses its own data conversion tables and atoe and etoa arguments are not used.
- Otherwise the conversion tables in atoe and etoa are used.
When __tcsettables() is issued from a process in a background process group, SIGTTOU is processing in this way:
Processing for SIGTTOU | Expected Behavior |
---|---|
Default or signal handler | The SIGTTOU signal is generated. The function is not performed. __tcsettables() returns -1 and sets errno to EINTR. |
Ignored or blocked | The SIGTTOU signal is not sent. The function continues normally. |
Returned value
If successful, __tcsettables() returns 0.
- Error Code
- Description
- EBADF
- fildes is not a valid open file descriptor.
- EINTR
- A signal interrupted the call.
- EINVAL
- One of the following error conditions exists:
- The value of termcplen was invalid.
- An invalid combination of multibyte code page names was specified
in the __termcp structure.
One of the following applies:
- The source code page specified in __tccp_fromname specified a supported ASCII multibyte code page and the __tccp_toname did not specify a supported EBCDIC multibyte code page.
- The target code page specified in __tccp_toname specified a supported EBCDIC multibyte code page and the __tccp_fromname did not specify a supported ASCII multibyte code page.
- EIO
- The process group of the process issuing the function is an orphaned, background process group, and the process 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 associated with fildes is not a terminal device.
Example
#define _OPEN_SYS_PTY_EXTENSIONS
#include <fcntl.h>
#include <unistd.h>
#include <stdio.h>
#include <termios.h>
#include <iconv.h>
main()
{
struct __termcp mytermcp; /* local __termcp */
unsigned char *intabptr; /* pointer to input table */
unsigned char *outtabptr; /* pointer to output table */
unsigned char intab[256],
atoe[256],
etoa[256]; /* conversion tables */
iconv_t cd; /* conversion descriptor */
size_t inleft; /* number of bytes left in input */
size_t outleft; /* number of bytes left in output */
int i; /* loop variable */
int rv; /* return value */
int cterm_fd; /* file descriptor for controlling
terminal */
if ((cterm_fd = open("/dev/tty",O_RDWR)) == -1)
{
printf("No controlling terminal established. ");
printf("Code pages were not changed.\n");
exit(0);
}
if ((rv = __tcgetcp(cterm_fd,sizeof(mytermcp),&mytermcp))== -1)
{
perror("__tcgetcp() error");
exit(1);
}
if (_TCCP_BINARY == (mytermcp.__tccp_flags & _TCCP_BINARY))
{
printf("Binary mode is in effect. No change made.\n");
exit(0);
}
if (rv == _CPCN_TABLES) {
/* build ASCII -> EBCDIC conversion table */
strcpy(mytermcp.__tccp_fromname,"IBM-850");
if ((cd = iconv_open(mytermcp.__tccp_toname,
mytermcp.__tccp_fromname)) ==
(iconv_t) (-1)) {
fprintf(stderr,"Cannot open converter from %s to %s\n",
mytermcp.__tccp_fromname,mytermcp.__tccp_toname);
exit(1);
}
/* build input table with character values of 00 - FF */
for (i=0; i<256; i++ ) {
intab[i] = (unsigned char) i;
} /* endfor */
inleft = 256;
outleft = 256;
intabptr = intab;
outtabptr = atoe;
/* build ASCII -> EBCDIC conversion table. */
rv = iconv(cd,&intabptr, &inleft, &outtabptr, &outleft);
if (rv == -1) {
fprintf(stderr,"Error in building ASCII to EBCDIC table\n");
exit(1);
}
iconv_close(cd);
/* build EBCDIC -> ASCII conversion table */
if ((cd = iconv_open(mytermcp.__tccp_fromname,
mytermcp.__tccp_toname)) ==
(iconv_t) (-1)) {
fprintf(stderr,"Cannot open converter from %s to %s\n",
mytermcp.__tccp_toname,mytermcp.__tccp_fromname);
exit(1);
}
inleft = 256;
outleft = 256;
intabptr = intab;
outtabptr = etoa;
rv = iconv(cd,&intabptr, &inleft, &outtabptr, &outleft);
if (rv == -1) {
fprintf(stderr,"Error in building EBCDIC to ASCII table\n");
exit(1);
}
iconv_close(cd);
/*
* Change the data conversion to use IBM-850 as the ASCII source
*/
if (__tcsettables(cterm_fd, sizeof(mytermcp), &mytermcp,
atoe,etoa) == -1) {
perror("__tcsettables() error");
exit(1);
} else {
printf("Data conversion now using ASCII IBM-850\n");
} /* endif */
} /* endif */
close(cterm_fd);
} /* main */
Data conversion now using ASCII IBM-850.