hp.com home products and services support and drivers solutions how to buy
cd-rom home
End of Jump to page title
HP OpenVMS systems
documentation

Jump to content


HP OpenVMS RTL Library (LIB$) Manual

HP OpenVMS RTL Library (LIB$) Manual


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

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:

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.


Previous Next Contents Index