OpenVMS RTL Library (LIB$) Manual

Updated: 11 December 1998

OpenVMS RTL Library (LIB$) Manual

Contents

Index

LIB$INSQTI

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.

Format

LIB$INSQTI entry ,header [,retry-count]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

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

Description

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

LIB$INSQTIQ (Alpha Only)

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.

Format

LIB$INSQTIQ entry ,header [,retry-count]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

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.

Description

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

LIB$INSV

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 systems, OpenVMS Alpha instructions perform the equivalent operation.

Format

LIB$INSV longword-integer-source ,position ,size ,base-address

RETURNS

None.

Arguments

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.

Condition Value Signaled

SS$_ROPRAND A reserved operand fault is signaled if a size greater than 32 is specified.

Examples

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

LIB$INT_OVER

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 systems in translated form and is applicable to translated VAX images only.

Format

LIB$INT_OVER new-setting

RETURNS

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

Argument

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.

Description

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.

Condition Values Returned

None.

Example


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;

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

LIB$LEN

The Length of String Returned as Longword Value routine returns the length of a string.

Format

LIB$LEN source-string

RETURNS

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.

Argument

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.

Description

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.

Condition Values Returned

None.

LIB$LOCC

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 systems, OpenVMS Alpha instructions perform the equivalent operation.

Format

LIB$LOCC character-string ,source-string

RETURNS

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.

Arguments

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.

Description

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.

Condition Values Returned

None.

Examples

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

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

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

Contents

Index

Legal

 
5932PRO_028.HTML

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

OpenVMS usage:	unspecified
type:	unspecified
access:	modify
mechanism:	by reference, array reference

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

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

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.

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

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

OpenVMS usage:	byte_unsigned
type:	byte (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	address
type:	address
access:	read only
mechanism:	by value

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by value

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