OpenVMS RTL Library (LIB$) Manual

Document revision date: 30 March 2001

OpenVMS RTL Library (LIB$) Manual

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;

 
 
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.

Contents

Index

privacy and legal statement

5932PRO_016.HTML

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

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

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

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

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

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

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

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

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

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.

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

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

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