hp.com home products and services support and drivers solutions how to buy
cd-rom home
End of Jump to page title
HP OpenVMS systems
documentation

Jump to content


HP OpenVMS RTL Library (LIB$) Manual

HP OpenVMS RTL Library (LIB$) Manual


Previous Contents Index


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.

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.


Previous Next Contents Index