Qp0zStartTerminal()--Start a Generic Terminal

Syntax

 #include <qp0ztrml.h>

 int Qp0zStartTerminal( Qp0z_Terminal_T *handle,
                        char *args[],
                        char *envs[],
                        Qp0z_Terminal_Attr_T attr);

  Service Program Name: QP0ZTRML

  Default Public Authority: *USE

  Threadsafe: No

The Qp0zStartTerminal() function starts a new terminal by:

starting a new interpreter process running the program specified in args[0],
creating pipes connected to descriptors 0, 1, and 2 in the interpreter process, and
starting a terminal window.

The interpreter process is started with the environment variables specified in envs. Using attr, you can set attributes for the terminal, including the inheritance structure used by spawn() to start the interpreter process, the title line and command key descriptions in the terminal window, and the IBM^® i simple job name of the interpreter process. The program running in the interpreter process receives the arguments specified in args.

In the interpreter process, descriptors 0, 1, and 2 are connected to pipes in the process that started the terminal. When a command is entered in the terminal window, it is written to descriptor 0 in the interpreter process. When a program in the interpreter process writes to descriptors 1 or 2, the data is displayed in the terminal window.

After a new terminal is started, you must call Qp0zRunTerminal() to wait for the user to enter input at the command line, press a command key, or for output from the interpreter process to be displayed.

Parameters

*handle

(Output) A pointer to the area to store the terminal handle. When successful, Qp0zStartTerminal() returns a handle to the started terminal.

*args

(Input) A null-terminated array of pointers to the arguments passed to the interpreter program. The first element in the array is a pointer to the path name of the program to start in the interpreter process.

*envs

(Input) A null-terminated array of pointers to the environment variables inherited by the interpreter process. If this parameter is NULL, the environment variables currently defined when Qp0zStartTerminal() is called are inherited by the interpreter process.

attr

(Input) Attributes for the terminal session.

The members of the Qp0z_Terminal_Attr_T structure are as follows:

struct inherit Inherit

The inheritance structure used when calling spawn() to start the interpreter process. Using the inheritance structure you can control the attributes of the interpreter process.

int Buffer_Size

Size of buffer for reading data from interpreter process. If zero is specified, Qp0zStartTerminal() uses a default buffer size of 4096 bytes.

char DBCS_Capable

This field is no longer used.

char Return_Exit_Status

Return the exit status of the interpreter process from Qp0zEndTerminal(). You must specify an optional parameter when calling Qp0zEndTerminal() to receive the exit status.

char Send_End_Msg

Send message CPCA989 when the interpreter process ends during Qp0zRunTerminal(). The message is displayed on the message line of the terminal window to alert the user that the interpreter process has ended.

char Return_On_End

Return immediately from Qp0zRunTerminal() when the interpreter process ends. By default, Qp0zRunTerminal() waits for the user to press either the F3 or F12 command key before returning when the interpreter process ends.

char *Title

Pointer to null-terminated string with the title for the terminal window. If the string is too long to fit in the terminal window, it is truncated to the width of the window.

char *Cmd_Key_Line1

Pointer to null-terminated string with the first line of command key descriptions for the terminal window. If the string is too long to fit in the terminal window, it is truncated to the width of the window.

char *Cmd_Key_Line2

Pointer to null-terminated string with the second line of command key descriptions for the terminal window. If the string is too long to fit in the terminal window, it is truncated to the width of the window.

char Interpreter_Process_Name[10]

The 10 character IBM i simple job name to use for the interpreter process. If specified, this field must be uppercase, and contain only those characters allowed for an IBM i job name. However, a period (.) is not considered a valid character.

char reserved2[22]

Reserved field that must be set to zero.

Authorities

Authorization Required for Qp0zStartTerminal()

Object Referred to

Authority Required

errno

Each directory in the path name preceding the executable file that will run in the interpreter process

EACCES

Executable file that will run in the interpreter process

EACCES

If executable file that will run in the interpreter process is a shell script

*RX

EACCES

Return Value

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

Error Conditions

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

[E2BIG]

Argument list too long.

[EACCES]

Permission denied.

An attempt was made to access an object in a way forbidden by its object access permissions.

The thread does not have access to the specified file, directory, component, or path.

If you are accessing a remote file through the Network File System, update operations to file permissions at the server are not reflected at the client until updates to data that is stored locally by the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.) Access to a remote file may also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote systems.

[EBUSY]

Resource busy.

An attempt was made to use a system resource that is not available at this time. A terminal session is already active in the job and another one cannot be started.

[ECONVERT]

Conversion error.

One or more characters could not be converted from the source CCSID to the target CCSID.

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

[ELOOP]

A loop exists in the symbolic links.

This error is issued if the number of symbolic links encountered is more than POSIX_SYMLOOP (defined in the limits.h header file). Symbolic links are encountered during resolution of the directory or path name.

[EMFILE]

Too many open files for this process.

An attempt was made to open more files than allowed by the value of OPEN_MAX. The value of OPEN_MAX can be retrieved using the sysconf() function.

The process has more than OPEN_MAX descriptors already open (see the sysconf() function).

[ENAMETOOLONG]

A path name is too long.

A path name is longer than PATH_MAX characters or some component of the name is longer than NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, the length of the name string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and NAME_MAX values can be determined using the pathconf() function.

[ENFILE]

Too many open files in the system.

A system limit has been reached for the number of files that are allowed to be concurrently open in the system.

The entire system has too many other file descriptors already open.

[ENOENT]

No such path or directory.

The directory or a component of the path name specified does not exist.

A named file or directory does not exist or is an empty string.

[ENOMEM]

Storage allocation request failed.

A function needed to allocate storage, but no storage is available.

There is not enough memory to perform the requested function.

[ENOTDIR]

Not a directory.

A component of the specified path name existed, but it was not a directory when a directory was expected.

Some component of the path name is not a directory, or is an empty string.

[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

Only one terminal at a time can be active in an interactive job. If a terminal is currently active, Qp0zStartTerminal() returns EBUSY.
If the interpreter program is a C or C++ program, it must be compiled for Integrated File System I/O by specifying the SYSIFCOPT(*IFSIO) parameter on the command used to create the program.
If the interpreter program is a C or C++ program, the environment variable QIBM_USE_DESCRIPTOR_STDIO=Y must be set in the interpreter process to enable the program to use descriptors 0, 1, and 2 for standard input, standard output, and standard error.
The interpreter program can always read and write directly to descriptors 0, 1, and 2 regardless of the language it is compiled with.
It is the responsibility of the interpreter program to end and cleanup any open resources when the descriptors are closed by the terminal, it receives the SIGHUP signal, or it receives the SIGINT signal.

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
Qp0zRunTerminal()--Run a Generic Terminal
Qp0zSetTerminalMode()--Set Modes for a Generic Terminal
spawn()--Spawn Process

API introduced: V5R1

[ Back to top | UNIX-Type APIs | APIs by category ]