Qp0zControlTerminal()--Control a Generic Terminal

Syntax

 #include <qp0ztrml.h>

 int Qp0zControlTerminal( unsigned char action, int value );

  Service Program Name: QP0ZTRMLC

  Default Public Authority: *USE

  Threadsafe: Yes

The Qp0zControlTerminal() function allows a program to control the terminal window to which it is connected. A program can perform the same actions on the terminal window as an interactive user of the terminal window. See Generic Terminal Concepts for details about using a terminal.

Qp0zControlTerminal() supports the following actions:

QP0Z_TERMINAL_BOTTOM (0xB6): Display bottom of output area. The bottom of the output area is displayed.
QP0Z_TERMINAL_CLCMDLINE (0xB9): Display CL command line. A pop-up window with a CL command line is displayed. The user can run a CL command without exiting the terminal window.
QP0Z_TERMINAL_CLEAR (0xB1): Clear output area. The contents of the output area and the command retrieval buffer are cleared.
QP0Z_TERMINAL_EXIT (0x33): Exit terminal window. The terminal window is ended and Qp0zRunTerminal() returns 1 (or QP0Z_TERMINAL_F3).
QP0Z_TERMINAL_LEFT (0xB7): Shift output area left. The output area is shifted to the left by the number of columns specified by value. If value is zero, the output area is shifted left by the number columns currently in the output area.
QP0Z_TERMINAL_PAGEDOWN (0x38): Page down output area. The output area is moved down by the number of rows specified by value. If value is zero, the output area is moved down by the number rows currently in the output area (one page).
QP0Z_TERMINAL_PAGEUP (0x37): Page up output area. The output area is moved up by the number of rows specified by value. If value is zero, the output area is moved up by the number rows currently in the output area (one page).
QP0Z_TERMINAL_PRINT (0x36): Print output area. The contents of the output area are printed to a QPRINT spool file.
QP0Z_TERMINAL_REFRESH (0x35): Refresh output area. The contents of the output area are refreshed with any output that is available.
QP0Z_TERMINAL_RETRIEVE (0x39): Retrieve previous command. The last command entered by the user is retrieved and displayed on the input line.
QP0Z_TERMINAL_RETURN (0x3C): Return from terminal window. The terminal window is ended and Qp0zRunTerminal() returns 0 (or QP0Z_TERMINAL_F12).
QP0Z_TERMINAL_RIGHT (0xB8): Shift output area right. The output area is shifted to the right by the number of columns specified by value. If value is zero, the output area is shifted right by the number columns currently in the output area.
QP0Z_TERMINAL_TOP (0xB5): Display top of output area. The top of the output area is displayed.

Parameters

action: (Input)

Action to perform on the terminal window. The valid values are listed above.
value: (Input)

Value associated with action. For the QP0Z_TERMINAL_LEFT and QP0Z_TERMINAL_RIGHT actions, the value is the number of columns to shift or zero for the default number of columns. For the QP0Z_TERMINAL_PAGEDOWN and QP0Z_TERMINAL_PAGEUP actions, the value is the number of rows to page up or down or zero for the default number of rows. For all other actions, this parameter must be zero.

Authorities and Locks

None.

Return Value

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

Error Conditions

If Qp0zControlTerminal() 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.

[EBADF]

Descriptor not valid.

A file descriptor argument was out of range, referred to a file that was not open, or a read or write request was made to a file that is not open for that operation.

[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.

Correct the argument in error and try your request again.

[EIO]

Input/output error.

A physical I/O error occurred.

See the previous message in the job log. Correct any errors indicated there and try your operation again.

[ENOTTY]

Inappropriate I/O control operation.

[EUNKNOWN]

Unknown system state.

The operation failed due to an unknown system state. See any messages in the job log and correct any errors that may be indicated and then retry the operation.

Usage Notes

Before calling Qp0zControlTerminal(), a program should check to see if descriptor 0 is connected to a terminal by calling Qp0zIsATerminal().
There is no way for the Generic Terminal to prevent multiple programs calling Qp0zControlTerminal() to control the terminal window. A program must provide appropriate synchronization between calls to Qp0zControlTerminal() to avoid confusing the user of the terminal.

Related Information

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

API introduced: V5R1

Top | UNIX-Type APIs | APIs by category