PGM_$INTRO Domain/OS PGM_$INTRO
NAME
intro - the program manager
SYNOPSIS (C)
#include <apollo/base.h>
#include <apollo/pgm.h>
SYNOPSIS (Pascal)
%include '/sys/ins/base.ins.pas';
%include '/sys/ins/pgm.ins.pas';
SYNOPSIS (FORTRAN)
%include '/sys/ins/base.ins.ftn'
%include '/sys/ins/pgm.ins.ftn'
DESCRIPTION
The pgm_$ calls allow programs to invoke other programs, pass system
resources to child processes, and monitor their status.
The following is a list of the pgm_$ calls.
pgm_$del_arg delete a program argument
pgm_$exit exit a program
pgm_$get_arg get a program argument
pgm_$get_args get the program argument vector
pgm_$get_ec get a process eventcount
pgm_$get_puid get a process UID
pgm_$invoke invoke a program
pgm_$make_orphan orphan a process
pgm_$proc_wait wait on a process
pgm_$set_severity set the exit severity level
Constants
pgm_$error
The severity level to indicate that an error occurred in an invoked
program.
pgm_$false
A severity level to indicate that a condition was false.
pgm_$internal_fatal
A severity level to indicate that an internal fatal error occured in
an invoked program.
pgm_$max_severity
The highest exit severity level that can be returned by an invoked
program.
pgm_$ok
A severity level to indicate that an invoked program completed suc-
cessfully.
pgm_$output_invalid
A severity level to indicate that the output from an invoked program
is invalid.
pgm_$program_faulted
A severity level to indicate that an invoked program was faulted.
pgm_$true
A severity level to indicate that a condition was true.
pgm_$warning
A severity level to indicate a warning.
Data Types
pgm_$arg A record for passing program arguments. The following diagram
illustrates the pgm_$arg data type:
15 0
______________________________________________________________
| len |
|_____________________________________________________________|
| chars | ... |
______________________________________________________________
15 8 7 0
len The number of significant bytes in chars.
chars
A character array to hold the text of the argument.
pgm_$argv
An array of program arguments.
pgm_$argv_ptr
A pointer to a program argument.
pgm_$connv
An array for passing stream IDs to invoked programs.
pgm_$ec_key
A key specifying a process eventcount. Currently, pgm_$child_proc
is the only valid value. It designates an eventcount that advances
when a child process terminates.
pgm_$mode
A small set type to specify the mode in which to invoke a program.
It can take on any combination of the following predefined 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.
pgm_$proc
A pointer type used as a process handle.
Errors
pgm_$no_arg
There is no argument in the argument vector at the specified posi-
tion.
pgm_$arg_too_big
The argument requested is too big to fit in the buffer allocated for
it.
pgm_$bad_connv
Attempted to pass too many stream IDs in the connection vector.
pgm_$no_entry_point
There is no entry point in the invoked program.
pgm_$not_a_program
Attempted to invoke a file that is not an object.
pgm_$on_signal_stack
Attempted to invoke a program inprocess while running on the signal
stack. See BSD sigstack(2).
pgm_$option_conflict
Specified incompatible options to pgm_$invoke.
pgm_$process_vforked
Cannot call pgm_$invoke from a process created by a BSD vfork(2).
pgm_$wrong_format
Attempted to invoke a COFF object module with the pgm_$obj_only
option.