|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
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.
LIB$TRIM_FULLNAME fullname, trimmed-nodename [,output-width] [,resultant-length]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
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.
LIB$UNLOCK_IMAGE address
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
LIB$VERIFY_VM_ZONE zone-id
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
LIB$VERIFY_VM_ZONE_64 zone-id
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
LIB$WAIT seconds [,flags] [,float-type]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
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.
| Previous | Next | Contents | Index |