Qp0zRunTerminal()--Run a Generic Terminal

 #include <qp0ztrml.h>

 int Qp0zRunTerminal( Qp0z_Terminal_T handle );  

The Qp0zRunTerminal() function runs the terminal specified by handle. First, Qp0zRunTerminal() makes the terminal window the active window on the display. Then, Qp0zRunTerminal() waits for the user to enter input at the command line, press a command key, or for output to become available from the interpreter process. Qp0zRunTerminal() returns when either the user presses F3, the user presses F12, or the interpreter process ends.

When the user enters input at the terminal command line, Qp0zRunTerminal() writes the data to descriptor 0 in the interpreter process. The data is terminated with a new line (0x25) character.

When a program in the interpreter process writes to descriptor 1 or 2, Qp0zRunTerminal() displays the data in the output area of the terminal window.

When the user presses one of the following command keys, Qp0zRunTerminal() takes these actions:

F3 (Exit)

Returns to the caller 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 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.

When the user enters System Request 2, Qp0zRunTerminal() sends a SIGINT signal to the process group of the interpreter process.

Parameters

handle

(Input) Handle for terminal.

Authorities

None.

Return Value

0 (or QP0Z_TERMINAL_F12)

Qp0zRunTerminal() was successful and the user pressed F12 to return.

1 (or QP0Z_TERMINAL_F3)

Qp0zRunTerminal() was successful and the user pressed F3 to exit.

2 (or QP0Z_TERMINAL_ENDED)

Qp0zRunTerminal() was successful and the interpreter process ended.

value

Qp0zRunTerminal() was not successful. The value returned is an errno indicating the failure.

Error Conditions

If Qp0zRunTerminal() is not successful, the return value usually indicates one of the following errors. Under some conditions, the return value could indicate an error other than those listed here.

[EDESTROYED]

The mutex was destroyed.

A required object was destroyed.

[EFAULT]

The address used for an argument is not correct.

In attempting to use an argument in a call, the system detected an address that is not valid.

While attempting to access a parameter passed to this function, the system detected an address that is not valid.

[EINVAL]

The value specified for the argument is not correct.

A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.

An argument value is not valid, out of range, or NULL.

[EIO]

Input/output error.

A physical I/O error occurred.

A referenced object may be damaged.

[EUNKNOWN]

Unknown system state.

The operation failed because of an unknown system state. See any messages in the job log and correct any errors that are indicated, then retry the operation.

Usage Notes

1. The default action for the SIGINT signal is to end the request. The program running in the interpreter process can use a signal handler to catch the signal and perform any necessary cleanup. See Signals APIs for more information about signals.

Related Information

• The <qp0ztrml.h> file (see Header Files for UNIX-Type Functions)
  
  
• Qp0zControlTerminal()--Control a Generic Terminal
  
  
• Qp0zEndTerminal()--End a Generic Terminal
  
  
• Qp0zGetTerminalPid()--Get Process ID for a Generic Terminal
  
  
• Qp0zIsATerminal()--Determine Whether Descriptor Is Connected to a Generic Terminal
  
  
• Qp0zSetTerminalMode()--Set Modes for a Generic Terminal
  
  
• Qp0zStartTerminal()--Start a Generic Terminal
  
  
• Using the Generic Terminal APIs (see Examples)