Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

Previous | Contents | Index

## LIB$EXTV

> The Extract a Field and Sign-Extend routine returns a sign-extended longword field that has been extracted from the specified variable bit field. LIB$EXTV makes the VAX EXTV instruction available as a callable routine.

> Note On Alpha systems, OpenVMS Alpha instructions perform the equivalent operation.

### Format

> LIB$EXTV position ,size ,base-address

### RETURNS

> OpenVMS usage: | longword_signed
> type: | longword integer (signed)
> access: | write only
> mechanism: | by value

> Field extracted by LIB$EXTV, sign-extended to a longword.

### Arguments

> #### position

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

> Position (relative to the base address) of the first bit in the field that LIB$EXTV extracts. The position argument is the address of a signed longword integer containing the position.

> #### size

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

> Size of the bit field LIB$EXTV extracts. The size argument is the address of an unsigned byte containing the size. The maximum size is 32 bits.

> #### base-address

> OpenVMS usage: | longword_unsigned
> type: | longword (unsigned)
> access: | read only
> mechanism: | by value

> Base address of the bit field LIB$EXTV extracts from the specified variable bit field. The base-address argument is an unsigned longword containing the base address.

### Description

> The variable-length bit field is an OpenVMS data type used to store small integers packed together in a larger data structure. It is often used to store single flag bits.

> Three scalar attributes define a variable bit field:

> - The base address is the address of a byte in memory that serves as a reference point for locating the bit field.
> - The bit position is a signed longword containing the displacement of the least significant bit of the field with respect to bit 0 of the base address.
> - The size is a byte integer indicating the size of the bit field in bits (in the range 0 <= size <= 32). That is, a bit field can be no more than one longword in length.

> A variable-length bit field has the following format. The area containing asterisks indicates the field.

Bit fields are zero-origin, which means that the routine regards the first bit in the field as being the zero position.

### Condition Value Signaled

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

### Example

    SIGN_EXTEND: ROUTINE OPTIONS (MAIN);

    DECLARE LIB$EXTV ENTRY
            (FIXED BINARY (31),     /* Address of longword containing
                                    /*   beginning bit position             */
             FIXED BINARY (7),      /* Address of byte containing size
                                    /*   of field                           */
             FIXED BINARY (31))     /* Address of field                     */
             RETURNS (FIXED BINARY (31));   /* Return value                 */

    DECLARE (VALUE, SMALL_INT) FIXED BINARY (31);

    ON ENDFILE (SYSIN) STOP;

    DO WHILE ('1'B);                /* Loop continuously, until end of file */
            PUT SKIP(2);
            GET LIST (VALUE) OPTIONS (PROMPT ('Value: '));
            SMALL_INT = LIB$EXTV ( 0, 4, VALUE);    /* Extract and sign-extend
                                                    /*   first 4 bits       */
            PUT SKIP LIST (VALUE, SMALL_INT);
            END;

    END SIGN_EXTEND;

> This PL/I program extracts a field and returns it sign-extended into a longword.

## LIB$EXTZV

> The Extract a Zero-Extended Field routine returns a longword zero-extended field that has been extracted from the specified variable bit field. LIB$EXTZV makes the VAX EXTZV instruction available as a callable routine.

> Note On Alpha systems, OpenVMS Alpha instructions perform the equivalent operation.

### Format

> LIB$EXTZV position ,size ,base-address

### RETURNS

> OpenVMS usage: | longword_signed
> type: | longword integer (signed)
> access: | write only
> mechanism: | by value

> Field extracted by LIB$EXTZV, zero-extended to a longword.

### Arguments

> #### position

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

> Position (relative to the base address) of the first bit in the field LIB$EXTZV extracts. The position argument is the address of a signed longword integer containing the position.

> #### size

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

> Size of the bit field LIB$EXTZV extracts. The size argument is the address of an unsigned byte containing the size. The maximum size is 32 bits.

> #### base-address

> OpenVMS usage: | longword_unsigned
> type: | longword (unsigned)
> access: | read only
> mechanism: | by value

> Base address of the bit field LIB$EXTZV extracts. The base-address argument is an unsigned longword containing the base address.

### Description

> The variable-length bit field is an OpenVMS data type used to store small integers packed together in a larger data structure. It is often used to store single flag bits.

> Three scalar attributes define a variable bit field:

> - The base address is the address of the byte in memory that serves as a reference point for locating the bit field.
> - The bit position is a signed longword containing the displacement of the least significant bit of the field with respect to bit 0 of the base address.
> - The size is a byte integer indicating the size of the bit field in bits (in the range 0 <= size <= 32). That is, a bit field can be no more than one longword in length.

> A variable-length bit field has the following format. The area containing asterisks indicates the field.

Bit fields are zero-origin fields, which means that the routine regards the first bit in the field as being the zero position.

### Condition Value Signaled

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

## LIB$FFx

> The Find First Clear or Set Bit routines search the field specified by the start position, size, and base for the first clear or set bit. LIB$FFC and LIB$FFS make the VAX FFC and VAX FFS instructions available as callable routines.

> Note On Alpha systems, OpenVMS Alpha instructions perform the equivalent operation.

### Format

> LIB$FFC position ,size ,base ,find-position

> LIB$FFS position ,size ,base ,find-position

### RETURNS

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

### Arguments

> #### position

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

> Starting position, relative to the base address, of the bit field to be searched by LIB$FFx. The position argument is the address of a signed longword integer containing the starting position.

> #### size

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

> Number of bits to be searched by LIB$FFx. The size argument is the address of an unsigned byte containing the size of the bit field to be searched. The maximum size is 32 bits.

> #### base

> OpenVMS usage: | address
> type: | longword (unsigned)
> access: | read only
> mechanism: | by reference

> The base argument is the address of the bit field that LIB$FFx searches.

> #### find-position

> OpenVMS usage: | longword_signed
> type: | longword integer (signed)
> access: | write only
> mechanism: | by reference

> Bit position of the first bit in the specified state (clear or set), relative to the base address. The find-position argument is the address of a signed longword integer into which LIB$FFC writes the position of the first clear bit and into which LIB$FFS writes the position of the first set bit.

### Description

> LIB$FFC searches the field specified by the start position, size, and base for the first clear bit. LIB$FFS searches the field for the first set bit.

> If a bit in the specified state is found, LIB$FFx writes the position (relative to the base) of that bit into find-position and returns a success status. If no bits are in the specified state or if size is zero, LIB$FFx returns LIB$_NOTFOU and sets find-position to the starting position plus the size.

> LIB$FFx regards the first bit in the field as being the zero position.

### Condition Values Returned

> SS$_NORMAL | Routine successfully completed. A bit in the specified state was found.
> LIB$_NOTFOU | A bit in the specified state was not found.

### Condition Value Signaled

> SS$_ROPRAND | Reserved operand fault. A size greater than 32 was specified.

## LIB$FID_TO_NAME

> The Convert Device and File ID to File Specification routine converts a disk device name and file identifier to a file specification.

### Format

> LIB$FID_TO_NAME device-name ,file-id ,filespec [,filespec-length] [,directory-id] [,acp-status]

### RETURNS

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

### Arguments

> #### device-name

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

> Device name to be converted. The device-name argument is the address of a descriptor pointing to the device name. It must reference a disk device, and must contain 64 characters or less. LIB$FID_TO_NAME obtains device-name from the NAM$T_DVI field of an OpenVMS RMS name block.

> #### file-id

> OpenVMS usage: | vector_word_unsigned
> type: | word (unsigned)
> access: | read only
> mechanism: | by reference, array reference

> Specifies the file identifier. The file-id argument is the address of an array of three words containing the file identification. LIB$FID_TO_NAME obtains file-id from the NAM$W_FID field of an OpenVMS RMS name block. The $FIDDEF macro defines the structure of file-id.

> #### filespec

> OpenVMS usage: | char_string
> type: | character string
> access: | write only
> mechanism: | by descriptor

> Receives the file specification. The filespec argument is the address of a descriptor pointing to the file specification string. As of OpenVMS Version 7.2, the maximum file specification string that can be returned is 4095 bytes on Alpha systems, and 510 bytes on VAX systems. On versions prior to Version 7.2, the maximum is 510 bytes on both platforms. Refer to the Description section for more information about the file specification returned.

> #### filespec-length

> OpenVMS usage: | word_unsigned
> type: | word (unsigned)
> access: | write only
> mechanism: | by reference

> Receives the number of characters written into filespec, excluding padding in the case of a fixed-length string. The optional filespec-length argument is the address of an unsigned word containing the number of characters.

> If the output string is truncated to the number of characters specified in filespec, then filespec-length is set to that truncated size. Therefore, you can always use filespec-length to access a valid substring of filespec.

> #### directory-id

> OpenVMS usage: | vector_word_unsigned
> type: | word (unsigned)
> access: | read only
> mechanism: | by reference, array reference

> Specifies a directory file identifier. The directory-id argument is the address of an array of three words containing the directory file identifier. LIB$FID_TO_NAME obtains this array from the NAM$W_DID field of an OpenVMS RMS name block. The $FIDDEF macro defines the structure of directory-id.

> This parameter is relevant only for a structure level-1 disk on OpenVMS VAX systems. This parameter is ignored on OpenVMS Alpha systems because level-1 disks are not supported on OpenVMS Alpha systems.

> #### acp-status

> OpenVMS usage: | longword_unsigned
> type: | longword (unsigned)
> access: | write only
> mechanism: | by reference

> The status resulting from traversing the backward links. The optional acp-status argument is the address of an unsigned longword containing the status.

### Description

> LIB$FID_TO_NAME converts a disk device name and file identifier to a file specification by requesting the ACP file specification attribute.

> On OpenVMS Alpha systems, if the file specification is longer than can be accommodated by the filespec buffer, a directory in the path may be replaced by a DID abbreviation (see the Guide to OpenVMS File Applications). If the file specification, even after DID abbreviation, is longer than can be accommodated by the buffer, the file specification is truncated, and LIB$STRTRU is returned as an alternate success status.

> On OpenVMS VAX systems, if you use the LIB$FID_TO_NAME routine on a structure level 1 disk, specify the directory-id argument to ensure proper operation of the routine.

> LIB$FID_TO_NAME uses the directory backpointer stored in the file header. With files in SYS$COMMON, the directory structure is duplicated because of some SET FILE/ENTERs of directory names. If directory names have been renamed or the tree structure modified (which the OpenVMS operating system does with the [SYCOMMON] tree), the file specification returned by this routine may not be useful.

> LIB$FID_TO_NAME stores the output arguments (filespec, filespec-length, and acp-status) only if the routine successfully finishes.

> Note This routine calls LIB$GET_EF. Please read the note in the Description section of that routine.

### Condition Values Returned

> LIB$_NORMAL | Routine successfully completed.
> LIB$STRTRU | Output string truncated (qualified success).
> LIB$_INVARG | Required argument omitted, or device-name is longer than 64 characters.
> LIB$_INVFILSPE | The device-name argument does not reference a disk.

Any condition value returned by RTL routine LIB$ANALYZE_SDESC, or the $ASSIGN, $QIO, or $DASSGN system services.

## LIB$FILE_SCAN

> The File Scan routine searches an area, such as a directory, for all files matching the file specification given and transfers program execution to the specified user-written routine. Wildcards are acceptable. An action routine is called for each file and/or error found. LIB$FILE_SCAN allows the search sequence to continue even if an error occurs while processing a particular file.

### Format

> LIB$FILE_SCAN fab ,user-success-procedure ,user-error-procedure [,context]

### RETURNS

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

### Arguments

> #### fab

> OpenVMS usage: | fab
> type: | unspecified
> access: | read only
> mechanism: | by reference

> File Access Block (FAB) referencing a valid NAM block or NAML block. The fab argument is the address of the FAB that contains the address and length of the file specification being searched for by LIB$FILE_SCAN. On Alpha systems, NAML blocks support the use of file specifications with a maximum length of NAML$C_MAXRSS. See the OpenVMS Record Management Services Reference Manual for information on NAML blocks.

> #### user-success-procedure

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

> User-supplied success routine that LIB$FILE_SCAN calls when a file is found. The success routine is invoked with the FAB address that was passed to LIB$FILE_SCAN. The user context may be pased to this routine using the FAB$L_CTX field in the FAB.

> #### user-error-procedure

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

> User-supplied error routine that LIB$FILE_SCAN calls when it encounters an error. The error routine is called with the FAB argument that was passed to LIB$FILE_SCAN.

> #### context

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

> Default file context used in processing file specifications for multiple input files. The context argument is the address of a longword, which must be initialized to zero by your program before the first call to LIB$FILE_SCAN. After the first call, LIB$FILE_SCAN maintains this longword. You must not change the value of context in subsequent calls to LIB$FILE_SCAN.

> Name blocks and file specification strings are allocated by LIB$FILE_SCAN, and context is used to retain their addresses so they may be deallocated later. If the context argument is not passed, unspecified portions of the file specification will be inherited from the previous file specification processed, rather than from multiple input file specifications.

### Description

> LIB$FILE_SCAN is called with the address of a File Access Block (FAB) and calls an action routine for each file found and/or error returned. LIB$FILE_SCAN allows the search sequence to continue even if an error occurs while processing a particular file.

> If this routine is called once for each file specification argument in a command line, portions of the file specifications which are not specified by the user are inherited from the last files processed.

> On Alpha systems, support for a file specification greater than 255 characters is provided by the use of NAML blocks rather than NAM blocks. See the OpenVMS Record Management Services Reference Manual for information on NAML blocks.

> You must call LIB$FILE_SCAN_END before initiating a new sequence of calls to LIB$FILE_SCAN.

### Condition Values Returned

> Any condition value returned by the RMS Parse service.

Previous | Next | Contents | Index

| privacy and legal statement |
5932PRO_016.HTML