QP2SHELL() and QP2SHELL2()--Run an IBM PASE for i Program

 #include <qp2shell.h>

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


 #include <qp2shell2.h>

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

Programs QP2SHELL and QP2SHELL2 run an IBM^® i Portable Application Solutions Environment (IBM PASE for i) program in the job where the API is called. They load the IBM PASE for i 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 IBM PASE for i 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 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.

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 IBM PASE for i program as the program name. Standard IBM PASE for i 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 IBM PASE for i program as arguments. The system copies argument strings into IBM PASE for i 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 IBM PASE for i 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 IBM PASE for i Program for details about running an IBM PASE for i program.
   
   
2. Neither QP2SHELL nor QP2SHELL2 does the special setup for standard streams that most shells require for reliable operations (stdin, stdout, and stderr must be forkable file descriptors), so these APIs cannot be used without additional programming to run a shell or shell script. You can run a shell script without additional programming using either the QP2TERM API program or the QSH CL command. For example, this CL command runs a script using the the IBM PASE for i C Shell:
   

   QSH CMD('exec /QOpenSys/usr/bin/csh script_name')

   
   
   
3. 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 IBM PASE for i program. This is done to avoid unexpected behavior for the IBM PASE for i program if the job changed ILE pthread attributes before calling the API.
   
   
4. QP2SHELL, QP2SHELL2, and system processing for the IBM PASE for i 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 IBM PASE for i program exits, but if the IBM PASE for i 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 IBM PASE for i signal. The pending IBM PASE for i signal that may result is not delivered until control transfers to the IBM PASE for i 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 IBM PASE for i signal, and attempt to deliver pending signals immediately by using Qp2CallPase to call an IBM PASE for i function (in the same thread). A signal may remain pending if no thread running IBM PASE for i code has the signal unblocked.
   N	Do not map any ILE signals to IBM PASE for i. No ILE signal handlers are changed. IBM PASE for i runtime functions that rely on system-generated signals (such as asynchronous I/O use of SIGIO and SIGURG) may not work correctly.

   
   
   
5. 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 IBM PASE for i program is running.
   
   
6. QP2SHELL and QP2SHELL2 initialize IBM PASE for i environment variables with a modified copy of the entire ILE environment. An IBM PASE for i environment variable is initialized for every ILE environment variable, but the initial value of any IBM PASE for i 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 IBM PASE for i runtime and ILE runtime when they require different values for the same environment variable (for example, LANG).
   
   
7. For a login shell (only), QP2SHELL and QP2SHELL2 set ILE environment variable PASE_SHELL to the path name of the IBM PASE for i program.
   
   
8. 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 LOGNAME variable. If the job is not currently authorized to the LOGNAME user profile, the HOME environment variable is set to a null string.
   LOGNAME	If LOGNAME 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 IBM PASE for i PATH environment variable.
   PASE_LANG and QIBM_PASE_CCSID	Initial value for the IBM PASE for i LANG environment variable and what coded character set identifier (CCSID) the IBM i 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 IBM PASE for i LANG environment variable controls the default locale for an IBM PASE for i program. See IBM PASE for i Locales to determine what locales are supported by IBM PASE for i.
   PASE_LOCPATH	(Default: "/usr/lib/nls/msg/%L/%N:/usr/lib/nls/msg/%L/%N.cat") Initial value for the IBM PASE for i LOCPATH environment variable.
   PASE_LC__FASTMSG	(Default: "true") Initial value for the IBM i PASE LC__FASTMSG environment variable.
   PASE_TZ	(Default: based on the IBM i job TIMZON attribute) Initial value for the IBM PASE for i TZ environment variable. If no timezone information is provided in environment variable TZ, the IBM PASE for i 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.
   	IBM PASE for i programs assume the ability to open 65 534 files and the system requires an open file for each IBM PASE for i executable it loads, so the default of 66 000 files accomodates a maximally large IBM PASE for i program with a fairly large number of loaded executables.

Related Information

• Qp2CallPase()--Call an IBM PASE for i Procedure
  
  
• Qp2RunPase()--Run an IBM PASE for i Program
  
  
• Qp2SignalPase()--Post an IBM PASE for i Signal
  
  
• QP2TERM()--Run an IBM PASE for i Terminal Session

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