HP OpenVMS Systems Documentation

HP OpenVMS RTL Library (LIB$) Manual

The Trim a Full Name to Fit into a Desired Output Field routine trims a full name to fit into a desired output field. The trimming preserves the most significant part of the full 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$TRIM_FULLNAME fullname, trimmed-nodename [,output-width] [,resultant-length]

RETURNS

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

Arguments

fullname

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

Full name to be trimmed. The fullname argument contains the address of a descriptor pointing to this full name string.

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

trimmed-nodename

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

Trimmed node name. The trimmed-nodename argument contains the address of a descriptor pointing to the trimmed node-name string. LIB$TRIM_FULLNAME writes the trimmed node name into the buffer pointed to by trimmed-nodename.

The error LIB$_INVSTRDES is returned if trimmed-nodename is an invalid descriptor.

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

The trimmed-nodename argument contains an unusable result when LIB$TRIM_FULLNAME returns in error.

output-width

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

Field width desired for the trimmed node name. 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 trimmed-nodename is used. If trimmed-nodename is not a fixed-length string, specify output-width to ensure that the desired width is used.

If the lengths of both trimmed-nodename and output-width are specified, the length in output-width is used. In this case, if the current length of trimmed-nodename is smaller than the length of output-width, the output trimmed 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 trimmed 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$TRIM_FULLNAME returns in error.

Description

This routine trims a full name to the length that fits the desired output field. It allows applications to trim long full names for displaying in a fixed-length field, such as listing headers, in a consistent manner.

Full names are validated. Valid full names are defined as full names expanded from using LIB$EXPAND_NODENAME. A node name must be expanded to a full name using LIB$EXPAND_NODENAME before calling LIB$TRIM_FULLNAME. The error LIB$_INVARG is returned if the input full name is invalid.

If the length of fullname is less than or equal to the desired output width, no trimming is performed, and fullname is returned in trimmed-nodename. Trailing blanks are padded if necessary.

Trimming is performed when the length of fullname is larger than the desired output width. The alternate successful status LIB$_STRTRU is returned.

The trimmed node name contains the significant part of the full name. This allows the most important information of a full name to be retained for display purposes. The significant part of a full name is determined by the underlying network services.

In a DECnet environment, trimming a DECnet-Plus full name results in the error condition LIB$_INVARG.

If a usable short form of a node name is desired for display purposes, call LIB$COMPRESS_NODENAME first. If LIB$COMPRESS_NODENAME returns LIB$_STRTRU, LIB$TRIM_FULLNAME can then be used to return the trimmed node name.

LIB$TRIM_FULLNAME adds padding spaces to the end of the output buffer if the trimmed node name is shorter than the size of the output buffer. The argument resultant-length, if supplied, is set to the length of the trimmed 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 trimmed-nodename.
LIB$_INVARG	Invalid argument: fullname is invalid. fullname points to a null string. The length of the input full name is more than 1024 characters. The trimmed DECnet-Plus for OpenVMS node name is invalid in a DECnet for OpenVMS environment.
LIB$_INVSTRDES	Invalid string descriptor.
LIB$_WRONUMARG	Wrong number of arguments.

Any condition value returned by LIB$SCOPY_R_DX, or the $IPC DECnet service.

Examples

The following table gives some examples of the results of using LIB$TRIM_FULLNAME:

Full Name	Size of Output Field	Trimmed Node Name
NODE	3	NOD
NODE	8	NODE
DEC:.FOO.NODE	5	.NODE
DEC:.FOO.NODE	8	FOO.NODE
DEC:.FOO.NODE	20	DEC:.FOO.NODE

Alpha and I64 Only

Unlocks the specified image in the process's working set.

Format

LIB$UNLOCK_IMAGE address

RETURNS

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

Arguments

address

OpenVMS usage:	address
type:	quadword
access:	read only
mechanism:	by value

Address of a byte within the image to be unlocked in the working set. If the address argument is 0, the current image (which contains the call to LIB$UNLOCK_IMAGE) is unlocked in the working set.

Description

LIB$UNLOCK_IMAGE unlocks the specified image in the process's working set.

This routine is typically used by a privileged user after the program, executing in kernel mode, lowers IPL to 0 or 2. Above IPL 2, paging is not allowed by the system. The program must access only pages valid in the process's working set. LIB$LOCK_IMAGE is used to lock the image in the working set.

Condition Values Returned

SS$_WASSET	The specified image is unlocked in the working set and had previously been locked in the working set.
SS$_WASCLR	The specified image is unlocked in the working set and had previously not been locked in the working set.

Other status codes returned by sys$lkwset_64.

The Verify a Zone routine performs verification of a 32-bit zone.

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$VERIFY_VM_ZONE zone-id

RETURNS

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

Argument

zone-id

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

Zone identifier of the zone to be verified. The zone-id argument is the address of an unsigned longword that contains this zone identifier. A value of 0 indicates the 32-bit default zone.

Description

LIB$VERIFY_VM_ZONE verifies a zone. LIB$VERIFY_VM_ZONE performs verification of the zone header and scans all of the queues and lists maintained in the zone header; this includes the lookaside lists and the free lists. If the zone was created with LIB$M_VM_FREE_FILL0 or LIB$M_VM_FREE_FILL1, LIB$VERIFY_VM_ZONE also checks the contents of the free blocks.

As soon as an error is encountered, processing stops. If LIB$_BADZONE is returned, use the routine LIB$SHOW_VM_ZONE to dump the zone information.

You must have exclusive access to the zone while the verification is proceeding. Results are unpredictable if another thread of control modifies the zone while this routine is analyzing control data or scanning control blocks.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
LIB$_BADZONE	Invalid zone.
LIB$_INSVIRMEM	Insufficient virtual memory.
LIB$_INVARG	Invalid or null argument.
LIB$_WRONUMARG	Wrong number of arguments.

The Verify a Zone routine performs verification of a 64-bit zone.

Format

LIB$VERIFY_VM_ZONE_64 zone-id

RETURNS

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

Argument

zone-id

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

Zone identifier of the zone to be verified. The zone-id argument is the address of an unsigned quadword that contains this zone identifier. A value of 0 indicates the 64-bit default zone.

Description

LIB$VERIFY_VM_ZONE_64 verifies a zone. LIB$VERIFY_VM_ZONE_64 performs verification of the zone header and scans all of the queues and lists maintained in the zone header; this includes the lookaside lists and the free lists. If the zone was created with the LIB$M_VM_FREE_FILL0 or LIB$M_VM_FREE_FILL1 algorithm, LIB$VERIFY_VM_ZONE_64 also checks the contents of the free blocks.

As soon as an error is encountered, processing stops. If LIB$_BADZONE is returned, use the routine LIB$SHOW_VM_ZONE_64 to dump the zone information.

You must have exclusive access to the zone while the verification is proceeding. Results are unpredictable if another thread of control modifies the zone while this routine is analyzing control data or scanning control blocks.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
LIB$_BADZONE	Invalid zone.
LIB$_INVARG	Invalid or null argument.
LIB$_WRONUMARG	Wrong number of arguments.

The Wait a Specified Period of Time routine places the current process into hibernation for the number of seconds specified in its argument.

Format

LIB$WAIT seconds [,flags] [,float-type]

RETURNS

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

Arguments

seconds

OpenVMS usage:	floating_point
type:	F_floating
access:	read only
mechanism:	by reference

The number of seconds to wait. The seconds argument contains the address of an F-floating number that is this number.

The value is rounded to the nearest hundredth-second before use. Seconds must be between 0.0 and 100,000.0.

flags

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Control flags. The flags argument is the address of a longword integer that contains the control flags. The following flag is defined:

Bit	Value	Description
0	LIB$K_NOWAKE	LIB$WAIT will not wake in the case of an interrupt.

This is an optional argument. If omitted, the default is 0, and LIB$WAIT will wake in the case of an interrupt.

float-type

OpenVMS usage:	longword-unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Float type. The float-type argument is the address of a longword integer that determines the floating-point type of the seconds argument. Use one of the following symbols:

Symbol	Value	Floating-Point Type
LIB$K_VAX_F	0	F_floating
LIB$K_VAX_D	1	D_floating
LIB$K_VAX_G	2	G_floating
LIB$K_VAX_H	3	H_floating
LIB$K_IEEE_S	4	IEEE_S_floating
LIB$K_IEEE_T	5	IEEE_T_floating

This is an optional argument. If omitted, the default is F_floating. F_floating is the required float-type when LIB$WAIT is called from a module written in a language that prototypes functions.

Description

LIB$WAIT rounds the value specified by seconds to the nearest hundredth-second, uses the $SCHDWK system service to schedule a wakeup for that interval, and then issues the $HIBER system service to hibernate until the wakeup occurs.

Because of other system activity, the length of time that the process actually waits may be somewhat longer than what was specified by seconds.

The process hibernates in the caller's access mode; therefore, asynchronous system traps (ASTs) may be delivered while the process is hibernating. However, if the process hibernates at AST level, further ASTs can not be delivered.

When the LIB$K_NOWAIT control flag is used, LIB$WAIT makes use of the $SETIMR system service to schedule the wakeup, and then issues a $SYNCH system service call to check for the completion status. In this case, LIB$WAIT will not be interrupted by $WAKE. Use LIB$K_NOWAKE when it is necessary for the wait to be completed without interruption.

Note The NOWAKE option makes use of the $SETIMR and $SYNCH system services. Because use of these services requires that an AST be delivered, you should not use LIB$WAIT with the LIB$K_NOWAKE control flag at AST level.

See the HP OpenVMS System Services Reference Manual for more information.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
LIB$_INVARG	Invalid argument. The value of seconds was less than 0 or greater than 100,000.0
LIB$_WRONUMARG	Wrong number of arguments. An incorrect number of arguments was passed to LIB$WAIT.

Any condition values returned by the $SCHDWK or SETIMR system services, or by the RTL routine LIB$CVT_FTOF.

Example

IDENTIFICATION DIVISION.
PROGRAM-ID. T3.
DATA DIVISION.
WORKING-STORAGE SECTION.
01    WAIT-TIME    COMP-1.
01    FLOAT-TYPE   PIC 9(5) COMP VALUE 0.
PROCEDURE DIVISION.
p0.    MOVE 10 TO WAIT-TIME.
       CALL "LIB$WAIT"
       USING BY REFERENCE WAIT_TIME, OMITTED,
             BY REFERENCE FLOAT-TYPE.
       STOP RUN.




      

This COBOL program demonstrates the use of LIB$WAIT on both OpenVMS VAX and OpenVMS Alpha and I64 systems. When run, the process performs a 10 second wait.