OpenVMS RTL Library (LIB$) Manual

Document revision date: 19 July 1999

OpenVMS RTL Library (LIB$) Manual

Contents

Index

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 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 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 or an Alpha 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 or an Alpha 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 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 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. 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. 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. 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:

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.

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.

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 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 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.
If you are specifying one or more of the action routine arguments, be sure that the descriptor class used to pass resultant-name is the same as the descriptor class required by the action routine. For example, VAX Ada requires a class SB descriptor for string arguments to Ada routines, but will use a class A descriptor by default when calling external routines. Refer to your language manual to determine the proper descriptor class to use.
new-resultant-name

OpenVMS usage: char_string

type: character string

access: write only

mechanism: by descriptor

String into which LIB$RENAME_FILE writes the new OpenVMS RMS resultant file specification of the last file processed. The new-resultant-name argument is the address of a descriptor pointing to the new name. This is an optional argument. If present, it is used to store the file specification passed to the user-supplied routines instead of a class S, type T string. Any string class is supported.
If you are specifying one or more of the action routine arguments, be sure that the descriptor class used to pass resultant-name is the same as the descriptor class required by the action routine. For example, VAX Ada requires a class SB descriptor for string arguments to Ada routines, but will use a class A descriptor by default when calling external routines. Refer to your language manual to determine the proper descriptor class to use.
file-scan-context

OpenVMS usage: context

type: longword (unsigned)

access: modify

mechanism: by reference

Context for renaming a list of file specifications. The file-scan-context is the address of a longword that contains this context. You must initialize this longword to zero before the first of a series of calls to LIB$RENAME_FILE. LIB$RENAME_FILE uses the file scan context to retain the file context for multiple input files.
LIB$FILE_SCAN uses this context to retain multiple input file related file context. This is an optional argument; it need only be specified if you are using multiple input files, as the DCL command RENAME does. You may deallocate the context allocated by LIB$FILE_SCAN while processing the LIB$RENAME_FILE requests by calling LIB$FILE_SCAN_END after all calls to LIB$RENAME_FILE have been completed. See the description of LIB$FILE_SCAN for a more detailed description of this argument.

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

Description

This description is divided into three parts:

Call Format for a Success Routine
Call Format for an Error Routine
Call Format for a Confirm Routine

Call Format for a Success Routine

The success routine is optional; it is called only if the user-success-procedure argument is specified in the call to LIB$RENAME_FILE.
The calling format of a success routine is as follows:
user-success-procedure old-filespec ,new-filespec [,user-specified-argument]
old-filespec

OpenVMS usage: char_string

type: character string

access: read only

mechanism: descriptor

RMS resultant file specification of the file before it was renamed. If old-resultant-name was specified, it is used to pass the string to the success routine. Otherwise, a class S, type T string is passed. Any string class is supported.
new-filespec

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

RMS resultant file specification of the newly renamed file. If new-resultant-name was specified, it is used to pass the string to the success routine. Otherwise, a class S, type T string is passed. Any string class is supported.
user-specified-argument

OpenVMS usage: user_arg

type: longword (unsigned)

access: read only

mechanism: unspecified

Value of user-specified-argument passed by LIB$RENAME_FILE to the success routine using the same passing mechanism that was used to pass it to LIB$RENAME_FILE.

Call Format for an Error Routine

The error routine returns a success/fail value that LIB$RENAME_FILE uses to determine whether or not more files will be processed if an error is encountered. The error routine is called only if the user-error-procedure argument was specified in the call to LIB$RENAME_FILE. If the user-error-procedure argument was not specified, the default is to continue processing.
The calling format of the error routine is as follows:
user-error-procedure old-filespec ,new-filespec ,rms-sts ,rms-stv ,error-source ,user-specified-argument
old-filespec

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

RMS resultant file specification of the file being renamed when the error occurred. If old-resultant-name was specified, it is used to pass the string to the error routine. Otherwise, a class S, type T string is passed. Any string class is supported.
new-filespec

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

RMS resultant file specification of the new file name being used when the error occurred. If new-resultant-name was specified, it is used to pass the string to the error routine. Otherwise, a class S, type T string is passed. Any string class is supported.
rms-sts

OpenVMS usage: cond_value

type: longword (unsigned)

access: read only

mechanism: by reference

Primary condition code (FAB$L_STS) which describes the error that occurred. The rms-sts argument is the address of an unsigned longword that contains this primary condition code.
rms-stv

OpenVMS usage: cond_value

type: longword (unsigned)

access: read only

mechanism: by reference

Secondary condition code (FAB$L_STV) which describes the error that occurred. The rms-stv argument is the address of an unsigned longword that contains this secondary condition code.
error-source

OpenVMS usage: longword_signed

type: longword integer (signed)

access: read only

mechanism: by reference

Integer code indicating where the error was found. The error-source argument is the address of a longword containing the error source.

Previous Next Contents Index

privacy and legal statement

5932PRO_034.HTML

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

OpenVMS usage:	quadword_signed
type:	quadword integer (signed)
access:	modify
mechanism:	by reference

OpenVMS usage:	address
type:	longword (unsigned)
access:	write only
mechanism:	by reference

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

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.

OpenVMS usage:	octaword_signed
type:	octaword integer (signed)
access:	modify
mechanism:	by reference

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	procedure
type:	procedure value
access:	function call (before return)
mechanism:	by value

OpenVMS usage:	user_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	context
type:	longword (unsigned)
access:	modify
mechanism:	by reference

OpenVMS usage:	longword_signed
type:	longword integer (signed)
access:	read only
mechanism:	by reference