|
Document revision date: 19 July 1999
|
![[Compaq]](../../images/compaq.gif) |
![[Go to the documentation home page]](../../images/buttons/bn_site_home.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs.gif)
![[Help on this site]](../../images/buttons/bn_site_help.gif)
![[How to contact us]](../../images/buttons/bn_comments.gif)
|
![[OpenVMS documentation]](../../images/ovmsdoc_sec_head.gif)
|
OpenVMS RTL Library (LIB$) Manual
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-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.
|