Qp2RunPase()--Run an i5/OS PASE Program

 #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);

The Qp2RunPase() function runs an i5/OS Portable Application Solutions Environment (i5/OS PASE) program in the job where the API is called. It loads the i5/OS PASE program and any necessary shared libraries and then transfers control to the program. Control returns to the caller when the i5/OS PASE 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 i5/OS PASE 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 i5/OS PASE program. ccsid must specify a single-byte encoding (normally an ASCII CCSID) that i5/OS can convert to and from the job default CCSID, or a value of 1208 to indicate that the i5/OS PASE program uses UTF-8 encoding.

The system uses ccsid to set the CCSID of any bytestream file created by the i5/OS PASE program, and also to control character encoding conversions done for i5/OS PASE runtime interfaces that use i5/OS services.

argv

(Input) Pointer to an array of pointers to null-terminated character strings that are passed as arguments to the i5/OS PASE 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 i5/OS PASE 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 i5/OS PASE 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 i5/OS PASE 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 i5/OS PASE program.

The system copies environment variable strings into i5/OS PASE 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

Return Value

The function result may be one of these special values:

If the result is not one of the special values above, it is a value that contains status information about how the i5/OS PASE 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:

Error Messages

Usage Notes

1. 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 i5/OS PASE environment variable LIBPATH).
   
   
2. 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 i5/OS PASE Environment Variables for more information.
   
   
3. Qp2RunPase cannot run an i5/OS PASE 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 i5/OS PASE fork function is multi-thread capable.
   
   
4. You can set these ILE environment variables before calling Qp2RunPase to control the i5/OS PASE operation:
   
   

   QIBM_USE_DESCRIPTOR_STDIO	When this ILE environment variable is set to Y or I, both i5/OS PASE runtime and ILE C runtime use Integrated File System file descriptors 0, 1, and 2 for stdin, stdout, and stderr. Otherwise, i5/OS PASE 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). i5/OS PASE 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 i5/OS PASE file descriptors 0, 1, or 2 is also done for the same Integrated File System file descriptor number so i5/OS PASE 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 i5/OS PASE 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 i5/OS PASE file descriptors 0, 1, or 2.
   QIBM_PASE_FLUSH_STDIO	This ILE environment variable controls whether i5/OS PASE 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 i5/OS PASE, and only applies when i5/OS PASE 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 (i5/OS PASE descriptor 1) 2 flush only stderr (i5/OS PASE descriptor 2)
   QIBM_PASE_USE_PRESTART_JOBS	When this ILE environment variable is set to Y, i5/OS PASE runtime uses prestarted jobs for child processes created by fork and for any job started by the systemCL i5/OS PASE 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.

   
   
   
5. i5/OS PASE environment variables are independent of ILE environment variables. See i5/OS PASE Environment Variables for more information, including i5/OS PASE environment variables you can set to control runtime behaviors that differ from AIX.
   
   
6. The ccsid parameter provides the initial i5/OS PASE CCSID value, but the i5/OS PASE program can use the _SETCCSID function to change the i5/OS PASE CCSID or to rebind to a change in the job default CCSID. The i5/OS PASE CCSID should generally be the CCSID equivalent of the code set for the current locale. See i5/OS PASE Locales to determine what locales are supported by i5/OS PASE.
   
   
7. You may want to increase the number of file descriptors in the job by calling DosSetRelMaxFH before you call Qp2RunPase. By default, i5/OS jobs support only 200 open file descriptors, while i5/OS PASE 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 i5/OS PASE program and any shared libraries it uses.
   
   
8. You may want to establish Qp2SignalPase as the handler for any ILE signal that needs to be visible to the i5/OS PASE program. For example, system support for Sockets (used by i5/OS PASE runtime) only sends SIGIO and SIGURG as ILE signals, so ILE signal handling must be set up before calling an i5/OS PASE program that relies on SIGIO or SIGURG as i5/OS PASE signals. i5/OS PASE runtime automatically establishes Qp2SignalPase as the handler for every ILE signal in a fork child process.
   
   
9. 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. i5/OS PASE 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 i5/OS PASE code.
   
   
10. Time-of-day information in an i5/OS PASE program depends on the value of i5/OS PASE 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.
    
    
11. Any credentials changes (user, group, or group list changes) made by an i5/OS PASE 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 i5/OS PASE program calls any of the setuid or setgid family of interfaces. However, the system saves credentials before running any i5/OS PASE program with the S_ISUID or S_ISGID attribute, and automatically restores the saved credentials before returning to the caller of Qp2RunPase.
    
    
12. 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 i5/OS PASE 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.
    
    
13. If an i5/OS PASE program needs to use DBCS characters for i5/OS PASE runtime functions such as file system interfaces, it must run with the i5/OS PASE CCSID (ccsid parameter) set to 1208 because i5/OS PASE runtime provides complete support for DBCS characters using UTF-8 encoding only.
    
    
14. Older versions of Qp2RunPase used symbolName, symbolData, and symbolDataLen to pass inputs other than character string arguments and environment variables to the i5/OS PASE program. An i5/OS PASE 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()--Run an i5/OS PASE Shell Program
  
  
• QP2TERM()--Run an i5/OS PASE Terminal Session