iucvconn - start terminal connection

Edit online

Runs on the terminal server to access a terminal device on a target system. This command is used by ts-shell and by the iucvconn_on_login script.

The iucvconn command is not used directly by ts-shell and by the iucvconn_on_login users.

Format

Figure 1. iucvconn syntax

where:

-e or --escape-char <escape_char>

sets an escape character for the terminal session. You need an escape character to access special iucvconn functions. The default escape character is the underscore (_) character. If <escape_char> is set to none, escaping is not possible. The escape character can be the closing bracket (]), the caret (^), the underscore (_), or any alphabetic character except C, D, Q, S, and Z. The escape character is not case-sensitive.

To call a special function press <escape_char> while you hold down Ctrl, then press the key for the function:

Table 1. Special functions that can be accessed through the escape character
Function character	Function
d	Close the terminal session.
period (.)	Close the terminal session (same as d).
r	Force resizing of the connected terminal.

-s or --sessionlog <log_file>

creates a transcript of the terminal session and writes session data to three different files.

<log_file>: contains the raw terminal data stream.
<log_file>.timing: contains timing data that can be used for replaying the raw terminal data stream with realistic output delays.
<log_file>.info: contains more terminal session information.

If any of these files exist, the iucvconn program exits with an error. To proceed either delete the files or choose another file name for <log_file>.

<vm_guest>

specifies the z/VM® user ID where the target Linux™ instance runs.

<terminal_id>

identifies a running iucvtty instance, or an HVC terminal device. The <terminal_id> is like a port number in TCP/IP communications. <terminal_id> is case-sensitive and consists of up to eight alphanumeric characters.

The terminal ID for an iucvtty instance is set in the start command for the instance.

For HVC terminal devices, the terminal IDs are lnxhvc<n>, where <n> is an integer in the range 0 - 7. If you do not need a specific HVC terminal device or if you are not sure which device is free, you can omit the trailing integer.

As of kernel 3.14, you can specify the generic terminal ID lnxhvc to automatically assign the next free terminal device.

-v or --version

prints the version number of the iucvconn program and exits.

-h or --help

prints a short help text and exits. For more detail, see the iucvconn man page.

Examples

To access the lxterm1 terminal on the Linux instance in z/VM guest virtual machine LXGUEST1:
```
$ iucvconn lxguest1 lxterm1
```
To access the lxterm1 terminal on the Linux instance in z/VM guest virtual machine LXGUEST1 and setting the escape character to X:
```
$ iucvconn -e x lxguest1 lxterm1
```
To access the first z/VM IUCV HVC terminal device on the Linux instance in z/VM guest virtual machine LXGUEST2:
```
$ iucvconn lxguest2 lnxhvc0
```
To access any free z/VM IUCV HVC terminal device on the Linux instance in z/VM guest virtual machine LXGUEST2:
```
$ iucvconn lxguest2 lnxhvc
```
To access the first z/VM IUCV HVC terminal device on the Linux instance in z/VM guest virtual machine LINUX99 and create a set of session transcript files ~/transcripts/linux99, ~/transcripts/linux99.timing, and ~/transcripts/linux99.info:
```
$ iucvconn -s ~/transcripts/linux99 linux99 lnxhvc0
```