PGM_$INVOKE                       Domain/OS                        PGM_$INVOKE


NAME
     pgm_$invoke - invoke a program

SYNOPSIS (C)
     #include <apollo/base.h>
     #include <apollo/pgm.h>

     void pgm_$invoke(
          char *path_name,
          short &path_length,
          short &argument_count,
          pgm_$arg_ptr *argument_vector,
          short &stream_count,
          ios_$id_t *stream_vector,
          pgm_$mode &invoke_mode,
          pgm_$proc *process_handle,
          status_$t *status)

SYNOPSIS (Pascal)
     %include '/sys/ins/base.ins.pas';
     %include '/sys/ins/pgm.ins.pas';

     procedure pgm_$invoke(
          in path_name: univ name_$pname_t;
          in path_length: integer;
          in argument_count: integer;
          in argument_vector: univ pgm_$argv;
          in stream_count: integer;
          in stream_vector: univ pgm_$connv;
          in invoke_mode: pgm_$mode;
          out process_handle: univ pgm_$proc;
          out status: status_$t);

SYNOPSIS (FORTRAN)
     %include '/sys/ins/base.ins.ftn'
     %include '/sys/ins/pgm.ins.ftn'

           integer*4 process_handle, status
           integer*2 path_length, argument_count, arg_len, stream_count
           integer*2 stream_vector(128), invoke_mode
           character path_name*1023, arg_chars*128

           integer*4 arg_ptr, argument_vector(128)
           pointer /arg_ptr/ arg_len, arg_chars

           call pgm_$invoke(path_name, path_length, argument_count,
          &                 argument_vector, stream_count,
          &                 stream_vector, invoke_mode,
          &                 process_handle, status)

DESCRIPTION
     Pgm_$invoke invokes the program at path_name and supplies a process han-
     dle for it in process_handle.  The behavior of an invoked program depends
     on the mode in which the program is invoked.

     path_name
          The absolute pathname of the program to invoke.

     path_length
          The number of bytes in path_name.

     argument_count
          The number of arguments in argument_vector.

     argument_vector
          An array of program arguments of type pgm_$arg.

     stream_count
          The number of stream IDs in stream_vector.

     stream_vector
          An array of stream IDs to pass to the invoked program.

     invoke_mode
          A small set specifying the mode in which to invoke the program.
          Choose a combination of the following values:

          pgm_$back_ground
               The invoked program executes independently of the invoking pro-
               cess, and there is no valid process handle for it.  Conse-
               quently, there is no mechanism by which the new process can
               communicate its exit status to the invoking process.  Use this
               mode when the exit status of the invoked process in not impor-
               tant.

          pgm_$extra_proc
               This mode forces the invoked program to run in a separate pro-
               cess.

          pgm_$obj_only
               In this mode, the invoke call will fail if the invoked program
               is not a pre-SR10 object; that is, an object of type obj.

          pgm_$new_session
               This mode makes the invoked program a process group leader (a
               session leader as defined by POSIX).  If file descriptor 0 of
               the new process is a tty and is not already a controlling ter-
               minal, then that tty will be the controlling terminal for the
               new process.

          pgm_$wait
               The invoking program is suspended while the invoked program
               executes.  The termination status of the invoked program is
               supplied in the completion status of pgm_$invoke when it
               returns.

          To invoke in default mode, specify 0 in C and FORTRAN, or [] in Pas-
          cal.  When a program is invoked in default mode, pgm_$invoke sup-
          plies a process handle for the child process by which the parent
          process can monitor its status.

     process_handle
          A process handle for the invoked program.  The process handle is not
          valid if the program was invoked in background mode.

     status
          The completion status.  If pgm_$invoke was called to invoke a pro-
          gram in wait mode, then status is the completion status of the
          invoked program or one of the following predefined severity levels:

          pgm_$true
               The value of a tested condition is true.

          pgm_$false
               The value of a tested condition is false.

          pgm_$warning
               An unusual, but not fatal, condition was detected.

          pgm_$error
               There were syntactic or semantic errors in the input, but the
               output is structurally sound.

          pgm_$invalid_output
               There were syntactic or semantic errors in the input, and the
               output is not structurally sound.

          pgm_$internal_fatal
               A fatal internal error detected.

NOTES
     When a program is invoked in default mode, some of the parent's resources
     are reserved to keep track of the child processes whose handles are held
     by the parent process.  A parent process that indiscriminately invokes
     programs in default mode will eventually exhaust system resources unless
     it orphans its child processes by calling pgm_$make_orphan.

SEE ALSO
     pm_$intro.