HP OpenVMS RTL Library (LIB$) Manual
LIB$TRIM_FULLNAME
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
|
LIB$UNLOCK_IMAGE (Alpha and I64 Only)
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.
LIB$VERIFY_VM_ZONE
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.
|
LIB$VERIFY_VM_ZONE_64 (Alpha and I64 Only)
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.
|
LIB$WAIT
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.
|
