HP OpenVMS RTL Library (LIB$) Manual

Contents

Index

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 INTEGER4 FUNCTION LOG_HANDL (SIGARGS, MECHARGS) INTEGER4 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- LOGICAL4 FUNCTION PUT_LINE (LINE) CHARACTER()LINE PUT_LINE = .FALSE. 100 WRITE (99,200)LINE 200 FORMAT (A) RETURN END

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;

 
 
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.

Contents

Index

OpenVMS usage:	routine
type:	procedure value
access:	write only
mechanism:	by reference

OpenVMS usage:	procedure
type:	procedure value
access:	read only
mechanism:	by value

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

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

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

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.

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