Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

Previous | 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;

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

> 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

| privacy and legal statement |
5932PRO_029.HTML