VMS Help RTL Routines, PPL$, PPL$SPAWN  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    The Initiate Parallel Execution routine executes code in parallel
    with the caller by creating one or more subordinate threads of
    execution (OpenVMS subprocesses).

    Format

      PPL$SPAWN  copies [,program-name] [,children-ids] [,flags]

                 [,std-input-file] [,std-output-file]

1 - Arguments

 copies

    OpenVMS usage longword_unsigned
    type          longword (unsigned)
    access        modify
    mechanism     by reference
    Number of subordinates of the specified program to be executed
    concurrently. The copies argument is the address of an unsigned
    longword containing this number. Its value must be positive.
    If you specify a value greater than 1 for the copies argument,
    each copy created will have the same subprocess information (for
    example, standard input and output files). If you want to specify
    different information for each subprocess, call PPL$SPAWN once
    for each subprocess.

    On output, this parameter contains the number of subordinates
    actually created. This value differs from the requested number
    if an individual spawn attempt fails, for example, because of
    insufficient quotas.

 program-name

    OpenVMS usage logical_name
    type          character string
    access        read only
    mechanism     by descriptor, fixed-length
    Name of the program (image) to be invoked. The program-name
    argument is the address of a descriptor pointing to a character
    string containing the file specification of the image. Program-
    name must have no more than 63 characters. If program-name
    contains a logical name, the equivalence name must be in a
    logical name table that the created subordinate can access. If
    you do not specify a program-name, the default is to execute in
    parallel the image being run by the caller.

 children-ids

    OpenVMS usage vector_longword_unsigned
    type          longword (unsigned)
    access        write only
    mechanism     by reference, array reference
    Identifiers of each of the newly created subordinates. The
    children-ids argument is the address of a vector of longwords
    into which is written the index within the executing application
    of each subordinate successfully initiated by this call.

 flags

    OpenVMS usage mask_longword
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Bit mask specifying options for creating processes. The flags
    argument is a longword bit mask containing the flags. Valid
    values for flags are as follows:

    PPL$M_INIT_      If set, the caller of this routine and
    SYNCH            all subordinates created by this call are
                     synchronized to continue processing only after
                     each and every subordinate created by this call
                     has called PPL$CREATE_APPLICATION. (See the
                     Description section for more information.) A
                     failure of the created subordinate after it
                     successfully starts but before its call to
                     PPL$CREATE_APPLICATION can cause difficulties
                     with the use of this flag value.
    PPL$M_NOCLISYM   If set, the created processes do not inherit CLI
                     symbols from the calling process. The default
                     action is for created processes to inherit all
                     currently defined CLI symbols.
    PPL$M_           If set, prompt strings are not prefixed by
    NOCONTROL        carriage return/line feeds. The default action
                     is to prefix any prompt string specified with a
                     carriage return/line feed.
    PPL$M_NODEBUG    Prevents the startup of the OpenVMS Debugger,
                     even if the debugger was linked with the image.
    PPL$M_NOKEYPAD   If set, created processes inherit the current
                     keypad symbols and state from the calling
                     process. The default action is that created
                     processes do not inherit keypad symbols and
                     state.
    PPL$M_NOLOGNAM   If set, created processes do not inherit process
                     logical names from the calling process. The
                     default is for created processes to inherit all
                     currently defined process logical names.
    PPL$M_NOTIFY     If set, a message is broadcast to SYS$OUTPUT as
                     each process terminates. This flag is ignored if
                     the process is not interactive (for example, run
                     in batch).

 std-input-file

    OpenVMS usage logical-name
    type          character string
    access        read only
    mechanism     by descriptor
    File name of the file to serve as the standard input file in the
    created subordinates. The std-input-file argument is the address
    of a descriptor pointing to a character string containing the
    file name. If you do not specify a value for this argument, the
    subordinate inherits the creating participant's standard input
    file (SYS$INPUT).

 std-output-file

    OpenVMS usage logical-name
    type          character string
    access        read only
    mechanism     by descriptor
    File name of the file to serve as the standard output file in the
    created subordinates. The std-output-file argument is the address
    of a descriptor pointing to a character string containing the
    file name. If you do not specify a value for this argument, the
    subordinate inherits the creating participant's standard output
    file (SYS$OUTPUT).