|
|
Updated:
11 December 1998
|
OpenVMS RTL Library (LIB$) Manual
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.