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


  Syntax 
 #include <qp2shell.h>

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


 #include <qp2shell2.h>

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

  Default Public Authority: *USE

  Threadsafe: No

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:



  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:


Related Information


API introduced: V4R5

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