Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

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:

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

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
5932PRO_013.HTML