Document revision date: 19 July 1999

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.

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.

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

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.

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.

	privacy and legal statement
5932PRO_042.HTML