Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

Previous | Contents | Index

## LIB$DO_COMMAND

> The Execute Command routine stops program execution and directs the command language interpreter (CLI) to execute a command that you supply as the argument. If successful, LIB$DO_COMMAND does not return control to the calling program. Instead, LIB$DO_COMMAND begins execution of the specified command.

> If you want control to return to the caller, use LIB$SPAWN instead.

### Format

> LIB$DO_COMMAND command-string

### RETURNS

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

### Argument

> #### command-string

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

> Text of the command that LIB$DO_COMMAND executes. The command-string argument is the address of a descriptor pointing to the command text. The maximum length of the command is 255 characters.

### Description

> LIB$DO_COMMAND terminates your current image and then executes the contents of command-string as a command. The command is parsed using normal DCL rules.

> LIB$DO_COMMAND is especially useful when you want to execute a CLI command after your program has finished executing. For example, you could use the routine to execute a SUBMIT or PRINT command to handle a file that your program has created.

> Because of the following restrictions on LIB$DO_COMMAND, you should be careful when you incorporate it in your program:

> - During the call to LIB$DO_COMMAND, the current image exits and control cannot return to it.
> - The text of the command is passed to the current command language interpreter. Because you can define your own CLI in addition to DCL and MCR, you must make sure that the command will be handled by the intended CLI.
> - If LIB$DO_COMMAND is called from an image run directly as a subprocess or detached process, it will not execute correctly, because no CLI is associated with a subprocess.

> LIB$DO_COMMAND is supported for use with the DCL and 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. Note that the command can execute an indirect file using the at sign (@) feature of DCL.

### Condition Values Returned

> LIB$_INVARG | Invalid argument. command-string was more than 255 characters.
> 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 that 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.

### Example

    PROGRAM DO_COMMAND(INPUT, OUTPUT);

    {+}
    {  This example uses LIB$DO_COMMAND to execute
    {  any DCL command that is entered by the user
    {  at the prompt.
    {-}

    PROCEDURE LIB$DO_COMMAND(CMDTXT : VARYING [A] OF CHAR);
       EXTERN;

    VAR
      COMMAND :  VARYING [256] OF CHAR;

    BEGIN
      WRITELN('ENTER THE COMMAND YOU WANT TO EXECUTE: ');
      READLN(COMMAND);
      LIB$DO_COMMAND(COMMAND);
    END.

> This Pascal program shows how to call LIB$DO_COMMAND. An example of the output of this program is as follows:

>     $ RUN DO_COMMAND
>     ENTER THE COMMAND YOU WANT TO EXECUTE:  SHOW TIME
>       30-MAY-2000 14:07:28

## LIB$EDIV

> The Extended-Precision Divide routine performs extended-precision division. LIB$EDIV makes the VAX EDIV instruction available as a callable routine.

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

### Format

> LIB$EDIV longword-integer-divisor ,quadword-integer-dividend ,longword-integer-quotient ,remainder

### RETURNS

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

### Arguments

> #### longword-integer-divisor

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

> Divisor. The longword-integer-divisor argument is the address of a signed longword integer containing the divisor.

> #### quadword-integer-dividend

> OpenVMS usage: | quadword_signed
> type: | quadword integer (signed)
> access: | read only
> mechanism: | by reference

> Dividend. The quadword-integer-dividend argument is the address of a signed quadword integer containing the dividend.

> #### longword-integer-quotient

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

> Quotient. The longword-integer-quotient argument is the address of a signed longword integer containing the quotient.

> #### remainder

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

> Remainder. The remainder argument is the address of a signed longword integer containing the remainder.

### Condition Values Returned

> SS$_NORMAL | Normal successful operation.
> SS$_INTDIV | Integer divide by zero. The quotient is replaced by bits 31:0 of the dividend, and the remainder is replaced by zero.
> SS$_INTOVF | Integer overflow. The quotient is replaced by bits 31:0 of the dividend, and the remainder is replaced by zero.

### Example

    C+
    C This Fortran program demonstrates how to use LIB$EDIV.
    C-

            INTEGER DIVISOR,DIVIDEND(2),QUOTIENT,REMAINDER

    C+
    C Find the quotient and remainder of 4600387192 divided by 4096.
    C Because 4600387192 is too large to store as a longword, use LIB$EDIV.
    C-

            DIVISOR = 4096

    C+
    C The dividend must be represented as a quadword. To do this use a vector
    C of length 2. The first element is the low-order longword, and the second
    C element is the high-order longword.
    C Now, 4600387192 = '00000000112345678'x. So,
    C-

            DIVIDEND(1) = '12345678'X
            DIVIDEND(2) = '00000001'X

    C+
    C Compute the quotient and remainder of 4600387192 divided by 4096.
    C-

            RETURN = LIB$EDIV(DIVISOR,DIVIDEND,QUOTIENT,REMAINDER)
            TYPE *,'The longword integer quotient of 4600387192/4096 is:'
            TYPE *,'               ',QUOTIENT
            TYPE *,'The longword integer remainder of 4600387192/4096 is:'
            TYPE *,'               ', REMAINDER
            END

> This Fortran example demonstrates how to call LIB$EDIV. The output generated by this program is as follows:

>      The longword integer quotient of 4600387192/4096 is:
>                          1123141
>      The longword integer remainder of 4600387192/4096 is:
>                             1656

## LIB$EMODD

> The Extended Multiply and Integerize routine (D-Floating-Point Values) allows higher-level language users to perform accurate range reduction of D-floating arguments.

On Alpha systems, D-floating-point values are not supported in full precision in native OpenVMS Alpha programs. They are precise to 56 bits on VAX systems, 53 or 56 bits in translated VAX images, and 53 bits in native OpenVMS Alpha programs.

### Format

> LIB$EMODD 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: | D_floating
> access: | read only
> mechanism: | by reference

> The multiplier. The floating-point-multiplier argument is a D-floating number.

> #### multiplier-extension

> OpenVMS usage: | byte_unsigned
> type: | byte (unsigned)
> access: | read only
> mechanism: | by reference

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

> #### floating-point-multiplicand

> OpenVMS usage: | floating_point
> type: | D_floating
> access: | read only
> mechanism: | by reference

> The multiplicand. The floating-point-multiplicand argument is a D-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: | D_floating
> access: | write only
> mechanism: | by reference

> The fractional portion of the result. The fractional-portion argument is a D-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$EMODD | 8 | 7:0 | 64

### Condition Values Returned

> SS$_NORMAL | Routine successfully completed.
> SS$_FLTUND | Floating underflow. The integer and fraction operands are replaced by zero (0).
> 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$EMODF

> The Extended Multiply and Integerize routine (F-Floating-Point Values) allows higher-level language users to perform accurate range reduction of F-floating arguments.

### Format

> LIB$EMODF 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: | F_floating
> access: | read only
> mechanism: | by reference

> The multiplier. The floating-point-multiplier argument is the address of an F-floating number containing the number.

> #### multiplier-extension

> OpenVMS usage: | byte_unsigned
> type: | byte (unsigned)
> access: | read only
> mechanism: | by reference

> The left-justified multiplier-extension bits. The multiplier-extension argument is the address of an unsigned byte containing these multiplier extension bits.

> #### floating-point-multiplicand

> OpenVMS usage: | floating_point
> type: | F_floating
> access: | read only
> mechanism: | by reference

> The multiplicand. The floating-point-multiplicand argument is an F-floating number.

> #### integer-portion

> OpenVMS usage: | longword_signed
> type: | longword (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: | F_floating
> access: | write only
> mechanism: | by reference

> The fractional portion of the result. The fractional-portion argument is the address of an F-floating number containing the fractional portion of the result.

### Description

> LIB$EMODF allows higher-level language users to perform accurate range reduction of F-floating arguments.

> 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$EMODF | 8 | 7:0 | 32

### 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$EMODG

> The Extended Multiply and Integerize routine (G-Floating-Point Values) allows higher-level language users to perform accurate range reduction of G-floating arguments.

### Format

> LIB$EMODG 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: | G_floating
> access: | read only
> mechanism: | by reference

> The multiplier. The floating-point-multiplier argument is a G-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: | G_floating
> access: | read only
> mechanism: | by reference

> The multiplicand. The floating-point-multiplicand argument is a G-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: | G_floating
> access: | write only
> mechanism: | by reference

> The fractional portion of the result. The fractional-portion argument is a G-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$EMODG | 11 | 15:5 | 64

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

Previous | Next | Contents | Index

| privacy and legal statement |
5932PRO_014.HTML