 |
OpenVMS RTL Library (LIB$) Manual
This Pascal program demonstrates how to call LIB$SHOW_TIMER. The output
generated by this Pascal example is as follows:
$ RUN SHOW_TIMER
Spend time to acquire elapsed real time and page faults
User argument is 5
ELAPSED: 0 00:00:00.44 CPU: 0:00:00.04
BUFIO: 1 DIRIO: 0 FAULTS: 18
|
LIB$SHOW_VM
The Show Virtual Memory Statistics routine returns the statistics
accumulated from calls to LIB$GET_VM/LIB$FREE_VM and
LIB$GET_VM_PAGE/LIB$FREE_VM_PAGE.
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$SHOW_VM [code] [,user-action-procedure] [,user-specified-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 any one of the statistics to be written to SYS$OUTPUT
or passed to an action routine for processing. The
code argument is the address of a signed longword
integer containing the statistic code. This is an optional argument. If
the statistic code is omitted or is zero, statistics for values 1, 2,
and 3 are returned on one line.
The following values are allowed for the code argument:
| Value |
Statistic |
|
0
|
Statistics for values 1, 2, and 3 are returned.
|
|
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.
|
|
4
|
Statistics for values 5, 6, and 7 are returned.
|
|
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.
|
user-action-procedure
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
User-supplied action routine called by LIB$SHOW_VM. By default,
LIB$SHOW_VM returns statistics to SYS$OUTPUT. An action routine is
useful when you want to return statistics to a file or, in general, to
any place other than SYS$OUTPUT. The routine returns either a success
or failure condition value, which will be returned as the value of
LIB$SHOW_VM.
For more information on the action routine, see Call Format for an Action Routine in the
Description section.
user-specified-argument
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
A 32-bit value to be passed directly to the action routine without
interpretation. That is, the contents of the argument list entry
user-specified-argument are copied to the argument
list entry for user-action-procedure.
Description
LIB$SHOW_VM returns the statistics accumulated from calls to
LIB$GET_VM/LIB$FREE_VM and LIB$GET_VM_PAGE/LIB$FREE_VM_PAGE. By
default, with neither code nor
user-action-procedure specified in the call,
LIB$SHOW_VM writes a line giving the following information to
SYS$OUTPUT:
mmm calls to LIB$GET_VM, nnn calls to LIB$FREE_VM, ppp bytes still allocated
|
Optionally, any one of six statistics can be output to SYS$OUTPUT
and/or the line of information can be passed to a user-specified
"action routine" for processing different from the default.
Call Format for an Action Routine
The action routine is a user-supplied routine that LIB$SHOW_VM calls if
you specify the user-action-procedure argument in the
call to LIB$SHOW_VM.
The call format for an action routine is:
user-action-procedure resultant-string ,user-specified-argument
|
resultant-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Statistics supplied by LIB$SHOW_VM. The
resultant-string argument is the address of a
descriptor pointing to an address into which LIB$SHOW_VM writes the
statistics. The string is formatted exactly as it would be if written
to SYS$OUTPUT. The first character is a blank;
carriage-return/line-feed combinations are not included.
user-specified-argument
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The 32-bit value passed to LIB$SHOW_VM is passed to the action routine
without interpretation. If the user-specified-argument
argument is omitted in the call to LIB$SHOW_VM, a zero is passed by
value to the user routine.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_INVARG
|
Invalid arguments. This can be caused by an invalid value for
code.
|
Any condition values returned by LIB$PUT_OUTPUT or your action routine.
LIB$SHOW_VM_64 (Alpha Only)
The Show Virtual Memory Statistics routine returns the statistics
accumulated from calls to LIB$GET_VM_64/LIB$FREE_VM_64 and
LIB$GET_VM_PAGE_64/LIB$FREE_VM_PAGE_64.
Format
LIB$SHOW_VM_64 [code] [,user-action-procedure]
[,user-specified-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 any one of the statistics to be written to SYS$OUTPUT
or passed to an action routine for processing. The
code argument is the address of a signed quadword
integer containing the statistic code. This is an optional argument. If
the statistic code is omitted or is zero, statistics for values 1, 2,
and 3 are returned on one line.
The following values are allowed for the code argument:
| Value |
Statistic |
|
0
|
Statistics for values 1, 2, and 3 are returned.
|
|
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.
|
|
4
|
Statistics for values 5, 6, and 7 are returned.
|
|
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.
|
user-action-procedure
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
User-supplied action routine called by LIB$SHOW_VM_64. By default,
LIB$SHOW_VM_64 returns statistics to SYS$OUTPUT. An action routine is
useful when you want to return statistics to a file or, in general, to
any place other than SYS$OUTPUT. The routine returns either a success
or failure condition value, which will be returned as the value of
LIB$SHOW_VM_64.
For more information on the action routine, see Call Format for an Action Routine in the
Description section.
user-specified-argument
| OpenVMS usage: |
user_arg |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
A 64-bit value to be passed directly to the action routine without
interpretation. That is, the contents of the argument list entry
user-specified-argument are copied to the argument
list entry for user-action-procedure.
Description
LIB$SHOW_VM_64 returns the statistics accumulated from calls to
LIB$GET_VM_64/LIB$FREE_VM_64 and
LIB$GET_VM_PAGE_64/LIB$FREE_VM_PAGE_64. By default, with neither
code nor user-action-procedure
specified in the call, LIB$SHOW_VM_64 writes a line giving the
following information to SYS$OUTPUT:
mmm calls to LIB$GET_VM_64, nnn calls to LIB$FREE_VM_64, ppp bytes still
allocated
|
Optionally, any one of six statistics can be output to SYS$OUTPUT
and/or the line of information can be passed to a user-specified
"action routine" for processing different from the default.
Call Format for an Action Routine
The action routine is a user-supplied routine that LIB$SHOW_VM_64 calls
if you specify the user-action-procedure argument in
the call to LIB$SHOW_VM_64.
The call format for an action routine is:
user-action-procedure resultant-string ,user-specified-argument
|
resultant-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Statistics supplied by LIB$SHOW_VM_64. The
resultant-string argument is the address of a
descriptor pointing to an address into which LIB$SHOW_VM_64 writes the
statistics. The string is formatted exactly as it would be if written
to SYS$OUTPUT. The first character is a blank;
carriage-return/line-feed combinations are not included.
user-specified-argument
| OpenVMS usage: |
user_arg |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The 64-bit value passed to LIB$SHOW_VM_64 is passed to the action
routine without interpretation. If the
user-specified-argument argument is omitted in the
call to LIB$SHOW_VM_64, a zero is passed by value to the user routine.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_INVARG
|
Invalid arguments. This can be caused by an invalid value for
code.
|
Any condition values returned by LIB$PUT_OUTPUT or your action routine.
LIB$SHOW_VM_ZONE
The Return Information About a Zone routine returns formatted
information about a zone in the 32-bit virtual address space, detailing
such information as the zone's name, characteristics, and areas, and
then passes the information to the specified or default action routine.
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$SHOW_VM_ZONE zone-id [,detail-level] [,user-action-procedure]
[,user-arg]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
zone-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Zone identifier. The zone-id argument is the address
of an unsigned longword containing this identifier. Use zero to
indicate the 32-bit default zone.
detail-level
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
An identifier code specifying the level of detail required by the user.
The detail-level argument is the address of a signed
longword containing this code. The default is minimal information. The
following are valid values for detail-level:
|
0
|
zone-id and name
|
|
1
|
zone-id, name, algorithm, flags, and size information
|
|
2
|
zone-id, name, algorithm, flags, size information,
cache information, and area summary
|
|
3
|
zone-id, name, algorithm, flags, size information,
cache information, area summary, and queue validation
|
user-action-procedure
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
Optional user-supplied action routine called by LIB$SHOW_VM_ZONE. By
default, LIB$SHOW_VM_ZONE prints statistics to SYS$OUTPUT by means of
LIB$PUT_OUTPUT. An action routine is useful when you want to return
statistics to a file or, in general, to any location other than
SYS$OUTPUT. If user-action-procedure fails,
LIB$SHOW_VM_ZONE terminates and returns a failure code. Success codes
are ignored.
For more information on the action routine, see the Description section.
user-arg
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Optional 32-bit value to be passed directly to the action routine
without interpretation. That is, the contents of the argument list
entry user-arg are copied to the argument list entry
for user-action-procedure.
Description
LIB$SHOW_VM_ZONE returns formatted information about the specified zone
and passes it to the action routine. The detail-level
argument determines the degree of detail of the zone information
returned, and this information is formatted into a readable display and
passed to either a user action routine or to LIB$PUT_OUTPUT.
The action routine is a user-supplied routine that LIB$SHOW_VM_ZONE
calls if you specify the action-routine argument in
the call to LIB$SHOW_VM_ZONE. If you do not specify
action-routine, the information is passed to
LIB$PUT_OUTPUT for output to SYS$OUTPUT. The call format for an action
routine is as follows:
action-routine string, user-arg
|
Arguments
string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Information supplied by LIB$SHOW_VM_ZONE. The string
argument is the address of a descriptor pointing to an address into
which LIB$SHOW_VM_ZONE writes the requested information. The string is
formatted exactly as it would be if written to SYS$OUTPUT.
user-arg
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The 32-bit value passed to LIB$SHOW_VM_ZONE is passed to the action
routine without interpretation. If the user-arg
argument is omitted in the call to LIB$SHOW_VM_ZONE, a zero is passed
by value to the user routine.
If no zone-id is specified (0 is passed), the 32-bit
default zone is used.
You must ensure that you have exclusive access to the zone while
information is being displayed. Results are unpredictable and may be
inconsistent if another thread of control modifies the zone while this
routine is displaying data or scanning control blocks.
While scanning the queues and free lists, this routine may detect
errors.
If the lookaside list summary discovers a block improperly linked into
the list so that the list appears disjointed, the count of the number
of blocks of that particular size will be displayed as asterisks.
Table lib-7 lists error and warning messages that can be displayed
during the lookaside list and area free list scans. The format is:
**** ERROR -- error description ****
**** WARNING -- warning description ****
|
Table lib-7 LIB$SHOW_VM_ZONE Error and Warning Messages
| Error Message |
Description |
|
Invalid block size
|
The size of the block is either not large enough to contain the
necessary queue links or is unreasonably large. The size field has been
corrupted. Therefore, the size of the block is reduced so the block to
be dumped fits within the area.
|
|
Block not owned by zone
|
The current block is not within a section of the virtual address space
controlled by this zone. It is possibly attempting to free a block not
originally allocated from this zone.
|
|
Block extends past the end of area; truncated
|
The end of the block is not in the area from which the block has been
allocated. The size field may have been corrupted. Therefore, the size
of the block is reduced so the block to be dumped fits within the area.
|
|
Block extends into "unallocated" block, truncated
|
The end of the block extends past the allocated section of the area.
The size field may have been corrupted. Therefore, the size of the
block is reduced so the block to be dumped fits within the area.
|
|
Current block not completely accessible
|
The current block extends into a nonexistent part of the virtual
address space. The size field may have been corrupted. Therefore, the
size of the block is reduced so the block to be dumped fits within the
area.
|
|
Back link does not return to previous block
|
The back link in a doubly linked list does not point to the previous
block.
|
|
Forward link does not point to valid address
|
The forward link of current block points to a location that is not in
the virtual address space.
|
|
Free-fill mismatch
|
One of the locations filled when the block was freed has been modified.
|
|
Boundary tag mismatch
|
One of the boundary tags of the block is not valid.
|
| Warning |
Description |
|
Forward link of current block may not be valid
|
The back link of the block pointed to by the forward link of the
current block does not point to the current block.
|
|
Block at
nnnnnnnn is not accessible
|
The block at location
nnnnnnnn could not be accessed and cannot be dumped.
|
|
Block truncated to
nnnnnnnn bytes to prevent ACCVIO
|
The block to be dumped extends into the inaccessible part of the
address space. The size of the block is reduced so that the block to be
dumped fits within the accessible addresses.
|
When a block forward link is suspected of pointing to an invalid next
block, the information from the next block is replaced by asterisks.
The following is a sample error display:
**** ERROR -- forward-link does not point to valid address ****
Link Analysis for Current Block:
Previous Current Next
-------- -------- --------
Block adr : 0014B270 0014C200 6B6E754A
Forw link (abs): 0014C200 6B6E754A ********
Block size = 32
Block contents:
00000000 00000000 6B6E754A 00000020 ...Junk........ 00000 0014C200
0014B270 00000008 00000000 00000000 ............p².. 00010 0014C210
|
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_BADZONE
|
Invalid zone. Routine was called with a
zone-id that does not represent a valid VM zone.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory.
|
|
LIB$_INVARG
|
Invalid argument.
|
|
LIB$_INVOPEZON
|
Invalid operation for zone; invalid use of unspecified user zone action
routine.
|
|
LIB$_NOTFOU
|
Could not find another VM zone (alternate success status).
|
|
LIB$_WRONUMARG
|
Wrong number of arguments.
|
Any condition value returned by the user-formatted output action
routine or LIB$PUT_OUTPUT.
Examples
| #1 |
#include <lib$routines.h>
main()
{
long zone_id = 0;
long detail_level = 1;
LIB$SHOW_VM_ZONE(&zone_id, &detail_level);
}
|
An example of the output generated by this C program using
detail-level 1 is as follows:
Zone Id = 7FB96160, Zone name = "DEFAULT_ZONE"
Algorithm = LIB$K_VM_FIRST_FIT
Flags = 00000020
LIB$M_VM_EXTEND_AREA
Initial size = 124 pages Current size = 0 pages in 0 areas
Extend size = 128 pages Page limit = None
Requests are rounded up to a multiple of 8 bytes,
naturally aligned on 8 byte boundaries
0 bytes have been freed and not yet reallocated
72 bytes are used for zone and area control blocks, or 100.0% overhead
|
| #2 |
#include <descrip.h>
#include <libvmdef.h>
#include <lib$routines.h>
#include <stdlib.h>
main()
{
long zone_id;
long algorithm = LIB$K_VM_QUICK_FIT;
long algorithm_arg = 16;
long flags = LIB$M_VM_FREE_FILL0 | LIB$M_VM_EXTEND_AREA;
long detail_level = 3;
$DESCRIPTOR(zone_name, "Mix of lookaside list and area blocks");
int i;
#define NUM_BLOCKS 250
char *blocks[NUM_BLOCKS];
long sizes[NUM_BLOCKS];
LIB$CREATE_VM_ZONE(&zone_id, &algorithm, &algorithm_arg, &flags,
0, 0, 0, 0, 0, 0, /* Omitted arguments */
&zone_name, 0, 0);
for (i = 0; i < NUM_BLOCKS; i++)
{
sizes[i] = rand() % 300 + 9;
LIB$GET_VM(&sizes[i], &blocks[i], &zone_id);
}
for (i = 0; i < NUM_BLOCKS; i++)
LIB$FREE_VM(&sizes[i], &blocks[i], &zone_id);
LIB$SHOW_VM_ZONE(&zone_id, &detail_level);
}
|
|
