 |
HP OpenVMS RTL Library (LIB$) Manual
LIB$REMQHIQ (Alpha and I64 Only)
The Remove Entry from Head of Queue routine removes an entry from the
head of the specified self-relative quadword interlocked queue.
LIB$REMQHIQ makes the REMQHIQ instruction available as a callable
routine.
Format
LIB$REMQHIQ header ,remque-address [,retry-count]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
header
| OpenVMS usage: |
octaword_signed |
| type: |
octaword integer (signed) |
| access: |
modify |
| mechanism: |
by reference |
Queue header specifying the queue from which entry
will be removed. The header argument contains the
address of this signed aligned octaword integer. The
header argument must be initialized to zero before
first use of the queue; zero means an empty queue.
remque-address
| OpenVMS usage: |
address |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Address of the removed entry. The remque-address
argument is the address of an unsigned quadword that contains this
address. If the queue was empty, remque-address is set
to the address of the header.
retry-count
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
The number of times the operation is to be retried in case of
secondary-interlock failure of the queue instruction in a
processor-shared memory application. The retry-count
argument is the address of a longword that contains the retry count
value. A value of 1 causes no retries. The default value is 10.
Description
The queue from which LIB$REMQHIQ removes an entry can be in
process-private, processor-private, or processor-shareable memory to
implement per-process, per-processor, or across-processor queues.
Self-Relative Queues
A queue is a doubly linked list. A Run-Time Library routine specifies a
queue entry by its address.
A self-relative queue is a queue in which the links between entries are
the displacements of the current entry's predecessor and successor. If
these links are quadwords, the queue is referred to as a self-relative
quadword queue.
You can use the LIB$INSQHIQ, LIB$INSQTIQ, LIB$REMQHIQ, and LIB$REMQTIQ
routines to manage your self-relative quadword queue on an Alpha or I64
system. These routines implement the INSQHIQ, INSQTIQ, REMQHIQ, and
REMQTIQ instructions that allow you to insert and remove an entry at
the head or tail of a self-relative quadword queue.
Synchronization
When you insert or remove a queue entry using the self-relative queue
routines, the queue pointers are changed as an atomic operation. This
ensures that no other process can interrupt the operation to insert or
remove a queue entry of its own.
When you use these routines, cooperating processes can communicate
without further synchronization and without danger of being
interrupted, either on a single processor or in a multiprocessor
environment. The queue access routines are also useful in an AST
environment; they allow you to add or remove an entry from a queue
without being interrupted by an AST.
If you do not use the self-relative queue routines to insert or remove
a queue entry, you must ensure that the operation cannot be interrupted.
Alignment
Use of the self-relative quadword queue routines requires that the
queue header and each of the queue entries be octaword aligned. You can
use the Run-Time Library routine LIB$GET_VM_64 to allocate
octaword-aligned virtual memory for a queue.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed. The entry was removed from the head of
the queue, and the resulting queue contains one or more entries.
|
|
SS$_ROPRAND
|
Reserved operand fault. Either the entry or the header is at an address
that is not octaword aligned, or the header address equals the entry
address.
|
|
LIB$_ONEENTQUE
|
Routine successfully completed. The entry was removed from the head of
the queue, and the resulting queue is empty.
|
|
LIB$_QUEWASEMP
|
The queue was empty. The queue is not modified.
|
|
LIB$_SECINTFAI
|
A secondary interlock failure occurred; the insertion was attempted the
number of times specified by
retry-count. This is a severe error. The queue is not
modified. This condition can occur only when the queue is in memory
being shared between two or more processors.
|
LIB$REMQTI
The Remove Entry from Tail of Queue routine removes an entry from the
tail of the specified self-relative longword interlocked queue.
LIB$REMQTI makes the REMQTI instruction available as a callable routine.
Note
No support for arguments passed by 64-bit address reference or for use
of 64-bit descriptors, if applicable, is planned for this routine.
|
Format
LIB$REMQTI header ,remque-address [,retry-count]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
header
| OpenVMS usage: |
quadword_signed |
| type: |
quadword integer (signed) |
| access: |
modify |
| mechanism: |
by reference |
Queue header specifying the queue from which the entry is to be
deleted. The header argument contains the address of
this signed aligned quadword integer. The header
argument must be initialized to zero before first use of the queue;
zero means an empty queue.
On Alpha and I64 systems, the header argument must
contain a 32-bit sign-extended address. An illegal operand exception
occurs for any other form of address.
remque-address
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Address of the removed entry. The remque-address
argument is the address of a longword that contains this address. If
the queue was empty, remque-address is set to the
address of the header.
On Alpha and I64 systems, the remque-address argument
must contain a 32-bit sign-extended address. An illegal operand
exception occurs for any other form of address.
retry-count
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
The number of times the operation is to be retried in case of
secondary-interlock failure of the queue instruction in a
processor-shared memory application. The retry-count
argument is the address of a longword that is this retry count value. A
value of 1 causes no retries. The default value is 10.
Description
The queue from which LIB$REMQTI removes an in process-private,
processor-private, or processor-shareable memory to implement
per-process, per-processor, or across-processor queues.
Self-Relative Queues
A queue is a doubly linked list. A Run-Time Library routine specifies a
queue entry by its address.
A self-relative queue is a queue in which the links between entries are
the displacements of the current entry's predecessor and successor. If
these links are longwords, the queue is referred to as a self-relative
longword queue.
You can use the LIB$INSQHI, LIB$INSQTI, LIB$REMQHI, and LIB$REMQTI
routines to manage your self-relative longword queue on a VAX, Alpha,
or I64 system. These routines implement the INSQHI, INSQTI, REMQHI, and
REMQTI instructions that allow you to insert and remove an entry at the
head or tail of a self-relative longword queue.
Synchronization
When you insert or remove a queue entry using the self-relative queue
routines, the queue pointers are changed as an atomic operation. This
ensures that no other process can interrupt the operation to insert or
remove a queue entry of its own.
When you use these routines, cooperating processes can communicate
without further synchronization and without danger of being
interrupted, either on a single processor or in a multiprocessor
environment. The queue access routines are also useful in an AST
environment; they allow you to add or remove an entry from a queue
without being interrupted by an AST.
If you do not use the self-relative queue routines to insert or remove
a queue entry, you must ensure that the operation cannot be interrupted.
Alignment
Use of the self-relative longword queue routines requires that the
queue header and each of the queue entries be quadword aligned. You can
use the Run-Time Library routine LIB$GET_VM on a VAX, Alpha, or I64
system to allocate quadword-aligned virtual memory for a queue.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed. The entry was removed from the queue
tail, and the resulting queue contains one or more entries.
|
|
SS$_ROPRAND
|
Reserved operand fault. Either the entry or the header is at an address
that is not quadword aligned, or the header address equals the entry
address.
|
|
LIB$_ONEENTQUE
|
Routine successfully completed. The entry was removed from the queue
tail, and the resulting queue is empty.
|
|
LIB$_QUEWASEMP
|
Queue was empty. The queue is not modified.
|
|
LIB$_SECINTFAI
|
A secondary interlock failure occurred; the insertion was attempted the
number of times specified by
retry-count. This is a severe error. The queue is not
modified. This condition can occur only when the queue is in memory
being shared between two or more processors.
|
LIB$REMQTIQ (Alpha and I64 Only)
The Remove Entry from Tail of Queue routine removes an entry from the
tail of the specified self-relative quadword interlocked queue.
LIB$REMQTIQ makes the REMQTIQ instruction available as a callable
routine.
Format
LIB$REMQTIQ header ,remque-address [,retry-count]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
header
| OpenVMS usage: |
octaword_signed |
| type: |
octaword integer (signed) |
| access: |
modify |
| mechanism: |
by reference |
Queue header specifying the queue from which the entry is to be
deleted. The header argument contains the address of
this signed aligned octaword integer. The header
argument must be initialized to zero before first use of the queue;
zero means an empty queue.
remque-address
| OpenVMS usage: |
address |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Address of the removed entry. The remque-address
argument is the address of a quadword that contains this address. If
the queue was empty, remque-address is set to the
address of the header.
retry-count
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
The number of times the operation is to be retried in case of
secondary-interlock failure of the queue instruction in a
processor-shared memory application. The retry-count
argument is the address of a longword that is this retry count value. A
value of 1 causes no retries. The default value is 10.
Description
The queue from which LIB$REMQTIQ removes an entry can be in
process-private, processor-private, or processor-shareable memory to
implement per-process, per-processor, or across-processor queues.
Self-Relative Queues
A queue is a doubly linked list. A Run-Time Library routine specifies a
queue entry by its address.
A self-relative queue is a queue in which the links between entries are
the displacements of the current entry's predecessor and successor. If
these links are quadwords, the queue is referred to as a self-relative
quadword queue.
You can use the LIB$INSQHIQ, LIB$INSQTIQ, LIB$REMQHIQ, and LIB$REMQTIQ
routines to manage your self-relative quadword queue on an Alpha or I64
system. These routines implement the INSQHIQ, INSQTIQ, REMQHIQ, and
REMQTIQ instructions that allow you to insert and remove an entry at
the head or tail of a self-relative quadword queue.
Synchronization
When you insert or remove a queue entry using the self-relative queue
routines, the queue pointers are changed as an atomic operation. This
ensures that no other process can interrupt the operation to insert or
remove a queue entry of its own.
When you use these routines, cooperating processes can communicate
without further synchronization and without danger of being
interrupted, either on a single processor or in a multiprocessor
environment. The queue access routines are also useful in an AST
environment; they allow you to add or remove an entry from a queue
without being interrupted by an AST.
If you do not use the self-relative queue routines to insert or remove
a queue entry, you must ensure that the operation cannot be interrupted.
Alignment
Use of the self-relative quadword queue routines requires that the
queue header and each of the queue entries be octaword aligned. You can
use the Run-Time Library routine LIB$GET_VM_64 to allocate
octaword-aligned virtual memory for a queue.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed. The entry was removed from the queue
tail, and the resulting queue contains one or more entries.
|
|
SS$_ROPRAND
|
Reserved operand fault. Either the entry or the header is at an address
that is not octaword aligned, or the header address equals the entry
address.
|
|
LIB$_ONEENTQUE
|
Routine successfully completed. The entry was removed from the queue
tail, and the resulting queue is empty.
|
|
LIB$_QUEWASEMP
|
Queue was empty. The queue is not modified.
|
|
LIB$_SECINTFAI
|
A secondary interlock failure occurred; the insertion was attempted the
number of times specified by
retry-count. This is a severe error. The queue is not
modified. This condition can occur only when the queue is in memory
being shared between two or more processors.
|
LIB$RENAME_FILE
The Rename One or More Files routine changes the names of one or more
files. The specification of the files to be renamed can include
wildcards.
LIB$RENAME_FILE is similar in function to the DCL command RENAME.
Format
LIB$RENAME_FILE old-filespec ,new-filespec [,default-filespec]
[,related-filespec] [,flags] [,user-success-procedure]
[,user-error-procedure] [,user-confirm-procedure]
[,user-specified-argument] [,old-resultant-name] [,new-resultant-name]
[,file-scan-context]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
old-filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
File specification of the files to be renamed. The
old-filespec argument is the address of a descriptor
pointing to the old file specification. The specification may include
wildcards, in which case each file that matches the specification will
be renamed. If running on Alpha or I64 and flag LIB$M_FIL_LONG_NAMES is
set, the string must not contain more characters than specified by
NAML$C_MAXRSS, otherwise the string must not contain more than 255
characters. Any string class is supported.
new-filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
File specification for the new file names. The
new-filespec argument is the address of a descriptor
pointing to the new file specification.
This specification need not be complete; fields omitted or specified by
using the wildcard character (*) will be filled in from the existing
file's name using the same rules as for the DCL command RENAME. If
running on Alpha or I64 and flag LIB$M_FIL_LONG_NAMES is set, the
string must not contain more characters than specified by
NAML$C_MAXRSS, otherwise the string must not contain more than 255
characters. Any string class is supported.
default-filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Default file specification of the files to be renamed. The
default-filespec argument is the address of a
descriptor pointing to the default file specification.
This is an optional argument; if omitted, the default is the null
string. See the OpenVMS Record Management Services Reference Manual for information on default file
specifications. If running on Alpha or I64 and flag
LIB$M_FIL_LONG_NAMES is set, the string must not contain more
characters than specified by NAML$C_MAXRSS, otherwise the string must
not contain more than 255 characters. Any string class is supported.
related-filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Related file specification of the files to be renamed. The
related-filespec argument is the address of a
descriptor pointing to the related file specification. This is an
optional argument; if omitted, the default is the null string. Any
string class is supported.
Input file parsing is used. (See the OpenVMS Record Management Services Reference Manual for information on
related file specifications and input file parsing.)
The related file specification is useful when you are processing lists
of file specifications. Unspecified portions of the file specification
are inherited from the last file processed. Any string class is
supported. This is an optional argument.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Longword of flag bits designating optional behavior. The
flags argument is the address of an unsigned longword
containing the flag bits. This is an optional argument; if omitted, the
default is that all flags are clear.
The bit number and its meaning are as follows:
If a file already exists with the same file name, type and version
number, the error RMS$_FEX is given. This flag is equivalent to the
/NONEW_VERSION qualifier of the DCL command RENAME.)
| Bit |
Symbol |
Description |
|
0
|
LIB$M_FIL_CUR_VER
|
If
new-filespec does not specify a version number, this
flag controls whether a new version number for the output file is to be
assigned. If this bit is set, the current version number of the file is
used.
If this bit is clear, the file is given a version number 1 higher
than any previously existing file of the same file name and file type.
This is the default action.
|
|
1
|
LIB$M_FIL_INH_SECUR
|
Controls whether the renamed file takes on security attributes of the
new location or keeps its existing security attributes. If this bit is
clear, the attributes of the renamed file are inherited from the next
lower version of the new file name, if any, the new parent directory,
or both.
If this bit is clear, the file's security attributes are not
changed; this is the default action.
For more information on file security, see the HP OpenVMS Guide to System Security. This
flag is equivalent to the /INHERIT_SECURITY qualifier of the DCL
command RENAME.
|
|
2
|
LIB$M_FIL_LONG_NAMES
|
(Alpha and I64 only) Controls whether to accept file specifications
greater than 255 characters in length. If this bit is set,
LIB$RENAME_FILE can process files specifications with a maximum length
of NAML$C_MAXRSS characters.
If this bit is clear, LIB$RENAME_FILE can process files names with
a maximum length of 255 characters.
|
user-success-procedure
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
User-supplied success routine that LIB$RENAME_FILE calls after each
successful rename.
For further information on the success routine, see Call Format for a Success Routine in
the Description section.
user-error-procedure
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
User-supplied error routine that LIB$RENAME_FILE calls when it detects
an error. The value returned by the error routine determines whether
LIB$RENAME_FILE processes more files. For further information on the
error routine, see Call Format for an Error Routine in the Description section.
user-confirm-procedure
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
User-supplied confirm routine that LIB$RENAME_FILE calls before it
renames a file. The value returned by the confirm routine determines
whether or not LIB$RENAME_FILE renames the file.
The confirm routine can be used to select specific files for renaming
based on criteria such as expiration date, size, and so on.
For further information on the confirm routine, see Call Format for a Confirm Routine in
the Description section.
user-specified-argument
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Value that LIB$RENAME_FILE passes to the success, error, and confirm
routines each time they are called. Whatever mechanism is used to pass
user-specified-argument to LIB$RENAME_FILE is also
used to pass it to the user-supplied routines. This is an optional
argument; if omitted, zero is passed by value.
old-resultant-name
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
String into which LIB$RENAME_FILE copies the old resultant file
specification of the last file processed. This is an optional argument.
If present, it is used to store the file specification passed to the
user-supplied routines instead of a default class S, type T string. Any
string class is supported.
|
