41 – PPL$SET_QUORUM
The Set Barrier Quorum routine dynamically sets a value for the
specified barrier's quorum.
Format
PPL$SET_QUORUM barrier-id ,quorum
41.1 – Arguments
barrier-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the barrier. The barrier-id argument is the address
of the barrier identifier.
Barrier-id is returned by PPL$CREATE_BARRIER.
quorum
OpenVMS usage word_signed
type word (signed)
access read only
mechanism by reference
The number of participants required to terminate an active
wait for this barrier. The quorum argument is the address of a
signed word containing the quorum number. For example, a quorum
value of 3 indicates that the first two callers of PPL$WAIT_
AT_BARRIER specifying this barrier-id are blocked until a third
participant calls PPL$WAIT_AT_BARRIER. At that point, all three
are released for further processing. If you specify zero for
quorum, the quorum is set to the number of processes currently in
the application. The value of quorum must be positive or zero.
42 – PPL$SET_SEMAPHORE_MAXIMUM
The Set a Semaphore Maximum routine dynamically sets the maximum
value of a semaphore.
Format
PPL$SET_SEMAPHORE_MAXIMUM semaphore-id ,semaphore-maximum
42.1 – Arguments
semaphore-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the semaphore. The semaphore-id argument is the
address of an unsigned longword containing the identifier.
semaphore-maximum
OpenVMS usage word_signed
type word (signed)
access read only
mechanism by reference
New maximum value of the semaphore. The semaphore-maximum
argument is the address of a signed word containing the maximum
value. This value must be nonnegative.
43 – PPL$SPAWN
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]
43.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).
44 – PPL$STOP
The Stop a Participant routine terminates the execution of the
specified participant in this application.
Format
PPL$STOP participant-index
44.1 – Arguments
participant-index
OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by reference
PPL$-defined index of the participant to be terminated. The
participant-index argument is the address of an unsigned longword
containing the index.
Participant-index is obtained by a call to PPL$SPAWN or PPL$GET_
INDEX.
45 – PPL$TERMINATE
The Abort PPL$ Participation routine ends the caller's
participation in the application "prematurely"-that is, at some
time before the caller actually completes its execution.
Format
PPL$TERMINATE [flags]
45.1 – Arguments
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Bit mask specifying options for terminating access to PPL$. The
flags argument is the address of a longword bit mask containing
the flag. The flags argument accepts the following value:
PPL$M_STOP_ Terminates all subordinates created by
CHILDREN the caller in addition to terminating the
caller itself. (PPL$ makes no effort to
delete subordinates at process termination
in the absence of a call to this routine
specifying this flag value, but note that an
OpenVMS subprocess is deleted when the parent
terminates.)
46 – PPL$TRIGGER_EVENT
The Trigger an Event routine causes the event's state to become
occurred. You control whether all pending actions for the event
are processed (made to occur), or just one is processed. A
pending action can be an AST, a signal (condition), or a wakeup.
Format
PPL$TRIGGER_EVENT event-id [,event-param] [,flags]
46.1 – Arguments
event-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the event. The event-id argument is the address of
an unsigned longword containing the identifier.
Event-id is returned by PPL$CREATE_EVENT.
event-param
OpenVMS usage user_arg
type longword (unsigned)
access read only
mechanism by value
An arbitrary value to be passed to all requests processed for
the event as a result of the trigger, or, if there are no queued
event notification requests for this event, to the first caller
to enable event notification. The event-param argument is the
address of an unsigned longword containing this value. The value
of event-param is received by the output argument of PPL$AWAIT_
EVENT.
If a participant enables delivery of an AST by calling
PPL$ENABLE_EVENT_AST, this argument appears in the second
longword of the vector specified by the astprm argument. If a
participant enables delivery of a signal by calling PPL$ENABLE_
EVENT_SIGNAL, this argument appears as the third longword in the
signal vector when the condition is raised.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Specifies options for triggering an event. The flags argument is
the address of a longword bit mask containing the flag. The valid
value for flags is as follows:
PPL$M_NOTIFY_ONE Processes exactly one enabled event
notification. By default, all pending actions
are processed when the event state becomes
occurred.
47 – PPL$UNIQUE_NAME
The Produce a Unique Name routine returns an application-unique
name. A system-unique string specific to the calling application
is appended to the string specified by the user. The resulting
name is identical for all participants in the application, but
different from those for all other applications on that system.
Format
PPL$UNIQUE_NAME name-string ,resultant-string
[,resultant-length] [,flags]
47.1 – Arguments
name-string
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
The user-supplied string to be appended by the 'TOP' processes'
PID. When combined, they will provide a name unique to this
application.
resultant-string
OpenVMS usage char_string
type character string
access write only
mechanism by descriptor
Resulting unique name. The resultant-string argument is the
address of a descriptor pointing to a character string containing
this name. Resultant-string consists of the name-string string
and an appended system-unique string.
resultant-length
OpenVMS usage word_unsigned
type word (unsigned)
access write only
mechanism by reference
Length of the unique name returned as the resultant-string. The
resultant-length argument is the address of an unsigned word
containing this length.
flags
OpenVMS usage word_unsigned
type longword (unsigned)
access write only
mechanism by reference
Specifies whether the supplied name should be unique to the
application, to the calling process, or to this particular call.
The default is application-unique. The valid values for flags are
as follows:
PPL$M_PROC_UNIQUE Indicates that the caller wishes the returned
name to be unique to the calling process.
PPL$M_CALL_UNIQUE Indicates that the caller wishes the returned
name to be unique to this particular call.
48 – PPL$WAIT_AT_BARRIER
The Synchronize at a Barrier routine causes the caller to wait at
the specified barrier. The barrier is in effect from the time the
first participant calls PPL$WAIT_AT_BARRIER until each member of
the quorum has issued the call. At that time, the wait concludes
and all are released for further execution.
Format
PPL$WAIT_AT_BARRIER barrier-id ,flags ,spin
48.1 – Arguments
barrier-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the barrier. The barrier-id argument is the address
of an unsigned longword containing the barrier identifier.
Barrier-id is returned by PPL$CREATE_BARRIER.
flags
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Specifies options for the wait_at_barrier operation. The flags
argument is the value of a longword bit mask containing the flag.
The bit, when set, specifies the corresponding option. Valid
values for flags are as follows:
PPL$M_SPIN_WAIT Indicates that the caller is never to block,
but rather to always spin while waiting at
this barrier.
PPL$M_SPIN_ Indicates that the caller wishes to spin for
COUNTED a given amount of instructions and then to
block.
The default is block immediately, do not spin at all.
spin
OpenVMS usage identifier
type long (unsigned)
access read only
mechanism by reference
This value must be specified when using the PPL$M_SPIN_COUNTED
flag and represents a relative time that a process will spin
before blocking.