Qp2RunPase()--Run an IBM PASE for i Program

Syntax

 #include <qp2user.h>

 int Qp2RunPase(const char         *pathName,  
                const char         *symbolName,
                const void         *symbolData,
                unsigned int       symbolDataLen,  
                int                ccsid,
                const char  *const *argv,
                const char  *const *envp);

  Service Program Name: QP2USER

  Default Public Authority: *USE

  Threadsafe: No

The Qp2RunPase() function runs an IBM^® i Portable Application Solutions Environment (IBM PASE for i) program in the job where the API is called. It loads the IBM PASE for i program and any necessary shared libraries and then transfers control to the program. Control returns to the caller when the IBM PASE for i program exits, terminates due to a signal, or returns without exiting.

Parameters

pathName: (Input) Pointer to a null-terminated character string that identifies the stream file in the Integrated File System that contains the IBM PASE for i program to run. The pathName string may include an absolute or relative path qualifier in addition to the stream file name. Relative path names are resolved using the current working directory.
symbolName: (Input) This argument must be a null pointer.
symbolData: (Input) This argument is ignored.
symbolDataLen: (Input) This argument is ignored.
ccsid: (Input) The coded character set identifier (CCSID) initially used by the IBM PASE for i program. ccsid must specify a single-byte encoding (normally an ASCII CCSID) that IBM i can convert to and from the job default CCSID, or a value of 1208 to indicate that the IBM PASE for i program uses UTF-8 encoding.
The system uses ccsid to set the CCSID of any bytestream file created by the IBM PASE for i program, and also to control character encoding conversions done for IBM PASE for i runtime interfaces that use IBM i services.
argv: (Input) Pointer to an array of pointers to null-terminated character strings that are passed as arguments to the IBM PASE for i program. The last element in the array must be a null pointer. An error is reported if the argv parameter pointer is null.
The system copies argument strings into IBM PASE for i memory and converts them from the job default CCSID to the CCSID specified by the ccsid parameter. By convention, the first argument string passed to an IBM PASE for i program should be the same as the pathName string.
envp: (Input) Pointer to an array of pointers to null-terminated character strings that are passed as environment variables to the IBM PASE for i program. The last element in the array must be a null pointer. envp can be a null pointer if no environment variables need to be initialized for the IBM PASE for i program.
The system copies environment variable strings into IBM PASE for i memory and converts them from the job default CCSID to the CCSID specified by the ccsid parameter. By convension, environment variable strings take the form "NAME=value".

Authorities

Object Referred to

Authority
Required

Each directory in the path to the IBM PASE for i program and shared libraries

IBM PASE for i program (not a shell script) in a local file system

IBM PASE for i program in a remote file system or shell script

*RX

IBM PASE for i shared library

Return Value

The function result may be one of these special values:

QP2RUNPASE_ERROR (-1)

An internal error occurred during Qp2RunPase processing.

QP2RUNPASE_RETURN_NOEXIT (-2)

The IBM PASE for i program returned without exiting (by calling the IBM PASE for i _RETURN function).

If the result is not one of the special values above, it is a value that contains status information about how the IBM PASE for i program ended, in the same format as the stat_val parameter for the ILE waitpid function. You can use these macros in file <sys/wait.h> to interpret such a result:

WIFEXITED(stat_val)

Evaluates to a nonzero value if IBM PASE for i program ended normally.

WEXITSTATUS(stat_val)

If the value of the WIFEXITED(stat_val) is nonzero, evaluates to the low-order 8 bits of the value the IBM PASE for i program specified as the argument to exit or the function result returned by main.

WIFSIGNALED(stat_val)

Evaluates to a nonzero value if IBM PASE for i program ended because of the receipt of a terminating signal that was not caught by the process.

WTERMSIG(stat_val)

If the value of WIFSIGNALED(stat_val) is nonzero, evaluates to the number of the IBM PASE for i signal that caused the program to end. IBM PASE for i programs use the same signal numbers as AIX^® (which differ from ILE signal numbers).

Error Messages

Message ID

Error Message Text

CPF9872 E

Program or service program &1 in library &2 ended. Reason code &3.

CPFB9C0 E

Error loading program &1. See previous messages.

CPFB9C1 E

System support for IBM i Portable Application Solutions Environment not available.

CPFB9C2 E

Hardware support for IBM i Portable Application Solutions Environment not available.

CPFB9C3 E

IBM PASE for i CCSID and job default CCSID are incompatible.

CPFB9C7 E

IBM PASE for i already running in this job.

CPFB9C8 E

File descriptors 0, 1, and 2 must be open to run the IBM PASE for i program.

CPFB9CB E

Qp2RunPase second argument must be a null pointer.

Usage Notes

Qp2RunPase works like the AIX execve function, including the ability to run shell scripts and the rules for resolving shared libraries (which may include using IBM PASE for i environment variable LIBPATH).
If an absolute path (starting with "/") is specified for the pathName string or in the first line of a shell script identified by pathName and that path cannot be opened or is not a regular bytestream file, the system generally searches the /QOpenSys file system for the file. See environment variable PASE_EXEC_QOPENSYS in IBM PASE for i Environment Variables for more information.
Qp2RunPase cannot run an IBM PASE for i program or shared library stored in a file system that is not threadsafe in a job that is multithread capable. Any job started by the IBM PASE for i fork function is multi-thread capable.

You can set these ILE environment variables before calling Qp2RunPase to control the IBM PASE for i operation:

QIBM_USE_DESCRIPTOR_STDIO

When this ILE environment variable is set to Y or I, both IBM PASE for i runtime and ILE C runtime use Integrated File System file descriptors 0, 1, and 2 for stdin, stdout, and stderr. Otherwise, IBM PASE for i file descriptors 0, 1, and 2 are mapped to ILE C runtime files stdin, stdout, and stderr (which may not use any Integrated File System file descriptors).

IBM PASE for i and ILE generally use different descriptor numbers for the same open file, but when QIBM_USE_DESCRIPTOR_STDIO is set to Y or I, any operation against IBM PASE for i file descriptors 0, 1, or 2 is also done for the same Integrated File System file descriptor number so IBM PASE for i and ILE C use the same files for stdin, stdout, and stderr.

QIBM_PASE_DESCRIPTOR_STDIO

This ILE environment variable controls ASCII/EBCDIC conversion for data read or written through IBM PASE for i files stdin, stdout, and stderr to Integrated File System file descriptors 0, 1, and 2. ASCII/EBCDIC conversion is always done (and this variable is ignored) unless QIBM_USE_DESCRIPTOR_STDIO is set to either Y or I. If QIBM_PASE_DESCRIPTOR_STDIO is set to B, the PASE program processes binary data (without ASCII/EBCDIC conversion). Otherwise, ASCII/EBCDIC conversion is done for any data read from or written to IBM PASE for i file descriptors 0, 1, or 2.

QIBM_PASE_FLUSH_STDIO

This ILE environment variable controls whether IBM PASE for i runtime flushes every write to a standard output stream attached to a Data Management file (such as a spooled printer file) or to the Dynamic Screen Manager in an interactive job. QIBM_PASE_FLUSH_STDIO must be set before starting IBM PASE for i, and only applies when IBM PASE for i is NOT using IFS descriptors for standard I/O (QIBM_USE_DESCRIPTOR_STDIO is not set). It is usually only needed for interactive programs that require immediate display of output that does not end with newline. These values are supported:

Y: flush both stdout and stderr
1: flush only stdout (IBM PASE for i descriptor 1)
2: flush only stderr (IBM PASE for i descriptor 2)

QIBM_PASE_USE_PRESTART_JOBS

When this ILE environment variable is set to Y, IBM PASE for i runtime uses prestarted jobs for child processes created by fork and for any job started by the systemCL IBM PASE for i runtime function (to run a CL command). You should add prestarted job entries (ADDPJE command) for programs QP0ZSPWT (used by fork) and QP0ZSPWP (used by systemCL) to any subsystem description that will run jobs that use this support.

IBM PASE for i environment variables are independent of ILE environment variables. See IBM PASE for i Environment Variables for more information, including IBM PASE for i environment variables you can set to control runtime behaviors that differ from AIX.
The ccsid parameter provides the initial IBM PASE for i CCSID value, but the IBM PASE for i program can use the _SETCCSID function to change the IBM PASE for i CCSID or to rebind to a change in the job default CCSID. The IBM PASE for i CCSID should generally be the CCSID equivalent of the code set for the current locale. See IBM PASE for i Locales to determine what locales are supported by IBM PASE for i.
You may want to increase the number of file descriptors in the job by calling DosSetRelMaxFH before you call Qp2RunPase. By default, IBM i jobs support only 200 open file descriptors, while IBM PASE for i programs generally expect to be able to open 32 767 file descriptors, and the system requires file descriptors to open bytestream files that contain the IBM PASE for i program and any shared libraries it uses.
You may want to establish Qp2SignalPase as the handler for any ILE signal that needs to be visible to the IBM PASE for i program. For example, system support for Sockets (used by IBM PASE for i runtime) only sends SIGIO and SIGURG as ILE signals, so ILE signal handling must be set up before calling an IBM PASE for i program that relies on SIGIO or SIGURG as IBM PASE for i signals. IBM PASE for i runtime automatically establishes Qp2SignalPase as the handler for every ILE signal in a fork child process.
You may want to call ILE interfaces pthread_setcancelstate and pthread_setcanceltype to set pthread cancel state and cancel type before calling Qp2RunPase in a process that did prior pthread work. IBM PASE for i pthreads use ILE pthreads and Qp2RunPase assumes that ILE pthread cancel state and cancel type are set to defaults (PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED). The state of these attributes when a program ends is whatever value was last set by either ILE or IBM PASE for i code.
Time-of-day information in an IBM PASE for i program depends on the value of IBM PASE for i environment variable TZ, which provides information about timezone name and offset from UTC (Universal Coorodinated Time). For example, the correct TZ setting for Central Time in the USA is TZ=CST6CDT. See AIX documentation for more information about environment varble TZ.
Any credentials changes (user, group, or group list changes) made by an IBM PASE for i program are generally persistent in the job. The job (thread) credentials before and after a call to Qp2RunPase may not be the same if the IBM PASE for i program calls any of the setuid or setgid family of interfaces. However, the system saves credentials before running any IBM PASE for i program with the S_ISUID or S_ISGID attribute, and automatically restores the saved credentials before returning to the caller of Qp2RunPase.
Character conversions controlled by the ccsid parameter only handle the single-byte component of an EBCDIC-mixed CCSID (for the job default CCSID). This restricts the IBM PASE for i program name specified by the pathName parameter, argument strings passed through the argv parameter, and environment variables passed through the envp parameter to single-byte characters.
If an IBM PASE for i program needs to use DBCS characters for IBM PASE for i runtime functions such as file system interfaces, it must run with the IBM PASE for i CCSID (ccsid parameter) set to 1208 because IBM PASE for i runtime provides complete support for DBCS characters using UTF-8 encoding only.
Older versions of Qp2RunPase used symbolName, symbolData, and symbolDataLen to pass inputs other than character string arguments and environment variables to the IBM PASE for i program. An IBM PASE for i program can retrieve any inputs that cannot be expressed as null-terminated strings (such as tagged pointers) by calling ILE or OPM code (using _ILECALL or _PGMCALL) with by-address arguments.

Related Information

The <sys/wait.h> file (see Header Files for UNIX^®-Type Functions)
DosSetRelMaxFH()--Change Maximum Number of File Descriptors
pthread_setcancelstate()--Set Cancel State
pthread_setcanceltype()--Set Cancel Type
QP2SHELL() and QP2SHELL2()--Run an IBM PASE for i Program
QP2TERM()--Run an IBM PASE for i Terminal Session

API introduced: V4R5

[ Back to top | IBM PASE for i APIs | APIs by category ]