QP2SHELL() and QP2SHELL2()--Run an i5/OS PASE Shell Program

 #include <qp2shell.h>

 void QP2SHELL(const char    *pathName,  
               ...);


 #include <qp2shell2.h>

 void QP2SHELL2(const char   *pathName,  
                ...);

Programs QP2SHELL and QP2SHELL2 run an i5/OS Portable Application Solutions Environment (i5/OS PASE) program in the job where the API is called. They load the i5/OS PASE program and any necessary shared libraries and then transfer control to the program. QP2SHELL runs in a new ILE activation group, while QP2SHELL2 runs in the caller's activation group. Control returns to the caller when the i5/OS PASE program either 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.

If the base name part of the pathName value (excluding any prefix path qualifier) begins with a hyphen (-), QP2SHELL and QP2SHELL2 strip the hyphen when locating the bytestream file, but pass the full string (with the hyphen) to the i5/OS PASE program as the program name. Standard i5/OS PASE shell programs (including sh and ksh) run as login shells when called with a hyphen as the first character of the program name. Login shells look for a profile file and run it automatically when the shell starts.

argument strings

(Input) Optional pointers to null-terminated character strings that are passed to the i5/OS PASE program as arguments. The system copies argument strings into i5/OS PASE memory and converts them from the job default CCSID to the CCSID specified by ILE environment variable QIBM_PASE_CCSID.

Note: When calling QP2SHELL or QP2SHELL2 from CL, be sure to quote any argument string that could be interpreted as a numeric value. CL converts unquoted numeric arguments to decimal or floating-point format, which does not match the assumption made by these APIs and i5/OS PASE programs that all arguments are null-terminated character strings.

Authorities

Return Value

QP2SHELL and QP2SHELL2 return no function result. Escape messages are sent to report errors.

Error Messages

Some of the more common error messages sent by QP2SHELL and QP2SHELL2 are:

Usage Notes

1. QP2SHELL and QP2SHELL2 provide callable program interfaces to ILE procedure Qp2RunPase. See Qp2RunPase()--Run an i5/OS PASE Program for details about running an i5/OS PASE program.
   
   
2. QP2SHELL and QP2SHELL2 set the ILE pthread cancel state and cancel type to default values (PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED) before running the i5/OS PASE program. This is done to avoid unexpected behavior for the i5/OS PASE program if the job changed ILE pthread attributes before calling the API.
   
   
3. QP2SHELL, QP2SHELL2, and system processing for the i5/OS PASE fork function normally set up handlers for most ILE signals (replacing any prior handlers). QP2SHELL always restores original ILE signal handlers before returning to the caller. QP2SHELL2 restores original ILE signal handlers before returning if the i5/OS PASE program exits, but if the i5/OS PASE program returns without exiting, original ILE signal handlers are not restored until the system destroys the activation group that called QP2SHELL2.

   You can control how these interfaces handle signals by setting ILE environment variable QIBM_PASE_MAP_SIGNALS to one of these values:

   Y	Call Qp2SignalPase for any ILE signal (other than SIGCHLD) that corresponds to an i5/OS PASE signal. The pending i5/OS PASE signal that may result is not delivered until control transfers to the i5/OS PASE program in some thread that has not blocked the signal. This is the default behavior if QIBM_PASE_MAP_SIGNALS is not set.
   I	Call Qp2SignalPase for any ILE signal (other than SIGCHLD) that corresponds to an i5/OS PASE signal, and attempt to deliver pending signals immediately by using Qp2CallPase to call an i5/OS PASE function (in the same thread). A signal may remain pending if no thread running i5/OS PASE code has the signal unblocked.
   N	Do not map any ILE signals to i5/OS PASE. No ILE signal handlers are changed. i5/OS PASE runtime functions that rely on system-generated signals (such as asynchronous I/O use of SIGIO and SIGURG) may not work correctly.

   
   
   
4. To avoid unpredictable results, do not not change ILE environment variables QIBM_USE_DESCRIPTOR_STDIO or QIBM_PASE_DESCRIPTOR_STDIO in a job in which an i5/OS PASE program is running.
   
   
5. QP2SHELL and QP2SHELL2 initialize i5/OS PASE environment variables with a modified copy of the entire ILE environment. An i5/OS PASE environment variable is initialized for every ILE environment variable, but the initial value of any i5/OS PASE variable (except those whose name begins with "PASE_") can be overridden by the value of an ILE environment variable with a name that concatenates the prefix PASE_ with the original variable name. This processing avoids some interference between i5/OS PASE runtime and ILE runtime when they require different values for the same environment variable (for example, LANG).
   
   
6. For a login shell (only), QP2SHELL and QP2SHELL2 set ILE environment variable PASE_SHELL to the path name of the i5/OS PASE shell program.
   
   
7. QP2SHELL and QP2SHELL2 initialize any of the following ILE environment variables that are not already set, with default values as shown:
   
   

   HOME	If HOME is not already set, QP2SHELL and QP2SHELL2 set it to the home directory path specified in the user profile identified by the LOGIN variable. If the job is not currently authorized to the LOGIN user profile, the HOME environment variable is set to a null string.
   LOGIN	If LOGIN is not already set, QP2SHELL and QP2SHELL set it to the middle qualifier of the job name. For an interactive job, this is the name of the user who did a signon to start the job.
   PASE_PATH	(Default: "/QOpenSys/usr/bin:/usr/ccs/bin:/QOpenSys/usr/bin/X11:/usr/sbin:.:/usr/bin") Initial value for the i5/OS PASE PATH environment variable.
   PASE_LANG and QIBM_PASE_CCSID	Initial value for the i5/OS PASE LANG environment variable and what coded character set identifier (CCSID) the i5/OS PASE program will use. QP2SHELL and QP2SHELL2 set both these ILE environment variables if either or both is absent. The default values are function of the current LANGID and CNTRYID attributes of the job, but the system will use PASE_LANG=POSIX and QIBM_PASE_CCSID=819 if it does not recognize the LANGID and CNTRYID pair. The i5/OS PASE LANG environment variable controls the default locale for an i5/OS PASE program. See i5/OS PASE Locales to determine what locales are supported by i5/OS PASE.
   PASE_LOCPATH	(Default: "/usr/lib/nls/msg/%L/%N:/usr/lib/nls/msg/%L/%N.cat") Initial value for the i5/OS PASE LOCPATH environment variable.
   PASE_LC__FASTMSG	(Default: "true") Initial value for the i5/OS PASE LC__FASTMSG environment variable.
   PASE_TZ	(Default: based on the i5/OS job TIMZON attribute) Initial value for the i5/OS PASE TZ environment variable. If no timezone information is provided in environment variable TZ, the i5/OS PASE program sees UTC (Universal Standard Time) as local time. You can set ILE environment variable PASE_TZ at the system level to provide a default timezone other than the one determined from the job TIMZON attribute. For example, this CL command sets the default timezone to US Central time: ADDENVVAR ENVVAR(PASE_TZ) VALUE('CST6CDT') LEVEL(*SYS)
   QIBM_IFS_OPEN_MAX	(Default: "66000") Maximum number of Integrated File System open file descriptors desired in the job. QP2SHELL and QP2SHELL call the DosSetRelMaxFH API to set the maximum number of file descriptors to the value in this ILE environment variable, and updates the environment variable to reflect the actual limit (in case the requested limit is not currently allowed). Any change to the maximum number of file descriptors persists after the API returns.
   	i5/OS PASE programs assume the ability to open 65 534 files and the system requires an open file for each i5/OS PASE executable it loads, so the default of 66 000 files accomodates a maximally large i5/OS PASE program with a fairly large number of loaded executables.

Related Information

• Qp2CallPase()--Call an i5/OS PASE Procedure
  
  
• Qp2RunPase()--Run an i5/OS PASE Program
  
  
• Qp2SignalPase()--Post an i5/OS PASE Signal
  
  
• QP2TERM()--Run an i5/OS PASE Terminal Session