 |
HP OpenVMS RTL Library (LIB$) Manual
LIB$SGET1_DD_64 (Alpha and I64 Only)
The Get One Dynamic String routine allocates dynamic virtual memory to
the string descriptor you specify.
Format
LIB$SGET1_DD_64 quad-integer-length ,descriptor-part
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
quad-integer-length
| OpenVMS usage: |
quadword_unsigned |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Number of bytes of dynamic virtual memory to be allocated by
LIB$SGET1_DD_64. The quad-integer-length argument is
the address of an unsigned quadword that contains this number. The
amount of storage allocated can be rounded up automatically.
descriptor-part
| OpenVMS usage: |
quadword_unsigned |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Descriptor of the dynamic string to which LIB$SGET1_DD_64 allocates the
dynamic virtual memory. The descriptor-part argument
contains the address of this descriptor.
The descriptor-part argument must contain the address
of a dynamic string descriptor; LIB$SGET1_DD_64 returns an
unpredictable result if any other type of descriptor is specified by
this argument.
The descriptor CLASS field is not checked but is set to dynamic (2).
The LENGTH field is set to quad-integer-length, and
the POINTER field points to the string area allocated.
Description
LIB$SGET1_DD_64 is similar to LIB$SCOPY_DXDX except that no source
string is copied. You can write anything you want in the allocated area.
If descriptor-part already has dynamic memory
allocated to it, but the amount allocated is less than
quad-integer-length, that space is deallocated before
LIB$SGET1_DD_64 allocates new space.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_FATERRLIB
|
Fatal internal error. An internal consistency check has failed. This
usually indicates an internal error in the Run-Time Library and should
be reported to your HP support representative.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory. Your program has exceeded the image quota
for virtual memory.
|
LIB$SHOW_TIMER
The Show Accumulated Times and Counts routine returns times and counts
accumulated since the last call to LIB$INIT_TIMER and displays them on
SYS$OUTPUT. (LIB$INIT_TIMER must be called prior to invoking this
routine.) A user-supplied action routine may change this default
behavior.
Format
LIB$SHOW_TIMER [handle-address] [,code] [,user-action-procedure]
[,user-argument-value]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
handle-address
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Block of storage containing the value returned by a previous call to
LIB$INIT_TIMER. The handle-address argument is the
address of an unsigned longword integer containing that value.
- If specified, the pointer must be the same value returned by a
previous call to LIB$INIT_TIMER.
- If omitted, LIB$SHOW_TIMER will use a block of memory allocated by
LIB$INIT_TIMER.
- If handle-address is omitted and LIB$INIT_TIMER
has not been called previously, the error LIB$_INVARG is returned.
LIB$INIT_TIMER must be called prior to a call to LIB$SHOW_TIMER.
LIB$SHOW_TIMER assumes that LIB$INIT_TIMER has been previously called,
and that the results of that call are stored either in a block pointed
to by handle-address, or in the memory allocated by
LIB$INIT_TIMER.
Note that the handle-address argument is the same as
the context argument used in the LIB$INIT_TIMER call.
code
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Integer specifying the statistic you want; if it is omitted or zero,
all five statistics are returned on one line. The code
argument is the address of a signed longword integer containing the
statistic code.
The following values are allowed for the code argument:
| Value |
Description |
|
1
|
Elapsed time
|
|
2
|
CPU time
|
|
3
|
Buffered I/O
|
|
4
|
Direct I/O
|
|
5
|
Page faults
|
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_TIMER. The default
action of LIB$SHOW_TIMER is to write the results to SYS$OUTPUT. An
action routine is useful if you want to write the results to a file or,
in general, anywhere other than SYS$OUTPUT.
The action routine returns either a success or failure condition value;
this status is returned to the calling program as the value of
LIB$SHOW_TIMER.
user-argument-value
| OpenVMS usage: |
user-arg |
| type: |
longword (unsigned) (on VAX systems)
quadword
(unsigned) (on Alpha and I64 systems) |
| access: |
read only |
| mechanism: |
by value |
A value to be passed to the action routine without interpretation. If
omitted, LIB$SHOW_TIMER passes a zero by value to the user routine.
Description
LIB$SHOW_TIMER returns the times and counts accumulated since the last
call to LIB$INIT_TIMER. By default, when neither code
nor user-action-procedure is specified in the call,
LIB$SHOW_TIMER writes to SYS$OUTPUT a line giving the following
information:
| Shown on Line |
Description |
|
ELAPSED = dddd hh:mm:ss.cc
|
Elapsed real time
|
|
CPU = hhhh:mm:ss.cc
|
Elapsed CPU time
|
|
BUFIO = nnnn
|
Count of buffered I/O operations
|
|
DIRIO = nnnn
|
Count of direct I/O operations
|
|
PAGEFAULTS = nnnn
|
Count of page faults
|
Any one or all five statistics can be written to SYS$OUTPUT or passed
to your user-supplied action routine for other processing.
Call Format for an Action Routine
Action routine is a user-supplied routine called by LIB$SHOW_TIMER. The
action routine is used when you want to write results to anywhere other
than SYS$OUTPUT. The action routine is called only when you specify the
user-action-procedure argument in the call to
LIB$SHOW_TIMER.
LIB$SHOW_TIMER calls the action routine using this format:
user-action-procedure out-str [,user-argument-value]
|
out-str
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Fixed-length string containing the statistics requested. The string is
formatted exactly as it would be if written to SYS$OUTPUT. The leading
character is blank.
user-argument-value
| OpenVMS usage: |
user-arg |
| type: |
longword (unsigned) (on VAX systems)
quadword
(unsigned) (on Alpha and I64 systems) |
| access: |
read only |
| mechanism: |
by value |
A value passed to LIB$SHOW_TIMER. The user argument is passed without
interpretation to the action routine.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_INVARG
|
Invalid argument. Either
code or
handle-address was invalid.
|
Any condition values returned by LIB$PUT_OUTPUT or your action routine.
Example
|
PROGRAM SHOW_TIMER(INPUT,OUTPUT);
{+}
{ This Pascal example demonstrates how to use LIB$SHOW_TIMER.
{-}
VAR
RETURNED_STATUS : INTEGER;
[EXTERNAL] FUNCTION LIB$INIT_TIMER(
HANDLE_ADR : [REFERENCE] UNSIGNED := %IMMED 0
) : INTEGER; EXTERNAL;
[EXTERNAL] FUNCTION LIB$SHOW_TIMER(
HANDLE_ADR : [REFERENCE] UNSIGNED := %IMMED 0;
CODE : INTEGER;
[IMMEDIATE,UNBOUND]
ROUTINE ACTION_RTN( OUT_STR : [CLASS_S] PACKED ARRAY [L..U:INTEGER] OF CHAR;
USER_ARG : INTEGER) := %IMMED 0;
USER_ARG : INTEGER := %IMMED 0
) : INTEGER; EXTERNAL;
[EXTERNAL] FUNCTION LIB$STOP(
CONDITION_STATUS : [IMMEDIATE,UNSAFE] UNSIGNED;
FAO_ARGS : [IMMEDIATE,UNSAFE,LIST] UNSIGNED
) : INTEGER; EXTERNAL;
ROUTINE USER_ACTION_RTN(
OUT_STR : [CLASS_S] PACKED ARRAY [L..U:INTEGER] OF CHAR;
USER_ARG : INTEGER);
BEGIN
WRITELN('User argument is ',USER_ARG:1);
WRITELN(OUT_STR);
END;
BEGIN
{+}
{ Call LIB$INIT_TIMER to initialize RTL internal counters.
{-}
RETURNED_STATUS := LIB$INIT_TIMER;
IF NOT ODD(RETURNED_STATUS)
THEN
LIB$STOP(RETURNED_STATUS);
{+}
{ Print a line of text to waste time.
{-}
WRITELN('Spend time to acquire elapsed real time and page faults');
{+}
{ Call LIB$SHOW_TIMER to display counters.
{-}
RETURNED_STATUS := LIB$SHOW_TIMER(,0,USER_ACTION_RTN,5);
END.
|
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 and I64 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 or I64 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.
|
