 |
HP OpenVMS RTL Library (LIB$) Manual
LIB$ESTABLISH
The Establish a Condition Handler routine moves the address of a
condition handling routine (which can be a user-written or a library
routine) to longword 0 of the stack frame of the caller of
LIB$ESTABLISH.
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 not available to native OpenVMS Alpha and I64 programs
but is recognized and handled appropriately by most HP high-level
language compilers.
Format
LIB$ESTABLISH new-handler
RETURNS
| OpenVMS usage: |
routine |
| type: |
procedure value |
| access: |
write only |
| mechanism: |
by reference |
Previous contents of SF$A_HANDLER (longword 0) of the caller's stack
frame; zero if no handler existed.
Argument
new-handler
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
read only |
| mechanism: |
by value |
Routine to be set up as the condition handler. The
new-handler argument is the address of the procedure
value to this routine.
Description
LIB$ESTABLISH moves the address of a condition-handling routine to
longword 0 of the stack frame of the caller of LIB$ESTABLISH. This
condition-handling routine then becomes the caller's condition handler.
LIB$ESTABLISH returns the previous contents of longword 0. This can
either be the address of the caller's previous condition handler or
zero if no handler existed.
The new condition handler remains in effect for your routine until you
call LIB$REVERT or until control returns to the caller of the routine
that called LIB$ESTABLISH. Once this happens, you must call
LIB$ESTABLISH again if the same (or a new) condition handler is to be
associated with the routine that called LIB$ESTABLISH.
LIB$ESTABLISH modifies the caller's stack frame.
LIB$ESTABLISH is provided primarily for use with languages without
built-in error handling facilities. Do not use LIB$ESTABLISH with
languages that provide error handling, such as BASIC, COBOL, Pascal,
and PL/I. The language-support library for these languages depends on
predefined language-specific handlers, and use of LIB$ESTABLISH with
these languages may adversely affect the behavior of your program. See
the language documentation for more information about how each language
handles errors.
In VAX MACRO, use the following instruction instead of calling
LIB$ESTABLISH:
MOVAB HANDLER, (FP) ; set handler address
; in current stack frame
|
Condition Values Returned
None.
Example
|
C+
C This Fortran program demonstrates the
C use of LIB$ESTABLISH.
C
C This is the main program.
C-
EXTERNAL LOG_HANDL
CHARACTER TIMBUF
OPEN (UNIT=99, FILE = 'ERRLOG', STATUS = 'NEW')
CALL LIB$ESTABLISH (LOG_HANDL)
CALL SYS$BINTIM (TIMBUF, TIMADR)
C+
C The rest of the main program would go here.
C-
END
INTEGER*4 FUNCTION LOG_HANDL (SIGARGS, MECHARGS)
INTEGER*4 SIGARGS (*), MECHARGS (5)
C+
C This is the handler to journal any signaled error messages.
C-
INCLUDE '($SSDEF)'
EXTERNAL PUT_LINE
LOG_HANDL = SS$_RESIGNAL
CALL SYS$PUTMSG (SIGARGS, PUT_LINE, )
RETURN
END
C+
C This is the action subroutine.
C-
LOGICAL*4 FUNCTION PUT_LINE (LINE)
CHARACTER*(*)LINE
PUT_LINE = .FALSE.
100 WRITE (99,200)LINE
200 FORMAT (A)
RETURN
END
|
In this Fortran example, the function log_handl is the
condition handler for the program, and thus receives control when an
error occurs.
LIB$EXPAND_NODENAME
The Expand a Node Name to Its Full Name Equivalent routine expands a
node name to its full name equivalent.
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$EXPAND_NODENAME nodename, fullname [,resultant-length]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
nodename
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Node name to be expanded. The nodename argument
contains the address of a descriptor pointing to this node-name string.
The error LIB$_INVARG is returned if nodename contains
an invalid node name, points to a null string, or contains more than
1024 characters. The error LIB$_INVSTRDES is returned if
nodename is an invalid descriptor.
fullname
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Expanded node name. The fullname argument contains the
address of a descriptor pointing to the expanded node-name string.
LIB$EXPAND_NODENAME writes the expanded node-name string into the
buffer pointed to by the fullname descriptor.
The error LIB$_INVSTRDES is returned if fullname is an
invalid descriptor.
The length field of the fullname descriptor is not
updated unless fullname is a dynamic descriptor with a
length less than the resulting expanded full name. Refer to the
OpenVMS RTL String Manipulation (STR$) Manual for dynamic string descriptor usage.
The fullname argument contains an unusable result when
LIB$EXPAND_NODENAME returns in error.
resultant-length
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Length of the expanded node name. The resultant-length
argument is the address of an unsigned word that contains this length
in bytes.
The resultant-length argument contains an unusable
result when LIB$EXPAND_NODENAME returns in error.
Description
This routine expands the input node name to its full name equivalent.
Input is validated against the supported form of node names. The error
LIB$_INVARG is returned if the input node name is invalid.
If the returned full name overflows the buffer pointed to by
fullname, the returned full name is truncated, and the
alternate successful status LIB$_STRTRU is returned. The
resultant-length argument is set to the value of the
length field of the fullname descriptor if this
argument is supplied.
If the length of the returned full name is less than or equal to the
output buffer, the expanded full name is returned in
fullname. Resultant-length is set to
the actual length of the expanded full name if this argument is
supplied.
In a DECnet environment, expanding a DECnet-Plus node name results in
the error condition LIB$_INVARG.
LIB$EXPAND_NODENAME uses the underlying network directory services to
look up the full name. In a DECnet-Plus for OpenVMS environment,
LIB$EXPAND_NODENAME verifies the existence of the expanded full name in
the naming environment. If the expanded full name does not exist in the
naming environment, an error condition is returned from the underlying
network services and is propagated back to the caller of
LIB$EXPAND_NODENAME.
It is recommended that applications use full names instead of the short
form of full names whenever possible. Because the short form of a full
name is intended to be used only in a specific naming environment, make
sure the short form of a full name is expanded in the right naming
environment to avoid ambiguity. See LIB$COMPRESS_NODENAME for more information
about where and when to use the short form of a full name.
Any error resulting from calling the underlying network services is
propagated and returned as condition values in this routine.
LIB$EXPAND_NODENAME supports any string class for the
nodename and fullname string
arguments.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_STRTRU
|
Routine successfully completed. Characters are truncated in the output
buffer pointed to by the
fullname descriptor.
|
|
LIB$_INVARG
|
Invalid argument:
-
nodename is invalid.
-
nodename points to a null string.
- The length of the node name is more than 1024 characters.
- The expanded DECnet Phase V node name is invalid in a DECnet for OpenVMS
environment.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor.
|
|
LIB$_WRONUMARG
|
Wrong number of arguments.
|
Any condition value returned by RTL routine LIB$SCOPY_R_DX or
DECnet service $IPC.
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 and I64 systems, OpenVMS Alpha and I64 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 and I64 systems, OpenVMS Alpha and I64 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 and I64 systems, OpenVMS Alpha and I64 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.
|
|
