RTL Routines, PPL$
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
VMS Help RTL Routines, PPL$ *Conan The Librarian (sorry for the slow response - running on an old VAX) |
|
| 1 - PPL$ADJUST_QUORUM |
The Adjust Barrier Quorum routine increments or decrements the
quorum associated with a barrier.
Format
PPL$ADJUST_QUORUM barrier-id ,amount
1.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.
amount
OpenVMS usage word_signed
type word (signed)
access read only
mechanism by reference
Value to add to the barrier quorum. The amount argument is the
address of a signed word containing the amount. You can specify a
negative value to decrement the quorum.
| 2 - PPL$ADJUST_SEMAPHORE_MAXIMUM |
The Adjust a Semaphore Maximum routine increments or decrements
the maximum associated with a semaphore.
Format
PPL$ADJUST_SEMAPHORE_MAXIMUM semaphore-id ,amount
2.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.
amount
OpenVMS usage word_signed
type word (signed)
access read only
mechanism by reference
Value to add to the semaphore maximum. The amount argument is
the address of a signed word containing the amount. Specify a
positive value for amount to increase the maximum; specify a
negative value to decrease the maximum.
| 3 - PPL$AWAIT_EVENT |
The Await Event Occurrence routine blocks the caller until an
event occurs.
Format
PPL$AWAIT_EVENT event-id [,output]
3.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.
The event-id is returned by PPL$CREATE_EVENT.
output
OpenVMS usage user_arg
type longword (unsigned)
access write only
mechanism by reference
Receives the event-param argument from PPL$TRIGGER_EVENT. The
output argument is the address of an unsigned longword that
receives the value of event-param. The value of event-param is
copied to output when an event is triggered.
| 4 - PPL$CREATE_APPLICATION |
The Form or Join a PPL$ Application routine informs the PPL$
facility that the calling process is forming or joining a
parallel application.
Format
PPL$CREATE_APPLICATION [size] [,application-name]
[,protection] [,flags]
4.1 - Arguments
size
OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by reference
Number of (512 byte) pages that PPL$ allocates for its internal
data structures. The optional size argument is the address of an
unsigned longword containing this size value. See the Description
section for information about the default value.
application-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
The name of the application that the calling process will form or
join. The optional application-name argument is the address of a
descriptor pointing to a character string containing the name of
the application. The application-name argument can contain up to
11 characters.
protection
OpenVMS usage file_protection
type longword (unsigned)
access read only
mechanism by reference
Numeric value representing the protection mask to be applied to
the application. The optional protection argument is the address
of an unsigned longword containing this numeric value. For more
information, see the description of the $CRMPSC system service in
the OpenVMS System Services Reference Manual.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Specifies options for forming or joining a PPL$ application. The
flags argument is a longword bit mask containing the flags. Valid
values for flags are as follows:
PPL$M_ Form a new application only-do not join an
FORMONLY existing application. If this flag is not
specified, a process will join an application
if it already exists.
PPL$M_ Join an existing application only-do not form a
JOINONLY new application. If this flag is not specified,
a process will form an application if it does not
already exist.
PPL$M_PERM Form a permanent application in which data is
maintained even though there are no active
processes. By default, application data is lost
when the last process in the application exits.
Use of this flag requires PRMGBL privilege.
PPL$M_SYSTEM Form or join a systemwide application. By default,
the application is available only to processes
running under the same group UIC. Use of this flag
requires SYSGBL and SYSLCK privileges.
| 5 - PPL$CREATE_BARRIER |
The Create a Barrier routine creates and initializes a barrier,
and returns the barrier identifier. You use the barrier
identifier to perform all operations on that barrier.
Format
PPL$CREATE_BARRIER barrier-id [,barrier-name] [,quorum]
5.1 - Arguments
barrier-id
OpenVMS usage identifier
type longword (unsigned)
access write only
mechanism by reference
Identifier of the barrier. The barrier-id argument is the address
of an unsigned longword containing the identifier. Barrier-id
must be used in calls to the other barrier routines (listed in
the Description section) to identify the barrier.
barrier-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the barrier. The optional barrier-name argument is the
address of a descriptor pointing to a character string containing
the barrier name. The name of the barrier is arbitrary. If you
do not specify this argument, or if you specify 0, an unnamed
barrier is created. An arbitrary number of unnamed barriers may
be created by a given application.
quorum
OpenVMS usage word_signed
type word (signed)
access read only
mechanism by reference
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 caller calls
PPL$WAIT_AT_BARRIER. At that point, all three participants are
released for further processing. If you do not specify a value
for quorum, a default value of 1 is assigned.
| 6 - PPL$CREATE_EVENT |
The Create an Event routine creates an arbitrary user-defined
event and returns the event identifier. You use the event
identifier to perform all operations on that event.
Format
PPL$CREATE_EVENT event-id [,event-name]
6.1 - Arguments
event-id
OpenVMS usage identifier
type longword (unsigned)
access write only
mechanism by reference
Identifier of the event. The event-id argument is the address of
an unsigned longword containing the identifier. Event-id must be
used in other calls to identify the event.
event-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the event. The event-name argument is the address of a
descriptor pointing to a character string containing the event
name. The name of the event is entirely arbitrary. If you do
not specify a value for event-name, or if you specify 0, a new
unnamed event is created, which can be referenced only by its
identifier. An arbitrary number of unnamed events can be created
by a given application.
| 7 - PPL$CREATE_SEMAPHORE |
The Create a Semaphore routine creates and initializes a
semaphore with a waiting queue, and returns the semaphore
identifier. You use the semaphore identifier to perform all
operations on that semaphore.
Format
PPL$CREATE_SEMAPHORE semaphore-id [,semaphore-name]
[,semaphore-maximum] [,semaphore-initial]
7.1 - Arguments
semaphore-id
OpenVMS usage identifier
type longword (unsigned)
access write only
mechanism by reference
Identifier of the semaphore. The semaphore-id argument is the
address of an unsigned longword containing the identifier.
Semaphore-id must be used in other calls to identify the
semaphore.
semaphore-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the semaphore. The semaphore-name argument is the address
of a descriptor pointing to a character string containing
the semaphore name. The name of the semaphore is entirely
arbitrary. If you do not specify a value for semaphore-name,
or if you specify 0, a new unnamed semaphore is created. An
arbitrary number of unnamed semaphores may be created by a given
application.
semaphore-maximum
OpenVMS usage word_signed
type word (signed)
access read only
mechanism by reference
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. If you do not supply a value for
semaphore-maximum, a default value of 1 is used, thereby making
it a binary semaphore.
semaphore-initial
OpenVMS usage word_signed
type word (signed)
access read only
mechanism by reference
Initial value of the semaphore. The semaphore-initial argument is
the address of a signed word containing the initial value. This
value must be less than or equal to the semaphore-maximum value.
If you do not supply a value for semaphore-initial, a default
value equal to semaphore-maximum is used.
| 8 - PPL$CREATE_SHARED_MEMORY |
The Create Shared Memory routine creates (if necessary) and maps
a section of memory that can be shared by multiple processes.
Format
PPL$CREATE_SHARED_MEMORY section-name ,memory-area [,flags]
[,file-name] [,protection]
8.1 - Arguments
section-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the shared memory section you want to create. The
section-name argument is the address of a descriptor pointing
to the shared memory section name.
memory-area
OpenVMS usage vector_longword_unsigned
type longword (unsigned)
access modify
mechanism by reference, array reference
The area of memory into which the shared memory is mapped. The
memory-area argument is the address of a two-longword array
containing, in order, the length (in bytes) and the starting
virtual address for the area of memory.
If you specify the starting address as zero, the PPL$ facility
selects the virtual address space so that each current process
in the application can map the section to the same set of virtual
addresses.
PPL$CREATE_SHARED_MEMORY returns to this argument the actual
length and starting virtual address of the shared memory created
or mapped.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Specifies options for creating and mapping shared memory. The
flags argument is the address of a longword bit mask containing
the flag. Valid values are as follows:
PPL$M_NOZERO Does not initialize the shared memory to zero. By
default, PPL$CREATE_SHARED_MEMORY initializes the
shared memory to zero.
PPL$M_NOWRT Maps the shared memory with no write access (in
other words, read only). By default, the shared
memory is available with read/write access.
PPL$M_NOUNI Names the shared memory a nonunique name. By
default, PPL$CREATE_SHARED_MEMORY gives the
specified shared memory a name unique to the
application by using PPL$UNIQUE_NAME.
PPL$M_PERM Creates permanent shared memory in which data
is maintained even though there are no active
processes. The default is determined by your
call to PPL$CREATE_APPLICATION: if you specify
the PPL$M_PERM flag in your call to PPL$CREATE_
APPLICATION, this behavior is the default and
you do not need to specify PPL$M_PERM in your
call to PPL$CREATE_SHARED_MEMORY. If you do not
specify the PPL$M_PERM flag in your calls to
PPL$CREATE_APPLICATION and PPL$CREATE_SHARED_
MEMORY, application data is lost when the last
process in the application exits. Use of this flag
requires PRMGBL privilege.
PPL$M_SYSTEM Creates systemwide shared memory. The default is
determined by your call to PPL$CREATE_APPLICATION:
if you specify the PPL$M_SYSTEM flag in your call
to PPL$CREATE_APPLICATION, this behavior is the
default and you do not need to specify PPL$M_
SYSTEM in your call to PPL$CREATE_SHARED_MEMORY.
If you do not specify the PPL$M_SYSTEM flag in your
calls to PPL$CREATE_APPLICATION and PPL$CREATE_
SHARED_MEMORY, the application is available only to
processes running under the same group UIC. Use of
this flag requires the SYSGBL privilege.
file-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the file used for backup storage of the shared memory.
The file-name argument is the address of a descriptor pointing
to the file name. The size of the resulting address space is the
smaller of the following:
o The specified section size
o The size of the file being mapped
If you do not specify a file name, PPL$CREATE_SHARED_MEMORY
creates for backup storage a page file section instead of a disk
file section.
If you specify a file that does not exist, PPL$CREATE_SHARED_
MEMORY creates it.
protection
OpenVMS usage file_protection
type longword (unsigned)
access read only
mechanism by reference
Numeric value representing the protection mask to be applied
to the shared memory. The optional protection argument is the
address of an unsigned longword containing this numeric value.
If you do not specify a value, the default is the value for
protection specified in the call to PPL$CREATE_APPLICATION.
For more information, see the description of the $CRMPSC system
service in the OpenVMS System Services Reference Manual.
| 9 - PPL$CREATE_SPIN_LOCK |
The Create Spin Lock routine creates and initializes a simple
(spin) lock, and returns the lock identifier. You use that lock
identifier to get and free the lock.
Format
PPL$CREATE_SPIN_LOCK lock-id [,lock-name]
9.1 - Arguments
lock-id
OpenVMS usage identifier
type longword (unsigned)
access write only
mechanism by reference
Identifier of the newly created lock. The lock-id argument is the
address of an unsigned longword containing the lock identifier.
You must use lock-id when getting or freeing the lock.
lock-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the lock. The lock-name argument is the address of a
descriptor pointing to a character string containing the name.
The name of the lock is entirely arbitrary. If you do not specify
this argument, or if you specify 0, an unnamed lock is created.
An arbitrary number of unnamed locks can be created by a given
application.
| 10 - PPL$CREATE_VM_ZONE |
The Create a New Virtual Memory Zone routine creates a new
storage zone, according to specified arguments, which is
available to all participants in the application.
Format
PPL$CREATE_VM_ZONE zone-id [,algorithm] [,algorithm-argument]
[,flags] [,extend-size] [,initial-size]
[,block-size] [,alignment] [,page-limit]
[,smallest-block-size] [,zone-name]
10.1 - Arguments
zone-id
OpenVMS usage identifier
type longword (unsigned)
access write only
mechanism by reference
Zone identifier. The zone-id argument is the address of a
longword set to the zone identifier of the newly created zone.
algorithm
OpenVMS usage longword_signed
type longword (signed)
access read only
mechanism by reference
Algorithm. The algorithm argument is the address of a signed
longword that represents the code for one of the LIB$VM
algorithms:
1 LIB$K_VM_FIRST_ First fit
FIT
2 LIB$K_VM_QUICK_ Quick fit, lookaside list
FIT
3 LIB$K_VM_FREQ_ Frequent sizes, lookaside list
SIZES
4 LIB$K_VM_FIXED Fixed size blocks
If algorithm is not specified, a default of 1 (first fit) is
used.
algorithm-argument
OpenVMS usage longword_signed
type longword (signed)
access read only
mechanism by reference
Algorithm argument. The algorithm-argument argument is the
address of a signed longword that contains a value specific to
the particular allocation algorithm.
Algorithm Value
QUICK_FIT The number of queues used. The number of queues must
be between 1 and 128.
FREQ_SIZES The number of cache slots used. The number of cache
slots must be between 1 and 16.
FIXED The fixed request size (in bytes) for each get or
free. The request size must be greater than 0.
FIRST_FIT Not used, may be omitted.
The algorithm-argument argument must be specified if you are
using the quick-fit, frequent-sizes, or fixed-size-blocks
algorithms. However, this argument is optional if you are using
the first-fit algorithm.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Flags. The flags argument is the address of an unsigned longword
that contains flag bits that control various options:
Bit Value Description
Bit LIB$M_VM_BOUNDARY_ Boundary tags for faster freeing
0 TAGS
Adds a minimum of eight bytes to each
block
Bit LIB$M_VM_GET_FILL0 LIB$GET_VM; fill with bytes of 0
1
Bit LIB$M_VM_GET_FILL1 LIB$GET_VM; fill with bytes of FF
2 (hexadecimal)
Bit LIB$M_VM_FREE_FILL0 LIB$FREE_VM; fill with bytes of 0
3
Bit LIB$M_VM_FREE_FILL1 LIB$FREE_VM; fill with bytes of FF
4 (hexadecimal)
Bit LIB$M_VM_EXTEND_ Add extents to existing areas if
5 AREA possible
Bits 6 through 31 are reserved and must be 0.
This is an optional argument. If flags is omitted, the default of
0 (no fill and no boundary tags) is used.
extend-size
OpenVMS usage longword_signed
type longword (signed)
access read only
mechanism by reference
Zone extend size. The extend-size argument is the address of a
signed longword that contains the number of (512-byte) pages to
be added to the zone each time it is extended.
The value of extend-size must be between 1 and 1024.
This is an optional argument. If extend-size is not specified, a
default of 16 pages is used.
NOTE
Extend-size does not limit the number of blocks that can be
allocated from the zone. The actual extension size is the
greater of extend-size and the number of pages needed to
satisfy the LIB$GET_VM call that caused the extend.
initial-size
OpenVMS usage longword_signed
type longword (signed)
access read only
mechanism by reference
Initial size for the zone. The initial-size argument is the
address of a signed longword that contains the number of (512-
byte) pages to be allocated for the zone as the zone is created.
This is an optional argument. If initial-size is not specified
or is specified as 0, no pages are allocated when the zone is
created. The first call to LIB$GET_VM for the zone allocates
extend-size pages.
block-size
OpenVMS usage longword_signed
type longword (signed)
access read only
mechanism by reference
Block size of the zone. The block-size argument is the address
of a signed longword specifying the allocation quantum (in bytes)
for the zone. All blocks allocated are rounded up to a multiple
of block-size.
The value of block-size must be a power of 2 between 8 and 512.
This is an optional argument. If block-size is not specified, a
default of 8 is used.
alignment
OpenVMS usage longword_signed
type longword (signed)
access read only
mechanism by reference
Block alignment. The alignment argument is the address of a
signed longword that specifies the required address alignment
(in bytes) for each block allocated.
The value of alignment must be a power of 2 between 4 and 512.
This is an optional argument. If alignment is not specified, a
default of 8 (quadword alignment) is used.
page-limit
OpenVMS usage longword_signed
type longword (signed)
access read only
mechanism by reference
Maximum page limit. The page-limit argument is the address of a
signed longword that specifies the maximum number of (512-byte)
pages that can be allocated for the zone. The value of page-limit
must be between 0 and 32,767. Note that part of the zone is used
for header information.
This is an optional argument. If page-limit is not specified or
is specified as 0, the only limit is the total process virtual
address space limit imposed by the OpenVMS operating system.
If page-limit is specified, then initial-size must also be
specified.
smallest-block-size
OpenVMS usage longword_signed
type longword (signed)
access read only
mechanism by reference
Smallest block size. The smallest-block-size argument is the
address of a signed longword that specifies the smallest block
size (in bytes) with a queue for the quick fit algorithm.
If smallest-block-size is not specified, the default of block-
size is used. That is, queues are provided for the first n
multiples of block-size.
zone-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name to be associated with the zone being created. The optional
zone-name argument is the address of a descriptor pointing to a
character string containing the zone name. If zone-name is not
specified, the zone does not have an associated name.
| 11 - PPL$CREATE_WORK_QUEUE |
The Create a Work Queue routine creates and initializes a work
queue and returns the work queue identifier.
Format
PPL$CREATE_WORK_QUEUE queue-id [,queue-name]
11.1 - Arguments
queue-id
OpenVMS usage identifier
type longword (unsigned)
access write only
mechanism by reference
The work queue identifier. The queue-id argument is the address
of an unsigned longword containing the identifier. Queue-id must
be used in calls to the other work queue routines to identify the
work queue.
queue-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the work queue. The optional queue-name argument is the
address of a descriptor pointing to a character string containing
the work queue name. The work queue name is case sensitive. If
you do not specify this argument, or if you specify 0, an unnamed
work queue is created. An arbitrary number of unnamed work queues
may be created by a given application.
| 12 - PPL$DECREMENT_SEMAPHORE |
The Decrement a Semaphore routine waits for a semaphore to have a
value greater than 0, then decrements the value by 1 to indicate
the allocation of a resource.
Format
PPL$DECREMENT_SEMAPHORE semaphore-id [,flags] [,spin]
12.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-id is returned by PPL$CREATE_SEMAPHORE.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Bit mask specifying options for decrementing the semaphore. The
flags argument is a longword bit mask containing the flag. The
valid values for flags are as follows:
PPL$M_NON_ Indicates that the caller is not to block if
BLOCKING the resource is not available. The default is
FALSE: the caller will block if resource is
unavailable.
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 mask_longword
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.
| 13 - PPL$DELETE_APPLICATION |
The Delete a PPL$ Application routine marks all shared memory
for deletion and prevents additional processes from joining the
application.
Format
PPL$DELETE_APPLICATION
| 14 - PPL$DELETE_BARRIER |
The Delete a Barrier routine deletes a barrier and releases any
storage associated with it.
Format
PPL$DELETE_BARRIER [barrier-id] [,barrier-name]
14.1 - Arguments
barrier-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the barrier. The optional barrier-id argument
is the address of an unsigned longword containing the barrier
identifier.
barrier-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the barrier. The optional barrier-name argument is the
address of a descriptor pointing to a character string containing
the barrier name.
| 15 - PPL$DELETE_EVENT |
The Delete an Event routine deletes an event and releases any
storage associated with it.
Format
PPL$DELETE_EVENT [event-id] [,event-name]
15.1 - Arguments
event-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the event. The optional event-id argument is the
address of an unsigned longword containing the event identifier.
event-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the event. The optional event-name argument is the
address of a descriptor pointing to a character string containing
the event name.
| 16 - PPL$DELETE_SEMAPHORE |
The Delete a Semaphore routine deletes a semaphore and releases
any storage associated with it.
Format
PPL$DELETE_SEMAPHORE [semaphore-id] [,semaphore-name]
16.1 - Arguments
semaphore-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the semaphore. The optional semaphore-id argument
is the address of an unsigned longword containing the semaphore
identifier.
semaphore-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the semaphore. The optional semaphore-name argument
is the address of a descriptor pointing to a character string
containing the semaphore name.
| 17 - PPL$DELETE_SHARED_MEMORY |
The Delete Shared Memory routine deletes or unmaps from a global
section that you created using the PPL$CREATE_SHARED_MEMORY
routine. Optionally, this routine writes the contents of the
global section to disk before deleting the section.
Format
PPL$DELETE_SHARED_MEMORY section-name [,memory-area] [,flags]
17.1 - Arguments
section-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the global section you want to delete. The section-name
argument is the address of a descriptor pointing to a character
string containing the global section name.
memory-area
OpenVMS usage vector_longword_unsigned
type longword (unsigned)
access read only
mechanism by reference, array reference
The area of memory into which the global section that you want
to delete is mapped. The memory-area argument is the address of a
two-longword array containing, in order, the length in bytes and
the starting virtual address of the area of memory.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Bit mask specifying actions to be performed before deleting the
global section. The flags argument is the address of a longword
bit mask containing the flag. Valid values for flags are as
follows:
PPL$M_FLUSH Writes the global section to disk before deleting
it.
PPL$M_NOUNI Identifies the global section as having a
nonunique name. By default, PPL$CREATE_SHARED_
MEMORY gives the specified global section a name
unique to the application by using PPL$UNIQUE_
NAME. If you specified this value to give the
global section a nonunique name when you called
PPL$CREATE_SHARED_MEMORY, you must also specify
it when you call PPL$DELETE_SHARED_MEMORY.
| 18 - PPL$DELETE_SPIN_LOCK |
The Delete a Spin Lock routine deletes a spin lock and releases
any storage associated with it.
Format
PPL$DELETE_SPIN_LOCK [lock-id] [,lock-name]
18.1 - Arguments
lock-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the lock. The optional lock-id argument is the
address of an unsigned longword containing the lock identifier.
lock-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the lock. The optional lock-name argument is the address
of a descriptor pointing to a character string containing the
lock name.
| 19 - PPL$DELETE_VM_ZONE |
The Delete a Virtual Memory Zone routine deletes a storage zone
and returns all pages owned by the zone to the application-wide
page pool.
Format
PPL$DELETE_VM_ZONE [zone-id] [,zone-name]
19.1 - Arguments
zone-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the zone. The optional zone-id argument is the
address of an unsigned longword containing the zone identifier.
zone-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the zone. The optional zone-name argument is the address
of a descriptor pointing to a character string containing the
zone name.
| 20 - PPL$DELETE_WORK_ITEM |
The Delete a Work Queue Item routine deletes a work item from a
work queue.
Format
PPL$DELETE_WORK_ITEM queue-id ,work-item [,flags]
20.1 - Arguments
queue-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
The queue identifier. The queue-id argument is the address of an
unsigned longword containing the identifier.
work-item
OpenVMS usage user_arg
type longword (unsigned)
access read only
mechanism by value
The value of the item to be deleted from the queue. The work-item
argument is the address of an unsigned longword containing this
value.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Specifies options for deleting items from a work queue. The
optional flags argument is the address of a longword bit mask
containing the flag. Valid values are as follows:
PPL$M_DELETEALL Delete all items in the specified queue whose
value matches work-item. By default, only the
first item encountered is deleted.
PPL$M_TAILFIRST Begin searching at the end of the queue and
move toward the beginning. By default, the
search begins at the beginning of the queue
and moves toward the end.
| 21 - PPL$DELETE_WORK_QUEUE |
The Delete a Work Queue routine deletes the specified work queue,
and releases any storage associated with it.
Format
PPL$DELETE_WORK_QUEUE [queue-id] [,queue-name] [,flags]
21.1 - Arguments
queue-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
The work queue identifier. The optional queue-id argument is the
address of an unsigned longword containing the identifier.
queue-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the work queue. The optional queue-name argument is the
address of a descriptor pointing to a character string containing
the work queue name.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Specifies options for deleting a work queue. The optional flags
argument is the address of a longword bit mask containing the
flag. The valid value is as follows:
PPL$M_FORCEDEL Delete the work queue regardless of whether it
is empty. By default, PPL$ returns the error
PPL$_ELEINUSE if you attempt to delete a work
queue at which proceses are blocked or that
contains work items.
| 22 - PPL$DISABLE_EVENT |
The Disable Asynchronous Notification of an Event routine
disables delivery to a process of notification of an event by
either AST or signal.
Format
PPL$DISABLE_EVENT event-id
22.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.
| 23 - PPL$ENABLE_EVENT_AST |
The Enable AST Notification of an Event routine specifies the
address of an AST routine (and optionally an argument to that
routine) to be delivered when an event occurs.
Format
PPL$ENABLE_EVENT_AST event-id ,astadr [,astprm]
23.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.
astadr
OpenVMS usage ast_procedure
type procedure value
access call without stack unwinding
mechanism by reference
AST routine. The astadr argument is a procedure value of the
user's AST routine. This routine is called on the user's behalf
when the event state becomes occurred.
astprm
OpenVMS usage user_arg
type unspecified
access read only
mechanism by value
AST value passed as the argument to the specified AST routine.
The astprm argument is the address of a vector of unsigned
longwords containing this optional value. If this argument is not
specified, PPL$_EVENT_OCCURRED is the astprm for a user-created
event. The astprm argument has special restrictions when used in
conjunction with the PPL$ event routines.
o For user-defined events, the AST-argument must point to a
vector of two unsigned longwords. The first longword is a
"context" reserved for the user; it is not read or modified
by PPL$. The second longword receives the value specified by
the event-param argument in the call to PPL$TRIGGER_EVENT that
results in the delivery of this AST.
o For PPL$-defined events (those not created by the user),
the astprm argument must point to a vector of four unsigned
longwords. The vector accommodates the following:
- The user's "context" longword
- The longword to receive the event's distinguishing
condition value
- The parameters to the PPL$-defined event (the "trigger"
parameter)
Because each of the predefined events takes two arguments, the
vector that astprm points to must be four longwords in length.
| 24 - PPL$ENABLE_EVENT_SIGNAL |
The Enable Signal Notification of an Event routine specifies a
condition value to be signaled when the event occurs.
Format
PPL$ENABLE_EVENT_SIGNAL event-id [,signal-value]
24.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.
signal-value
OpenVMS usage user_arg
type longword (unsigned)
access read only
mechanism by value
Optional user-defined value to be signaled when the event occurs.
The signal-value argument is an unsigned longword containing this
value.
| 25 - PPL$FIND_OBJECT_ID |
Given the name of a spin lock, semaphore, barrier, event, work
queue, or shared memory zone, the Find Object Identification
routine returns the identifier of the object associated with the
name you specify.
Format
PPL$FIND_OBJECT_ID object-id ,object-name
25.1 - Arguments
object-id
OpenVMS usage identifier
type longword (unsigned)
access modify
mechanism by reference
Object identifier to be returned. The object-id argument is the
address of an unsigned longword that receives the associated
identifier.
object-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the object for which to return the associated identifier.
The object-name argument is the address of a descriptor pointing
to a character string containing the (user-defined) name of the
object.
| 26 - PPL$FLUSH_SHARED_MEMORY |
The Flush Shared Memory routine writes (flushes) to disk
the contents of a global section that you created using the
PPL$CREATE_SHARED_MEMORY routine. Only pages that have been
modified are flushed to disk.
Format
PPL$FLUSH_SHARED_MEMORY section-name [,memory-area] [,flags]
26.1 - Arguments
section-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the global section whose contents are to be written to
disk. The section-name argument is the address of a descriptor
pointing to a character string containing the global section
name.
memory-area
OpenVMS usage vector_longword_unsigned
type longword (unsigned)
access read only
mechanism by reference, array reference
The area of memory into which the specified global section
is mapped. The memory-area argument is the address of a two-
longword array containing, in order, the length (in bytes) and
the starting virtual address for the area of memory.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Bit mask specifying actions to perform before flushing the global
section. The flags argument is the address of a longword bit mask
containing the flag. The valid value for flags is as follows:
PPL$M_NOUNI Identifies the global section as having a nonunique
name. By default, PPL$CREATE_SHARED_MEMORY gives
the specified global section a name unique to
the application by using PPL$UNIQUE_NAME. If you
specified this value to give the global section a
nonunique name when you called PPL$CREATE_SHARED_
MEMORY, you must also specify it when you call
PPL$FLUSH_SHARED_MEMORY.
| 27 - PPL$GET_INDEX |
The Get Index of a Participant routine returns an index that
is unique within the application. A value of zero signifies the
participant that formed the application. The other participants
in the application always return an index greater than zero.
Format
PPL$GET_INDEX participant-index
27.1 - Arguments
participant-index
OpenVMS usage longword_unsigned
type longword (unsigned)
access write only
mechanism by reference
The index of the caller within this application. The participant-
index argument is the address of an unsigned longword that
contains this index. This index is assigned at process creation
time and is unique for each participant.
| 28 - PPL$INCREMENT_SEMAPHORE |
The Increment a Semaphore routine increments the value of the
semaphore by 1, analogous to the signal protocol. If any other
participants are blocked on a call to PPL$DECREMENT_SEMAPHORE for
this semaphore, one is removed from the queue and awakened. The
semaphore must have been created by PPL$CREATE_SEMAPHORE.
Format
PPL$INCREMENT_SEMAPHORE semaphore-id
28.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-id is returned by PPL$CREATE_SEMAPHORE.
| 29 - PPL$INDEX_TO_PID |
The Convert Participant Index to OpenVMS PID routine returns the
OpenVMS PID of the process associated with the specified index.
Format
PPL$INDEX_TO_PID participant-index ,pid
29.1 - Arguments
participant-index
OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by reference
Index of the caller within this application. The participant-
index argument is the address of an unsigned longword that
contains this index. Participant-index is assigned at process
creation time and is unique for each participant.
pid
OpenVMS usage longword_unsigned
type longword (unsigned)
access write only
mechanism by reference
PID (process identifier) of the OpenVMS process associated with
the specified participant-index. The pid argument is the address
of an unsigned longword that receives this PID.
| 30 - PPL$INSERT_WORK_ITEM |
The Insert a Work Queue Item routine inserts a work item into the
specified work queue.
Format
PPL$INSERT_WORK_ITEM queue-id ,work-item [,flags] [,priority]
30.1 - Arguments
queue-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
The queue identifier. The queue-id argument is the address of an
unsigned longword containing the identifier.
work-item
OpenVMS usage user_arg
type longword (unsigned)
access read only
mechanism by value
A value to be entered into the queue. The work-item argument
is an unsigned longword containing this value. The content of
work-item is completely arbitrary. You may want to place single
longword values into work-item (for example, the number of a
function or task to be performed). You can also use work-item to
pass a pointer to a data block. (This data block must reside in
memory created by PPL$CREATE_SHARED_MEMORY or allocated from a
shared memory zone created by PPL$CREATE_VM_ZONE.)
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Specifies options for inserting a work item into a work queue.
The optional flags argument is the address of a longword bit mask
containing the flag. The valid value is as follows:
PPL$M_ATHEAD Insert item as the first of those items with the
same priority (in other words, at the head of the
priority). By default, items are inserted after
other items of the same priority.
priority
OpenVMS usage longword_signed
type longword (signed)
access read only
mechanism by reference
Specifies the priority of the item being inserted. The optional
priority argument is an unsigned longword containing the priority
value for the item to be inserted. If unspecified, the default
value is zero. A high numerical value indicates a high priority.
| 31 - PPL$PID_TO_INDEX |
The Convert OpenVMS PID to Participant Index routine returns the
PPL$-defined participant index of the process associated with the
specified OpenVMS PID.
Format
PPL$PID_TO_INDEX pid ,participant-index
31.1 - Arguments
pid
OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by reference
PID (process identifier) of the OpenVMS process or subprocess
whose participant index is to be obtained. The pid argument is
the address of an unsigned longword that contains this PID.
participant-index
OpenVMS usage longword_unsigned
type longword (unsigned)
access write only
mechanism by reference
Participant index of the process or subprocess associated with
the specified OpenVMS PID. The participant-index argument is
the address of an unsigned longword that receives this index.
Participant-index is assigned by the PPL$ facility at process
creation time and is unique for each participant.
| 32 - PPL$READ_BARRIER |
The Read a Barrier routine returns the specified barrier's
current quorum and the number of participants currently waiting
(blocked) at the barrier. The barrier must have been created by
PPL$CREATE_BARRIER.
Format
PPL$READ_BARRIER barrier-id ,quorum ,waiters
32.1 - Arguments
barrier-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the specified event. The barrier-id argument is the
address of an unsigned longword containing the identifier.
Barrier-id is returned by PPL$CREATE_BARRIER.
quorum
OpenVMS usage word_signed
type word (signed)
access write only
mechanism by reference
Number of participants required to terminate a wait for this
barrier. The quorum argument is the address of a signed word
containing the quorum value. This argument returns the current
quorum value that you set with PPL$CREATE_BARRIER, PPL$SET_
QUORUM, or PPL$ADJUST_QUORUM.
waiters
OpenVMS usage word_signed
type word (signed)
access write only
mechanism by reference
Number of participants currently waiting at this barrier. The
waiters argument is the address of a signed word containing the
number of waiting participants.
| 33 - PPL$READ_EVENT |
The Read an Event State routine returns the current state of the
specified event. The state can be occurred or not_occurred.
Format
PPL$READ_EVENT event-id ,occurred
33.1 - Arguments
event-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the specified event. The event-id argument is the
address of an unsigned longword containing the identifier.
Event-id is returned by PPL$CREATE_EVENT.
occurred
OpenVMS usage longword_unsigned
type longword (unsigned)
access write only
mechanism by reference
Receives the state of the specified event. The occurred argument
is the address of an unsigned longword that receives the event
state. This argument returns a value of true if the current state
of the event is occurred, and returns false if the current state
of the event is not_occurred.
| 34 - PPL$READ_SEMAPHORE |
The Read Semaphore Values routine returns the current or maximum
values, or both, of the specified counting semaphore. The
semaphore must have been created by PPL$CREATE_SEMAPHORE.
Format
PPL$READ_SEMAPHORE semaphore-id [,semaphore-value]
[,semaphore-maximum]
34.1 - Arguments
semaphore-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the specified semaphore. The semaphore-id argument
is the address of an unsigned longword containing the identifier.
Semaphore-id is returned by PPL$CREATE_SEMAPHORE.
semaphore-value
OpenVMS usage word_signed
type word (signed)
access write only
mechanism by reference
Receives information about the specified semaphore. The optional
semaphore-value argument is the address of a signed word
containing the current value of the semaphore or the number of
blocked processes. If positive, semaphore-value contains the
number of available resources associated with this semaphore;
if negative, it contains the number of waiting processes. If the
value returned is zero, there are no available resources and no
waiting processes.
semaphore-maximum
OpenVMS usage word_signed
type word (signed)
access write only
mechanism by reference
Maximum value of the semaphore. The semaphore-maximum argument is
the address of a signed word containing the maximum value of the
semaphore specified by semaphore-id.
| 35 - PPL$READ_SPIN_LOCK |
The Read a Spin Lock State routine returns the current state of a
spin lock. The state can be seized or not_seized.
Format
PPL$READ_SPIN_LOCK lock-id ,seized
35.1 - Arguments
lock-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the specified spin lock. The lock-id argument is
the address of an unsigned longword containing the identifier.
seized
OpenVMS usage longword_unsigned
type longword (unsigned)
access write only
mechanism by reference
Receives the state of the specified spin lock. The seized
argument is the address of an unsigned longword that receives
the spin lock state. This argument returns a value of true if the
current state of the spin lock is seized, and it returns a value
of false if the current state of the spin lock is not_seized.
| 36 - PPL$READ_WORK_QUEUE |
The Read a Work Queue routine returns information about a work
queue.
Format
PPL$READ_WORK_QUEUE queue-id [,queue-value]
36.1 - Arguments
queue-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
The queue identifier. The queue-id argument is the address of an
unsigned longword containing the identifier.
queue-value
OpenVMS usage longword_signed
type longword (signed)
access write only
mechanism by reference
Receives information about the specified work queue. If positive,
queue-value contains the number of items currently in the work
queue; if negative, it contains the number of processes currently
blocked (waiting for an item to be placed in the queue). If the
value returned is zero, there are no work items in the queue and
no blocked processes. The optional queue-value argument is the
address of a signed longword that receives the number of work
items or blocked processes.
| 37 - PPL$RELEASE_SPIN_LOCK |
The Release Spin Lock routine relinquishes the spin lock by
clearing the bit representing the lock. The lock must have been
created by PPL$CREATE_SPIN_LOCK.
Format
PPL$RELEASE_SPIN_LOCK lock-id
37.1 - Arguments
lock-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the specified lock. The lock-id argument is the
address of an unsigned longword containing the lock identifier.
Lock-id is returned by PPL$CREATE_SPIN_LOCK.
| 38 - PPL$REMOVE_WORK_ITEM |
The Remove a Work Queue Item routine removes the next item in
order from a work queue.
Format
PPL$REMOVE_WORK_ITEM queue-id ,work-item [,flags] [,spin]
38.1 - Arguments
queue-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
The queue identifier. The queue-id argument is the address of an
unsigned longword containing the identifier.
work-item
OpenVMS usage user_arg
type longword (unsigned)
access write only
mechanism by reference
Receives the value of the item that is removed from the work
queue. The work-item argument is the address of an unsigned
longword that receives the value of the item that is removed
from the work queue.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Specifies options for removing an item from the work queue. The
optional flags argument is the address of a longword bit mask
containing the flag. Valid values are as follows:
PPL$M_NON_ If the specified work queue is empty, return
BLOCKING immediately with the PPL$_NOT_AVAILABLE status
indicating that no items are available to be
removed from the work queue. By default, if
the work queue is empty the process hibernates
until there is an item available to be removed
from the work queue.
PPL$M_FROMTAIL Remove item from the end (or tail) of the work
queue. By default, this routine removes an
item from the beginning (or head) of the work
queue.
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 mask_longword
type longword (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.
| 39 - PPL$RESET_EVENT |
The Reset an Event routine resets an event's state to not_
occurred.
Format
PPL$RESET_EVENT event-id
39.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.
| 40 - PPL$SEIZE_SPIN_LOCK |
The Seize Spin Lock routine retrieves a simple (spin) lock by
waiting in a spin loop until the lock is free. The lock must have
been created by PPL$CREATE_SPIN_LOCK.
Format
PPL$SEIZE_SPIN_LOCK lock-id [,flags]
40.1 - Arguments
lock-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the lock to be seized. The lock-id argument is the
address of an unsigned longword containing the lock identifier.
Lock-id is returned by PPL$CREATE_SPIN_LOCK.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Bit mask specifying options for seizing the lock. The flags
argument is a longword bit mask containing the flag. The valid
value for flags is as follows:
PPL$M_NON_ The lock is seized if and only if it can
BLOCKING be done without causing the caller to wait
(spin). (This can be useful in situations
where the cost of waiting for a resource is
not desirable, or if the caller merely intends
to request immediate access to any one of a
number of resources.)
| 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.
|
|
