Generic Terminal APIs
The Generic Terminal APIs are:
- Qp0zControlTerminal() (Control a Generic Terminal) allows a program to control the terminal window to which it is connected.
- Qp0zEndTerminal() (End a Generic Terminal) ends the terminal session specified by handle.
- Qp0zGetTerminalPid() (Get Process ID for a Generic Terminal) returns the process ID of the interpreter process for the terminal specified by handle.
- Qp0zIsATerminal() (Determine Whether Descriptor Is Connected to a Generic Terminal) determines if the specified descriptor is connected to a terminal.
- Qp0zRunTerminal() (Run a Generic Terminal) runs the terminal specified by handle.
- Qp0zSetTerminalMode() (Set Modes for a Generic Terminal) allows a program to control the input mode and wrap mode of the terminal window to which it is connected.
- Qp0zStartTerminal() (Start a Generic Terminal) starts a new terminal.
Generic terminal concepts
The Generic Terminal provides an environment for running programs that use descriptors for reading input and writing output. Typically the programs are C, C++, or Java™ programs that read input from standard input, write regular output to standard output, and write error output to standard error.
A terminal is started, run, and ended from an interactive job. When a terminal is started by Qp0zStartTerminal(), an interpreter process is started in batch with descriptors 0, 1, and 2 connected to pipes in the interactive job. A user specified program runs in the interpreter process. After calling Qp0zRunTerminal(), an interactive user can send input to the program and see the output written by the program. The resources used by the terminal are cleaned up by calling Qp0zEndTerminal(). It closes the pipes and ends the interpreter process.
Terminal window
After calling Qp0zRunTerminal(), the terminal window is displayed. The interactive user enters input that is sent to the interpreter process and sees output that comes from the interpreter process. The terminal window has these parts:
- A title line identifies the terminal window. The title is set in the
Qp0z_Terminal_Attr_T parameter of
Qp0zStartTerminal().
- An output area that contains an echo of the commands that were entered and
any output from the interpreter process. When a program in the interpreter
process writes to descriptors 1 or 2, the output is displayed in the output
area.
- An input line for entering commands. The input is written to descriptor 0
in the interpreter process.
- A command key description. There are two lines of command key descriptions
that are set in the Qp0z_Terminal_Attr_T parameter of
Qp0zStartTerminal().
- A message line where messages to the user are displayed.
The terminal window supports these command keys:
| Command Key | Description |
|---|---|
| F3 (Exit) | Returns to the caller of Qp0zRunTerminal() with a return value of 1 (or QP0Z_TERMINAL_F3). |
| F5 (Refresh) | Refreshes the output area. |
| F6 (Print) | Prints the output area to a QPRINT spool file. |
| F7 (Page up) | Page up output area. If a number is on the command line, the output area is rolled up by that number of lines. |
| F8 (Page down) | Page down output area. If a number is on the command line, the output area is rolled down by that number of lines. |
| F9 (Retrieve) | Retrieve a previous command. If the key is pressed multiple times, it retrieves previous commands from a buffer. For example, to retrieve the second to last command, press the key two times. A specific command can be selected by placing the cursor on that command and pressing the key. When the interactive job is running in a double-byte CCSID, this key is not available. |
| F11 (Toggle line wrap) | Toggles the line wrap/truncate mode in the output area. In line wrap mode, lines longer than the width of the terminal window are wrapped to the next line. In truncate mode, the portion of a line beyond the width of the terminal window is not shown. |
| F12 (Return) | Returns to the caller of Qp0zRunTerminal() with a return value of 0 (or QP0Z_TERMINAL_F12). |
| F13 (Clear) | Clears the output area. |
| F14 (Adjust command line length) | Adjust the command line length to four lines. If a number is on the command line, the command line length is adjusted to that number of lines. |
| F17 (Top) | Displays top of output area. |
| F18 (Bottom) | Displays bottom of output area. |
| F19 (Left) | Shifts the output area to the left. If a number is on the command line, the output area is shifted by that number of columns. |
| F20 (Right) | Shifts the output area to the right. If a number is on the command line, the output area is shifted by that number of columns. |
| F21 (CL command line) | Displays a command entry window where the user can enter CL commands. |
Programs running in the interpreter process
The program can use descriptor 0 (or standard input) to read input, descriptor 1 (or standard output) to write regular output, and descriptor 2 (or standard error) to write error output. The program can use the following functions to work with the terminal to which it is connected.
- Use Qp0zIsATerminal() to see if a descriptor is
connected to a terminal.
- Use Qp0zControlTerminal() to control the
terminal window. For example, page up or page down in the terminal window.
- Use Qp0zSetTerminalMode() to set terminal modes. For example, switch to hidden input mode to read a password.>
The program also needs to decide how to handle the following signals:
- The terminal sends signal SIGINT when the interactive user enters SysReq 2
to interrupt the current request.
- The terminal sends signal SIGHUP when the terminal is ended.