|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
The Insert Entry at Tail of Queue routine inserts a queue entry at the tail of the specified self-relative longword interlocked queue. LIB$INSQTI makes the INSQTI 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.
LIB$INSQTI entry ,header [,retry-count]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
entry
OpenVMS usage: unspecified type: unspecified access: modify mechanism: by reference, array reference
Entry to be inserted at the tail of the queue by LIB$INSQTI. The entry argument contains the address of this signed quadword-aligned array that must be at least 8 bytes long. Bytes following the first 8 bytes can be used for any purpose by the calling program.For Alpha and I64 systems, the entry argument must contain a 32-bit sign-extended address. An illegal operand exception occurs for any other form of address.
header
OpenVMS usage: quadword_signed type: quadword integer (signed) access: modify mechanism: by reference
Queue header specifying the queue into which the queue entry is to be inserted. 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.For 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.
retry-count
OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by reference
The number of times the insertion 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 which contains the retry count value. The default value is 10.
The queue into which LIB$INSQTI inserts an entry can be in process-private, processor-private, or processor-shareable memory to implement per-process, per-processor, or across-processor 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.
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.
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.
SS$_NORMAL Routine successfully completed. The entry was added to the tail of the queue: the resulting queue contains more than one entry. 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 added to the tail of the queue: the resulting queue contains one entry. 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.
The Insert Entry at Tail of Queue routine inserts a queue entry at the tail of the specified self-relative quadword interlocked queue. LIB$INSQTIQ makes the INSQTIQ instruction available as a callable routine.
LIB$INSQTIQ entry ,header [,retry-count]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
entry
OpenVMS usage: unspecified type: unspecified access: modify mechanism: by reference, array reference
Entry to be inserted at the tail of the queue by LIB$INSQTIQ. The entry argument contains the address of this signed octaword-aligned array that must be at least 16 bytes long. Bytes following the first 16 bytes can be used for any purpose by the calling program.header
OpenVMS usage: octaword_signed type: octaword integer (signed) access: modify mechanism: by reference
Queue header specifying the queue into which the queue entry is to be inserted. 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.retry-count
OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by reference
The number of times the insertion 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. The default value is 10.
The queue into which LIB$INSQTIQ inserts an entry can be in process-private, processor-private, or processor-shareable memory to implement per-process, per-processor, or across-processor 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.
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.
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.
SS$_NORMAL Routine successfully completed. The entry was added to the tail of the queue: the resulting queue contains more than one entry. 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 added to the tail of the queue: the resulting queue contains one entry. 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.
The Insert a Variable Bit Field routine replaces the variable bit field specified by the base, position, and size arguments with bits 0 through (size---1) of the source field. If the size of the bit field is zero, nothing is inserted. LIB$INSV makes the VAX INSV instruction available as a callable routine.
Note
On Alpha and I64 systems, OpenVMS Alpha and I64 instructions perform the equivalent operation.
LIB$INSV longword-integer-source ,position ,size ,base-address
None.
longword-integer-source
OpenVMS usage: longword_signed type: longword integer (signed) access: read only mechanism: by reference
Source field to be inserted by LIB$INSV. The longword-integer-source argument is the address of a signed longword integer that contains this source field.position
OpenVMS usage: longword_signed type: longword integer (signed) access: read only mechanism: by reference
Bit position relative to the base address where insertion of longword-integer-source is to begin. The position argument is the address of a longword integer that contains this relative bit position.size
OpenVMS usage: byte_unsigned type: byte (unsigned) access: read only mechanism: by reference
Size of the bit field to be inserted by LIB$INSV. The size argument is the address of an unsigned byte that contains the size of this bit field. The maximum size is 32 bits.
base-address
OpenVMS usage: address type: address access: read only mechanism: by value
Field into which LIB$INSV writes the source field. The base-address argument is an unsigned longword containing the base address of this aligned bit string.
SS$_ROPRAND A reserved operand fault is signaled if a size greater than 32 is specified.
| #1 |
|---|
INTEGER*4 COND_VALUE
CALL LIB$INSV (4, 0, 3, COND_VALUE)
|
This example shows how to set bits 0 through 2 of longword COND_VALUE to the value 4 in Fortran.
| #2 |
|---|
DECLARE INTEGER COND_VALUE
CALL LIB$INSV (4%, 0%, 3%, COND_VALUE)
|
This example uses BASIC to set bits 0 through 2 of longword COND_VALUE to the value 4.
The Integer Overflow Detection routine enables or disables integer overflow detection for the calling routine activation. The previous integer overflow enable setting is returned.
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.
This routine is available on OpenVMS Alpha and I64 systems in translated form and is applicable to translated VAX images only.
LIB$INT_OVER new-setting
OpenVMS usage: longword_unsigned type: longword (unsigned) access: write only mechanism: by value
Old integer overflow enable setting (the previous contents of SF$W_PSW[PSW$V_IV] in the caller's frame).
new-setting
OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by reference
New integer overflow enable setting. The new-setting argument is the address of an unsigned longword that contains the new integer overflow enable setting. Bit 0 set to 1 means enable, bit 0 set to 0 means disable.
The caller's stack frame will be modified by this routine.LIB$INT_OVER affects only the current routine activation and does not affect any of its callers or any routines that it may call. However, the setting remains in effect for any routines which are subsequently entered through a JSB entry point.
None.
INTOVF: ROUTINE OPTIONS (MAIN);
DECLARE LIB$INT_OVER ENTRY (FIXED BINARY (7)) /* Address of byte for
/* enable/disable
/* setting */
RETURNS (FIXED BINARY (31)); /* Old setting */
DECLARE DISABLE FIXED BINARY (7) INITIAL (0) STATIC READONLY;
DECLARE (A,B) FIXED BINARY (7);
ON FIXEDOVERFLOW PUT SKIP LIST ('Overflow');
A = 127;
B = A + 2;
PUT LIST ('In MAIN');
BEGIN;
DECLARE RESULT FIXED BINARY (31);
/* Disable recognition of integer overflow in this block */
RESULT = LIB$INT_OVER (DISABLE);
B = A + 2;
PUT SKIP LIST ('In BEGIN block');
CALL Q;
Q: routine;
B = A + 2;
PUT LIST ('In Q');
END Q;
END /* Begin */;
END INTOVF;
|
This PL/I routine shows how to use LIB$INT_OVER to enable or disable the detection of integer overflow. Note that in PL/I, integer overflow is always enabled unless explicitly overridden by a call to this routine. However, disabling integer overflow is only effective for the block which calls this routine; descendent blocks are unaffected. The output generated by this PL/I program is as follows:
In MAIN In BEGIN block Overflow In Q
The Length of String Returned as Longword Value routine returns the length of a string.
LIB$LEN source-string
OpenVMS usage: word_unsigned type: word (unsigned) access: write only mechanism: by value
Length of the source string, extracted and zero-extended to 32 bits.
source-string
OpenVMS usage: char_string type: character string access: read only mechanism: by descriptor
Source string whose length is returned by LIB$LEN. The source-string argument contains the address of a descriptor pointing to this source string.
The BASIC and Fortran intrinsic function LEN generates equivalent in-line code at run time. Therefore, it is more efficient for BASIC and Fortran users to use the intrinsic function LEN than to call LIB$LEN.If you need both the length of the string and the address of its first byte, you should use LIB$ANALYZE_SDESC or LIB$ANALYZE_SDESC_64.
None.
The Locate a Character routine locates a character in a string by comparing successive bytes in the string with the character specified. The search continues until the character is found or the string has no more characters. LIB$LOCC makes the VAX LOCC instruction available as a callable routine.
Note
On Alpha and I64 systems, OpenVMS Alpha and I64 instructions perform the equivalent operation.
LIB$LOCC character-string ,source-string
OpenVMS usage: longword_unsigned type: longword (unsigned) access: write only mechanism: by value
The relative position from the start of source-string to the first equal character or zero if no match is found.
character-string
OpenVMS usage: char_string type: character string access: read only mechanism: by descriptor
String whose initial character is used by LIB$LOCC in the search. The character-string argument contains the address of a descriptor pointing to this string. Only the first character of character-string is used, and its length is not checked.source-string
OpenVMS usage: char_string type: character string access: read only mechanism: by descriptor
String to be searched by LIB$LOCC. The source-string argument is the address of a descriptor pointing to this character string.
LIB$LOCC returns the position of the first equal character relative to the start of the source string as an index. An index is the relative position of the first occurrence of a substring in the source string. If no character matches or if the string has a length of zero, then a zero is returned, indicating that the character was not found.
None.
| #1 |
|---|
IDENTIFICATION DIVISION.
PROGRAM-ID. LIBLOC.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 SEARCH-STRING PIC X(26)
VALUE "ABCDEFGHIJKLMNOPQRSTUVWXYZ".
01 SEARCH-CHAR PIC X.
01 IND-POS PIC 9(9) USAGE IS COMP.
01 DISP-IND PIC 9(9).
ROUTINE DIVISION.
001-MAIN.
MOVE SPACE TO SEARCH-CHAR.
DISPLAY " ".
DISPLAY "ENTER SEARCH CHARACTER: " WITH NO ADVANCING.
ACCEPT SEARCH-CHAR.
CALL "LIB$LOCC"
USING BY DESCRIPTOR SEARCH-CHAR, SEARCH-STRING
GIVING IND-POS.
IF IND-POS = ZERO
DISPLAY
"CHAR ENTERED (" SEARCH-CHAR ") NOT A VALID SEARCH CHAR"
STOP RUN.
MOVE IND-POS TO DISP-IND.
DISPLAY
"SEARCH CHAR (" SEARCH-CHAR ") WAS FOUND IN POSITION "
DISP-IND.
GO TO 001-MAIN.
|
This COBOL program accepts a character as input and returns as output the character's position in a search string. The output generated by this COBOL program is as follows:
$ RUN LIBLOC ENTER SEARCH CHARACTER: X SEARCH CHAR (X) WAS FOUND IN POSITION 000000024 ENTER SEARCH CHARACTER: Y SEARCH CHAR (Y) WAS FOUND IN POSITION 000000025 ENTER SEARCH CHARACTER: B SEARCH CHAR (B) WAS FOUND IN POSITION 000000002 ENTER SEARCH CHARACTER: b CHAR ENTERED (b) NOT A VALID SEARCH CHAR $Notice that uppercase and lowercase letters are not considered equal.
| #2 |
|---|
10 !+
! This is an BASIC program demonstrating the
! use of LIB$LOCC.
!-
EXTERNAL INTEGER FUNCTION LIB$LOCC
I% = 0
CHARSTR$ = 'DAY'
SRCSTR$ = 'ONE DAY AT A TIME'
I% = LIB$LOCC(CHARSTR$, SRCSTR$)
PRINT I%
90 END
|
This BASIC example also shows the use of LIB$LOCC. The output generated by this BASIC program is "5".
| Previous | Next | Contents | Index |