#include <qp0ztrml.h>
int Qp0zStartTerminal( Qp0z_Terminal_T *handle,
char *args[],
char *envs[],
Qp0z_Terminal_Attr_T attr);
Service Program Name: QP0ZTRMLThe Qp0zStartTerminal() function starts a new terminal by:
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.
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. |
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 | *X | EACCES |
| Executable file that will run in the interpreter process | *X | EACCES |
| If executable file that will run in the interpreter process is a shell script | *RX | EACCES |
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.
Argument list too long.
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.
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.
Conversion error.
One or more characters could not be converted from the source CCSID to the target CCSID.
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.
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.
Input/output error.
A physical I/O error occurred.
A referenced object may be damaged.
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.
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).
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.
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.
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.
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.
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.
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.