Updated: 11 December 1998

OpenVMS RTL Library (LIB$) Manual

The Return the Next Valid Zone Identifier routine returns the zone identifier of the next valid zone in the heap management 32-bit database.

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$FIND_VM_ZONE context ,zone-id

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Arguments

context

OpenVMS usage:	context
type:	longword (unsigned)
access:	modify
mechanism:	by reference

Context specifier. The context argument is the address of an unsigned longword used to keep the scan context for finding the next valid zone. The context argument must be 0 to initialize the scan and to start with the first returnable zone identifier.

zone-id

OpenVMS usage:	identifier
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Zone identifier. The zone-id argument is the address of an unsigned longword that receives the zone identifier for the next zone.

Description

At each call, LIB$FIND_VM_ZONE scans the heap management 32-bit zone database and returns the zone-id of the next valid zone. (The first and second calls to LIB$FIND_VM_ZONE return the zone-id of the 32-bit default zone and the 32-bit string zone, respectively.) This capability allows a program to deal with each 32-bit VM zone created during the invocation, including those created outside of the program.

Note LIB$FIND_VM_ZONE finds only 32-bit zones. You must use LIB$FIND_VM_ZONE and LIB$FIND_VM_ZONE_64 to loop through all VM zones.

The context argument controls the state of the scan. It determines what zone to return (the first, the next, and so forth). On the initial call, specified by context=0, LIB$VERIFY_VM_ZONE is called to verify the heap management zone database. If the database is corrupt, further calls to this routine will produce no additional useful output.

When no more zones can be found, the routine returns the condition value LIB$_NOTFOU.

If a zone has been corrupted in some major way (for example, if the validity code has been changed), then this routine may not be able to locate it in the zone database.

Note that ASTs may be disabled while LIB$FIND_VM_ZONE is executing code that depends on the stability of the heap management zone database. In general it is the caller's responsibility to ensure that the calling program has exclusive access to the zone database while scanning for multiple zones with this routine. Results are unpredictable if another thread of control modifies the zone database or the associated areas during the scanning.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
LIB$_BADZONE	Invalid zone.
LIB$_NOTFOU	Zone identifier not found (alternate success status).
LIB$_WRONUMARG	Wrong number of arguments.

Example

IMPLICIT NONE 
INTEGER*4 status,context,zone_id 
INTEGER*4 lib$find_vm_zone,lib$show_vm_zone 
 
context = 0 
status = lib$find_vm_zone (context, zone_id) 
DO WHILE (status) 
    print * 
    status = lib$show_vm_zone (zone_id, 0) 
    status = lib$find_vm_zone (context, zone_id) 
END DO 
END 
 
      

Sample output for this Fortran program is shown below:

Zone Id = 00020020, Zone name = "DEFAULT_ZONE" Zone Id = 000200B0, Zone name = "STRING_ZONE"

The Return the Next Valid Zone Identifier routine returns the zone identifier of the next valid zone in the heap management 64-bit database.

Format

LIB$FIND_VM_ZONE_64 context ,zone-id

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Arguments

context

OpenVMS usage:	context
type:	quadword (unsigned)
access:	modify
mechanism:	by reference

Context specifier. The context argument is the address of an unsigned quadword used to keep the scan context for finding the next valid zone. The context argument must be 0 to initialize the scan and to start with the first returnable zone identifier.

zone-id

OpenVMS usage:	identifier
type:	quadword (unsigned)
access:	write only
mechanism:	by reference

Zone identifier. The zone-id argument is the address of an unsigned quadword that receives the zone identifier for the next zone.

Description

At each call, LIB$FIND_VM_ZONE_64 scans the heap management 64-bit zone database and returns the zone-id of the next valid zone. (The first and second calls to LIB$FIND_VM_ZONE_64 return the zone-id of the 64-bit default zone and the 64-bit string zone, respectively.) This capability allows a program to deal with each VM 64-bit zone created during the invocation, including those created outside of the program.

Note LIB$FIND_VM_ZONE_64 finds only 64-bit zones. You must use LIB$FIND_VM_ZONE and LIB$FIND_VM_ZONE_64 to loop through all VM zones.

The context argument controls the state of the scan. It determines what zone to return (the first, the next, and so forth). On the initial call, specified by context=0, LIB$VERIFY_VM_ZONE_64 is called to verify the heap management zone database. If the database is corrupt, further calls to this routine will produce no additional useful output.

When no more zones can be found, the routine returns the condition value LIB$_NOTFOU.

If a zone has been corrupted in some major way (for example, if the validity code has been changed), then this routine may not be able to locate it in the zone database.

Note that ASTs may be disabled while LIB$FIND_VM_ZONE_64 is executing code that depends on the stability of the heap management zone database. In general it is the caller's responsibility to ensure that the calling program has exclusive access to the zone database while scanning for multiple zones with this routine. Results are unpredictable if another thread of control modifies the zone database or the associated areas during the scanning.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
LIB$_BADZONE	Invalid zone.
LIB$_NOTFOU	Zone identifier not found (alternate success status).
LIB$_WRONUMARG	Wrong number of arguments.

Example

IMPLICIT NONE 
INTEGER*4 status 
INTEGER*8 context,zone_id 
INTEGER*4 lib$find_vm_zone_64,lib$show_vm_zone_64 
 
context = 0 
status = lib$find_vm_zone_64 (context, zone_id) 
DO WHILE (status) 
    print * 
    status = lib$show_vm_zone_64 (zone_id, 0) 
    status = lib$find_vm_zone_64 (context, zone_id) 
END DO 
END 
 
      

Sample output for this Fortran program is as follows:

Zone Id = 0000000000020040, Zone name = "DEFAULT_ZONE" Zone Id = 0000000000020140, Zone name = "STRING_ZONE"

The Fit a Node Name Into an Output Field routine fits a node name into an output field. It attempts to compress the node name to fit the output field. If this fails, it trims the node name.

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$FIT_NODENAME nodename, output-buffer [,output-width][,resultant-length]

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Arguments

nodename

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Node name to be fitted into the desired output field. The nodename argument contains the address of a descriptor pointing to this node-name string.

The error LIB$_INVARG is returned if nodename contains an invalid node name, points to a null string, or contains more than 1024 characters. The error LIB$_INVSTRDES is returned if nodename is an invalid descriptor.

output-buffer

OpenVMS usage:	char_string
type:	character string
access:	write only
mechanism:	by descriptor

The output buffer. The output-buffer argument contains the address of a descriptor pointing to the output buffer. LIB$FIT_NODENAME writes the final output node name into the buffer pointed to by output-buffer.

The error LIB$_INVSTRDES is returned if output-buffer is an invalid descriptor.

The length field of the output-buffer descriptor is not updated unless output-buffer is a dynamic descriptor with a length less than the resulting fitted node name. Refer to the OpenVMS RTL String Manipulation (STR$) Manual for dynamic string descriptor usage.

The output-buffer argument contains an unusable result when LIB$FIT_NODENAME returns in error.

output-width

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	read only
mechanism:	by reference

Field width desired for the fit operation. The output-width argument is the address of an unsigned word that contains this field width in bytes.

If output-width is omitted, the current length of output-buffer is used. If output-buffer is not a fixed-length string, specify output-width to ensure that the desired width is used.

If the lengths of both output-buffer and output-width are specified, the length in output-width is used. In this case, if the current length of output-buffer is smaller than the length of output-width, the output node name is truncated at the end, and the alternate successful status LIB$_STRTRU is returned.

resultant-length

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference

Length of the output node name. The resultant-length argument is the address of an unsigned word that contains this length in bytes.

The resultant-length argument contains an unusable result when LIB$FIT_NODENAME returns in error.

Description

This routine fits the input node name into the desired output field for display purposes. It first attempts to get the usable short form of the input node name by calling LIB$COMPRESS_NODENAME. If that fails, the input node name is expanded by LIB$EXPAND_NODENAME and then trimmed by LIB$TRIM_FULLNAME to fit the desired output width.

The input is validated against the supported form of input node names. The error LIB$_INVARG is returned if the input node name is invalid.

Node-name compression is always attempted even if the length of the input node name is less than or equal to the desired output width. This is to ensure that the short form of a full name is always chosen for display purposes.

When the compressed node name is too long to fit the desired output width, the input node name is expanded using LIB$EXPAND_NODENAME and trimmed using LIB$TRIM_FULLNAME. In this case, the alternate success status LIB$_STRTRU is returned.

When LIB$FIT_NODENAME encounters errors from the underlying network services, it tries to return the string-truncated compressed node name. If it is the compression operation that fails, LIB$FIT_NODENAME returns the string-truncated input node name. The alternate successful status LIB$_STRTRU is returned.

Note that the returned node name can be either a compressed usable short form of the input node name or an unusable trimmed or truncated node name. The caller should always assume an unusable node name is returned when it finds the alternate success return status LIB$_STRTRU. On the other hand, the SS$_NORMAL return status means that a usable form of a node name is returned.

LIB$FIT_NODENAME adds padding spaces to the end of the output buffer if the output node name is shorter than the size of the output buffer. The argument resultant-length, if supplied, is set to the length of the output node name, excluding any padding spaces.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
LIB$_STRTRU	Routine successfully completed. Characters are truncated in the output buffer pointed to by output-buffer.
LIB$_INVARG	Invalid argument: nodename is invalid. nodename points to a null string. The length of the node name is more than 1024 characters.
LIB$_INVSTRDES	Invalid string descriptor.
LIB$_WRONUMARG	Wrong number of arguments.

Any condition value returned by LIB$SCOPY_R_DX.

The Fix Floating Reserved Operand routine finds the reserved operand of any F-floating, D-floating, G-floating, or H-floating instruction (with some exceptions) after a reserved operand fault has been signaled.+ LIB$FIXUP_FLT changes the reserved operand from --0.0 to the value of the new-operand argument, if present; or to +0.0 if new-operand is absent.

This routine is available on OpenVMS Alpha systems in translated form and is applicable to translated VAX images only.

Format

LIB$FIXUP_FLT signal-arguments ,mechanism-arguments [,new-operand]

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Arguments

signal-arguments

OpenVMS usage:	vector_longword_unsigned
type:	unspecified
access:	read only
mechanism:	by reference, array reference

Signal argument vector. The signal-arguments argument is the address of an array of unsigned longwords containing the signal argument vector.

mechanism-arguments

OpenVMS usage:	vector_longword_unsigned
type:	unspecified
access:	read only
mechanism:	by reference, array reference

Mechanism argument vector. The mechanism-arguments argument is the address of an array of unsigned longwords containing the mechanism argument vector.

new-operand

OpenVMS usage:	floating-point
type:	F_floating
access:	read only
mechanism:	by reference

An F-floating value to replace the reserved operand. The new-operand argument is the address of an F-floating number containing the new operand. This is an optional argument. If omitted, the default value is +0.0.

Description

LIB$FIXUP_FLT finds the reserved operand of any F-floating, D-floating, G-floating, or H-floating instruction (with some exceptions) after a reserved operand fault has been signaled. LIB$FIXUP_FLT changes the reserved operand from --0.0 to the value of the new-operand argument, if present; or to +0.0 if new-operand is absent. LIB$FIXUP_FLT cannot handle the following cases and will return a status of SS$_RESIGNAL if any of them occur:

• The currently active signaled condition is not SS$_ROPRAND.
• The reserved operand's data type is not F-floating, D-floating, G-floating, or H-floating.
• The reserved operand is an element in the coefficient table for one of the VAX POLYx instructions.

If the status value returned from LIB$FIXUP_FLT is seen by the condition handling facility (as would be the case if LIB$FIXUP_FLT was the handler), any success value is equivalent to SS$_CONTINUE, which causes the instruction to be restarted. Any failure value is equivalent to SS$_RESIGNAL, which causes the condition to be resignaled to the next handler. This resignal status is because the condition handler (LIB$FIXUP_FLT) was unable to handle the condition correctly.

LIB$FIXUP_FLT can be enabled directly as a condition handler. The signal-arguments and mechanism-arguments arguments are passed to the condition handler by OpenVMS exception dispatching.

Condition Values Returned

SS$_NORMAL	Routine successfully completed. The reserved operand was found and has been fixed.
SS$_ACCVIO	Access violation. An argument to LIB$FIXUP_FLT or an operand of the faulting instruction could not be read or written.
SS$_RESIGNAL	The signaled condition was not SS$_ROPRAND, or the reserved operand was not a floating-point value or was an element in a POLY x table.
SS$_ROPRAND	Reserved operand fault. The optional argument new-operand was supplied but was itself an F-floating reserved operand.
LIB$_BADSTA	Bad stack. The stack frame linkage has been corrupted since the time of the reserved operand exception.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5932PRO_017.HTML