Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

Previous | Contents | Index

## LIB$EMODH

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

## LIB$EMUL

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

## LIB$ENABLE_CTRL

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

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

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

Previous | Next | Contents | Index

| privacy and legal statement |
5932PRO_015.HTML