|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
The Get One Dynamic String routine allocates dynamic virtual memory to the string descriptor you specify.
LIB$SGET1_DD_64 quad-integer-length ,descriptor-part
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
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.
LIB$SHOW_TIMER [handle-address] [,code] [,user-action-procedure] [,user-argument-value]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
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
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.
LIB$SHOW_VM [code] [,user-action-procedure] [,user-specified-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 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.
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 allocatedOptionally, 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.
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.
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.
LIB$SHOW_VM_64 [code] [,user-action-procedure] [,user-specified-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 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.
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 allocatedOptionally, 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.
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.
| Previous | Next | Contents | Index |