Updated: 11 December 1998

OpenVMS RTL Library (LIB$) Manual

On OpenVMS VAX systems, the Extended Multiply and Integerize routine (H-Floating-Point Values) allows higher-level language users to perform accurate range reduction of H-floating arguments.

This routine is not available to native OpenVMS Alpha programs but is available to translated VAX images.

Format

LIB$EMODH floating-point-multiplier ,multiplier-extension ,floating-point-multiplicand ,integer-portion ,fractional-portion

RETURNS

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

Arguments

floating-point-multiplier

OpenVMS usage:	floating_point
type:	H_floating
access:	read only
mechanism:	by reference

The multiplier. The floating-point-multiplier argument is an H-floating number.

multiplier-extension

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

The left-justified multiplier-extension bits. The multiplier-extension argument is an unsigned word.

floating-point-multiplicand

OpenVMS usage:	floating_point
type:	H_floating
access:	read only
mechanism:	by reference

The multiplicand. The floating-point-multiplicand argument is an H-floating number.

integer-portion

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

The integer portion of the result. The integer-portion argument is the address of a signed longword integer containing the integer portion of the result.

fractional-portion

OpenVMS usage:	floating_point
type:	H_floating
access:	write only
mechanism:	by reference

The fractional portion of the result. The fractional-portion argument is an H-floating number.

Description

The floating-point multiplier extension operand (second operand) is concatenated with the floating-point multiplier (first operand) to gain x additional low-order fraction bits. The multiplicand is multiplied by the extended multiplier. After multiplication, the integer portion is extracted and a y-bit floating-point number is formed from the fractional part of the product by truncating extra bits.

The multiplication yields a result equivalent to the exact product truncated to a fraction field of y bits. With respect to the result as the sum of an integer and fraction of the same sign, the integer operand is replaced by the integer part of the result and the fraction operand is replaced by the rounded fractional part of the result.

The values of x and y are as follows:

Routine	x	Bits	y
LIB$EMODH	15	15:1	128

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
SS$_FLTUND	Floating underflow. The integer and fraction operands are replaced by zero.
SS$_INTOVF	Integer overflow. The integer operand is replaced by the low-order bits of the true result. Floating overflow is indicated by SS$_INTOVF also.
SS$_ROPRAND	Reserved operand. The integer and fraction operands are unaffected.

The Extended-Precision Multiply routine performs extended-precision multiplication. LIB$EMUL makes the VAX EMUL instruction available as a callable routine.

Note On Alpha systems, OpenVMS Alpha instructions perform the equivalent operation.

Format

LIB$EMUL longword-integer-multiplier ,longword-integer-multiplicand ,addend ,product

RETURNS

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

Arguments

longword-integer-multiplier

OpenVMS usage:	longword_signed
type:	longword integer (signed)
access:	read only
mechanism:	by reference

Multiplier used by LIB$EMUL in the extended-precision multiplication. The longword-integer-multiplier argument is the address of a signed longword integer containing the multiplier.

longword-integer-multiplicand

OpenVMS usage:	longword_signed
type:	longword integer (signed)
access:	read only
mechanism:	by reference

Multiplicand used by LIB$EMUL in the extended-precision multiplication. The longword-integer-multiplicand argument is the address of a signed longword integer containing the multiplicand.

addend

OpenVMS usage:	longword_signed
type:	longword integer (signed)
access:	read only
mechanism:	by reference

Addend used by LIB$EMUL in the extended-precision multiplication. The addend argument is the address of a signed longword integer containing the addend.

product

OpenVMS usage:	quadword_signed
type:	quadword integer (signed)
access:	write only
mechanism:	by reference

Product of the extended-precision multiplication. The product argument is the address of a signed quadword integer into which LIB$EMUL writes the product.

Description

The multiplicand argument is multiplied by the multiplier argument giving a double-length result. The addend argument is sign-extended to double-length and added to the result. LIB$EMUL then writes the result into the product argument.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.

Example

      INTEGER MULT1,MULT2,ADDEND,PRODUCT(2) 
C+ 
C Find the extended precision multiplication of 268435456 times 4096. 
C That is, find the extended precision product of 2**28 times 2**12. 
C Since 268435456 times 4096 is 2**40, a quadword value is needed for 
C the calculation: use LIB$EMUL. 
C- 
      MULT1 = 4096 
      MULT2 = 268435456 
      APPEND = 0 
C+ 
C Compute 268435456*4096. 
C Note that product will be stored as a quadword. This value will be stored 
C in the 2 dimensional vector PRODUCT. The first element of PRODUCT will 
C contain the low order bits, while the second element will contain the high 
C order bits. 
C- 
      RETURN = LIB$EMUL(MULT1,MULT2,APPEND,PRODUCT) 
      TYPE *,'PRODUCT(2) =',PRODUCT(2),' and PRODUCT(1) = ',PRODUCT(1) 
      TYPE *,' ' 
      TYPE *,'Note that 256 and 0 represent the hexadecimal value' 
      type *,14H'10000000000'x,', which in turn, represents 2**40.' 
      END 
 
      

This Fortran program demonstrates how to use LIB$EMUL. The output generated by this program is as follows:

PRODUCT(2) = 256 and PRODUCT(1) = 0

Note that 256 and 0 represent the hexadecimal value '10000000000'x, which in turn represents 2⁴⁰.

The Enable CLI Interception of Control Characters routine requests the calling process's command language interpreter (CLI) to resume interception of the selected control characters when they are typed during an interactive terminal session. LIB$ENABLE_CTRL provides the same function as the DCL command SET CONTROL.

Format

LIB$ENABLE_CTRL enable-mask [,old-mask]

RETURNS

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

Arguments

enable-mask

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

Bit mask indicating for which control characters LIB$ENABLE_CTRL is to enable interception. The enable-mask argument is the address of an unsigned longword containing this bit mask. Each of the 32 bits corresponds to one of the 32 possible control characters. If a bit is set, the corresponding control character is intercepted by the CLI. Currently, only bits 20 and 25, corresponding to Ctrl/T and Ctrl/Y, are recognized.

The following mask is defined in symbol libraries supplied by Compaq to specify the value of enable-mask:

Symbol	Hex Value	Function
LIB$M_CLI_CTRLT	%X'00100000'	Enables Ctrl/T
LIB$M_CLI_CTRLY	%X'02000000'	Enables Ctrl/Y

If a set bit does not correspond to a character that the CLI can intercept, an error is returned.

old-mask

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Previous bit mask. The old-mask argument is the address of an unsigned longword containing the old bit mask. The old bit mask is of the same form as enable-mask.

Description

LIB$ENABLE_CTRL provides the functions of the DCL command SET CONTROL. Normally, Ctrl/Y interrupts the current command, command procedure, or image. After a call to LIB$DISABLE_CTRL, Ctrl/Y is treated like Ctrl/U followed by a carriage return. LIB$ENABLE_CTRL restores the normal operation of Ctrl/Y or Ctrl/T.

Both the DCL and MCR CLIs can intercept control characters. See the OpenVMS DCL Dictionary for information on how the CLI processes control characters.

LIB$ENABLE_CTRL is supported for use with the DCL or MCR CLIs.

If an image is run directly as a subprocess or as a detached process, there is no CLI present to perform this function. In those cases, the error status LIB$_NOCLI is returned.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
LIB$_INVARG	Invalid argument. A bit in enable-mask was set which did not correspond to a control character supported by the CLI.
LIB$_NOCLI	No CLI present. The calling process did not have a CLI to perform the function, or the CLI did not support the request type. Note that an image run as a subprocess or detached process does not have a CLI.
LIB$_UNECLIERR	Unexpected CLI error. The CLI returned an error status which was not recognized. This error may be caused by use of a nonstandard CLI. If this error occurs while using the DCL or MCR CLIs, please report the problem to your Compaq support representative.

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 programs but is recognized and handled appropriately by most Compaq 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.

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 for OpenVMS environment, expanding a DECnet-Plus for OpenVMS 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.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5932PRO_014.HTML