HELPLIB.HLB  —  RTL Routines, PPL$

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.
Close Help