![[OpenVMS documentation]](../../images/openvms_doc_banner_top.gif)
|
![[Site home]](../../images/buttons/bn_site_home_off.gif)
![[Send comments]](../../images/buttons/bn_comments_off.gif)
![[Help with this site]](../../images/buttons/bn_site_help_off.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs_off.gif)
![[OpenVMS site]](../../images/buttons/bn_openvms_off.gif)
![[Compaq site]](../../images/buttons/bn_compaq_off.gif)
|
|
Updated:
11 December 1998
|
OpenVMS RTL Library (LIB$) Manual
LIB$STAT_VM
The Return Virtual Memory Statistics routine returns to its caller one
of six statistics available from calls to LIB$GET_VM/LIB$FREE_VM and
LIB$GET_VM_PAGE/LIB$FREE_VM_PAGE. Unlike LIB$SHOW_VM, which formats the
values for output and displays them on SYS$OUTPUT, LIB$STAT_VM returns
the statistic in the value-argument argument. Only one
of the statistics is returned by each call to LIB$STAT_VM.
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$STAT_VM code ,value-argument
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
code
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Code specifying which statistic is to be returned. The
code argument contains the address of a signed
longword integer that is this code.
| Code |
Statistic |
|
1
|
Number of successful calls to LIB$GET_VM
|
|
2
|
Number of successful calls to LIB$FREE_VM
|
|
3
|
Number of bytes allocated by LIB$GET_VM but not yet deallocated by
LIB$FREE_VM
|
|
5
|
Number of calls to LIB$GET_VM_PAGE
|
|
6
|
Number of calls to LIB$FREE_VM_PAGE
|
|
7
|
Number of VAX pages or Alpha pagelets allocated by LIB$GET_VM_PAGE but
not yet deallocated by LIB$FREE_VM_PAGE
|
Note that it is invalid to omit code or to give a
code of 0 or 4.
value-argument
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Value of the statistic returned by LIB$STAT_VM. The
value-argument argument contains the address of an
unsigned longword integer that is this value.
Description
LIB$STAT_VM returns to its caller one of six available statistics.
Unlike LIB$SHOW_VM, which formats the values for output, LIB$STAT_VM
returns the value to a location specified as an argument.
Only one of the six statistics can be returned by one call to
LIB$STAT_VM. The argument code must be one of six
values described for LIB$SHOW_VM. A code value of 0 or
4 is invalid.
Unlike LIB$SHOW_VM, which produces ASCII values for output, LIB$STAT_VM
returns the value in binary form to a location specified as an argument.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_INVARG
|
Invalid argument. The value of
code was not one of the values allowed by LIB$STAT_VM.
|
LIB$STAT_VM_64 (Alpha Only)
The Return Virtual Memory Statistics routine returns to its caller one
of six statistics available from calls to LIB$GET_VM_64 and
LIB$FREE_VM_64, as well as LIB$GET_VM_PAGE_64 and LIB$FREE_VM_PAGE_64.
Unlike LIB$SHOW_VM_64, which formats the values for output and displays
them on SYS$OUTPUT, LIB$STAT_VM_64 returns the statistic in the
value-argument argument. Only one of the statistics is
returned by each call to LIB$STAT_VM_64.
Format
LIB$STAT_VM_64 code ,value-argument
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
code
| OpenVMS usage: |
quadword_signed |
| type: |
quadword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Code specifying which statistic is to be returned. The
code argument contains the address of a signed
quadword integer that is this code.
| Code |
Statistic |
|
1
|
Number of successful calls to LIB$GET_VM_64
|
|
2
|
Number of successful calls to LIB$FREE_VM_64
|
|
3
|
Number of bytes allocated by LIB$GET_VM_64 but not yet deallocated by
LIB$FREE_VM_64
|
|
5
|
Number of calls to LIB$GET_VM_PAGE_64
|
|
6
|
Number of calls to LIB$FREE_VM_PAGE_64
|
|
7
|
Number of Alpha pagelets allocated by LIB$GET_VM_PAGE_64 but not yet
deallocated by LIB$FREE_VM_PAGE_64
|
Note that it is invalid to omit code or to give a
code of 0 or 4.
value-argument
| OpenVMS usage: |
user_arg |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Value of the statistic returned by LIB$STAT_VM_64. The
value-argument argument contains the address of an
unsigned quadword integer that is this value.
Description
LIB$STAT_VM_64 returns to its caller one of six available statistics.
Unlike LIB$SHOW_VM_64, which formats the values for output,
LIB$STAT_VM_64 returns the value to a location specified as an argument.
Only one of the six statistics can be returned by one call to
LIB$STAT_VM_64. The code argument must be one of six
values described for LIB$SHOW_VM_64. A code value of 0
or 4 is invalid.
Unlike LIB$SHOW_VM_64, which produces ASCII values for output,
LIB$STAT_VM_64 returns the value in binary form to a location specified
as an argument.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_INVARG
|
Invalid argument. The value of
code was not one of the values allowed by
LIB$STAT_VM_64.
|
LIB$STOP
The Stop Execution and Signal the Condition routine generates a signal
that indicates that an exception condition has occurred in your
program. Exception conditions signaled by LIB$STOP cannot be continued
from the point of the signal.
Format
LIB$STOP condition-value [,number-of-arguments] [,FAO-argument...]
RETURNS
LIB$STOP generates a signal and stops execution of the calling program.
No condition values are returned.
Arguments
condition-value
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
OpenVMS 32-bit condition value. The condition-value
argument is an unsigned longword that contains this condition value.
The OpenVMS Programming Concepts Manual explains the format of a condition value.
number-of-arguments
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
read only |
| mechanism: |
by value |
Number of FAO arguments associated with
condition-value. The optional
number-of-arguments argument is a signed longword
integer that contains this number. If omitted or specified as zero, no
FAO arguments follow.
FAO-argument
| OpenVMS usage: |
varying_arg |
| type: |
unspecified |
| access: |
read only |
| mechanism: |
by value |
Optional FAO (formatted ASCII output) argument that is associated with
the specified condition value.
The OpenVMS Programming Concepts Manual explains the message format.
Description
LIB$STOP is called whenever your program must indicate an exception
condition because it is impossible to continue execution or return a
status code to the calling program.
LIB$STOP scans the stack frame by frame, starting with the most recent
frame, calling each established handler (see the OpenVMS Programming Concepts Manual).
LIB$STOP guarantees that control will not return to the caller.
The LIB$STOP argument list, the Program Counter (PC) and Processor
Status Longword (PSL on OpenVMS VAX systems, PS on OpenVMS Alpha
systems) of the caller are appended to build the signal argument vector.
The severity of condition-value is forced to SEVERE
before each call to a handler.
If any handler attempts to continue by returning a success completion
code, the error message ATTEMPT TO CONTINUE FROM STOP is printed and
your program exits.
If the handler called by LIB$STOP in turn calls system service $UNWIND,
control will not return to LIB$STOP's caller, thus changing the program
flow. A handler can also modify the saved copy of R0/R1 in the
mechanism vector, changing registers R0 and R1 after the stack has been
unwound. If a handler does neither of these things, then all registers
including R0/R1 and the hardware condition codes are preserved.
Note
On Alpha systems, OpenVMS Alpha instructions perform the equivalent
operation.
|
The only way a handler can prevent the image from exiting after a call
to LIB$STOP is to unwind the stack using the $UNWIND system service.
Condition Values Returned
None.
Example
|
10 EXTERNAL LONG FUNCTION LIB$RESERVE_EF
DECLARE LONG RET_STATUS
RET_STATUS = LIB$RESERVE_EF( 2% )
IF (RET_STATUS AND 1%) = 0% THEN
CALL LIB$STOP( RET_STATUS BY VALUE )
END IF
PRINT "Event flag 2 reserved successfully"
END
|
This BASIC example program uses LIB$STOP to stop executing if an error
is signaled. This BASIC program tries to reserve an event flag that is
not accessible to user programs, thus ensuring that an error will be
signaled.
The output generated by this BASIC program is as follows:
%LIB-F-EF_ALRRES, event flag already reserved
%TRACE-F-TRACEBACK, symbolic stack dump follows
module name routine name line rel PC abs PC
2822XBLST$MAIN 2822XBLST$MAIN 6 00000044 00000644
|
LIB$SUBX
The Multiple-Precision Binary Subtraction routine performs subtraction
on signed two's complement integers of arbitrary length.
Format
LIB$SUBX minuend-array ,subtrahend-array ,difference-array
[,array-length]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
minuend-array
| OpenVMS usage: |
vector_longword_signed |
| type: |
unspecified |
| access: |
read only |
| mechanism: |
by reference, array reference |
Minuend; a multiple-precision, signed two's complement integer. The
minuend-array argument is the address of an array of
signed longword integers that contains the minuend.
subtrahend-array
| OpenVMS usage: |
vector_longword_signed |
| type: |
unspecified |
| access: |
read only |
| mechanism: |
by reference, array reference |
Subtrahend; a multiple-precision, signed two's complement integer. The
subtrahend-array argument is the address of an array
of signed longword integers that contains the subtrahend.
difference-array
| OpenVMS usage: |
vector_longword_signed |
| type: |
unspecified |
| access: |
write only |
| mechanism: |
by reference, array reference |
Difference; a multiple-precision, signed two's complement integer
result. The difference-array argument is the address
of an array of signed longword integers that contains the difference.
array-length
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Length in longwords of the arrays to be operated on by LIB$SUBX. The
array-length argument contains the address of a signed
longword integer that is this length. The array-length
argument must not be negative. The default length is 2 units.
Description
LIB$SUBX performs subtraction on signed two's complement integers of
arbitrary length. The integers are located in arrays of longwords. The
higher addresses contain the higher-precision parts of the values. The
highest-addressed longword contains the sign and 31 bits of precision.
The remaining longwords contain 32 bits of precision in each. The
number of longwords to be operated on is given by the optional
argument, array-length. The default length is 2, which
corresponds to the OpenVMS quadword data type.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
SS$_INTOVF
|
Integer overflow. The result is correct, except that the sign bit is
lost.
|
|
LIB$_INVARG
|
Invalid argument. Length is negative. The output array is unchanged.
|
Example
|
C+
C This Fortran example program demonstrates the use of LIB$SUBX.
C-
INTEGER A(2),B(2),C(2),RETURN
C+
C Let "A" have the value 72057594037927937 = '1000000000000001'x.
C Let "B" have the value 4294967295 = '00000000FFFFFFFF'x.
C-
A(1) = '00000001'x
A(2) = '10000000'x
B(1) = 'FFFFFFFF'x
B(2) = '00000000'x
C+
C Then "A" - "B" is 72057589742960642.
C-
RETURN = LIB$SUBX(A,B,C)
TYPE *,' '
TYPE *,'Let A = 72057594037927937 and B = 4294967295.'
TYPE *,'Then C = A - B = 72057589742960642.'
TYPE 2,C(2),C(1)
2 FORMAT(' 72057589742960642 is represented as ',1H',Z8,Z8,3H'x.)
TYPE *, 51HThat is, C(2) = '0FFFFFFF'x and C(1) = '00000002'x.
END
|
This Fortran example demonstrates how to call LIB$SUBX. The output
generated by this program is as follows:
Let A = 72057594037927937 and B = 4294967295.
Then C = A - B = 72057589742960642.
72057589742960642 is represented as ' FFFFFFF 2'x.
That is, C(2) = '0FFFFFFF'x and C(1) = '00000002'x.
|
LIB$SUB_TIMES
The Subtract Two Quadword Times routine subtracts two OpenVMS
internal-time-format times.
Format
LIB$SUB_TIMES time1 ,time2 ,resultant-time
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
time1
| OpenVMS usage: |
date_time |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
First time, from which LIB$SUB_TIMES subtracts the second time. The
time1 argument is the address of an unsigned quadword
containing this time. The time1 argument must
represent a later or equal time or a longer or equal time interval than
time2. The time1 argument may be
either absolute time or delta time as long as time2 is
of the same type. If time1 and time2
are of different types, time1 must be the absolute
time.
time2
| OpenVMS usage: |
date_time |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Second time, which LIB$SUB_TIMES subtracts from the first time. The
time2 argument is the address of an unsigned quadword
containing this time. The time2 argument must
represent an earlier or equal time or a shorter or equal time interval
than time1. The time2 argument may be
either absolute time or delta time as long as time1 is
of the same type. If time2 and time1
are of different types, time2 must be the delta time.
resultant-time
| OpenVMS usage: |
date_time |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
The result of subtracting time2 from
time1. The resultant-time argument is
the address of an unsigned quadword containing the result. If both
time1 and time2 are delta times, then
resultant-time is a delta time. If both
time1 and time2 are absolute times,
then resultant-time is a delta time. If
time1 is an absolute time and time2
is a delta time, then resultant-time is an absolute
time.
Description
LIB$SUB_TIMES subtracts two OpenVMS internal times. The second time,
specified by time2, is subtracted from
time1. The following table shows the only combinations
of times you can subtract:
| Time1 |
Time2 |
Subtraction |
Resultant-Time |
|
delta
|
delta
|
time1 - time2
|
delta
|
|
absolute
|
absolute
|
time1 - time2
|
delta
|
|
absolute
|
delta
|
time1 - time2
|
absolute
|
OpenVMS does not allow a delta time to be 0 or negative. Therefore, if
time1 and time2 are equal,
resultant-time cannot be 0. Instead,
resultant-time is represented by .1 of one microsecond
(the smallest interval of time recognized by the OpenVMS operating
system). This interval is shown as "0 00:00:00.00" when
formatted by the standard techniques.
Condition Values Returned
|
LIB$_NORMAL
|
Routine successfully completed.
|
|
LIB$_INVARGORD
|
Invalid ordering of arguments.
|
|
LIB$_IVTIME
|
Invalid time.
|
|
LIB$_NEGTIM
|
Negative time computed.
|
|
LIB$_WRONUMARG
|
Incorrect number of arguments.
|
![[OpenVMS documentation]](../../images/openvms_doc_banner_bottom.gif)