Document revision date: 30 March 2001 | |
Previous | Contents | Index |
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.
LIB$STAT_VM code ,value-argument
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
LIB$STAT_VM_64 code ,value-argument
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
LIB$STOP condition-value [,number-of-arguments] [,FAO-argument...]
LIB$STOP generates a signal and stops execution of the calling program. No condition values are returned.
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.
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.
None.
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.
LIB$SUBX minuend-array ,subtrahend-array ,difference-array [,array-length]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
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.
LIB$SUB_TIMES time1 ,time2 ,resultant-time
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
Previous | Next | Contents | Index |
privacy and legal statement | ||
5932PRO_043.HTML |