OpenVMS RTL Library (LIB$) Manual

Document revision date: 30 March 2001

OpenVMS RTL Library (LIB$) Manual

Contents

Index

LIB$TRA_EBC_ASC

The Translate EBCDIC to ASCII routine translates an EBCDIC string to an ASCII string.

Format

LIB$TRA_EBC_ASC byte-integer-source-string ,destination-string

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: read only

mechanism: by value

Arguments

byte-integer-source-string

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

String (EBCDIC) to be translated by LIB$TRA_EBC_ASC. The byte-integer-source-string argument contains the address of a descriptor pointing to this source string.
destination-string

OpenVMS usage: char_string

type: character string

access: write only

mechanism: by descriptor

Destination string (ASCII). The destination-string argument contains the address of the descriptor of this destination string.
The LIB$TRA_EBC_ASC routine uses the EBCDIC to ASCII translation table, LIB$AB_EBC_ASC.

Description

LIB$TRA_EBC_ASC translates an EBCDIC string to an ASCII string. If the destination string is a fixed-length string, its length must match the length of the input string. The length of both the source and destination strings is limited to 65,535 characters. No filling is done.
A similar operation can be accomplished by specifying the EBCDIC to ASCII translation table, LIB$AB_EBC_ASC, in a routine using LIB$MOVTC, but no testing for untranslatable characters is done under these circumstances.
The LIB$TRA_EBC_ASC routine uses the EBCDIC to ASCII translation shown in Figure lib-26.
Figure lib-26 LIB$AB_EBC_ASC

EBCDIC to ASCII Translation Table

The numbers on the left represent the low-order bits of the EBCDIC characters in hexadecimal notation.
The numbers across the top represent the high-order bits of the EBCDIC characters in hexadecimal notation.
The numbers in the body of the table represent the equivalent ASCII characters in hexadecimal notation.

All EBCDIC graphics are translated to their equivalent ASCII graphic except for the graphics noted in Figure lib-27.

Figure lib-27 EBCDIC Graphics Not Translated to ASCII Equivalent by LIB$TRA_EBC_ASC

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_INVARG If the destination string is a fixed-length string and its length is not the same as the source string length, or if the length of the input string is greater than 65,535 characters, no translation is attempted.

LIB$_INVCHA One or more occurrences of an untranslatable character have been detected during the translation.

LIB$TRIM_FILESPEC

The Fit Long File Specification into Fixed Field routine takes a file specification, such as an OpenVMS RMS resultant name string, and shortens it (if necessary) so that it fits into a field of fixed width.

Format

LIB$TRIM_FILESPEC old-filespec ,new-filespec [,word-integer-width] [,resultant-length]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

old-filespec

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

File specification to be trimmed. The old-filespec argument contains the address of a descriptor pointing to this file specification string.
The file specification should be an RMS resultant name string.
new-filespec

OpenVMS usage: char_string

type: character string

access: write only

mechanism: by descriptor

Trimmed file specification. The new-filespec argument contains the address of a descriptor pointing to this trimmed file specification string. LIB$TRIM_FILESPEC writes the trimmed file specification into new-filespec.
word-integer-width

OpenVMS usage: word_unsigned

type: word (unsigned)

access: read only

mechanism: by reference

Maximum field width desired. The word-integer-width argument is the address of an unsigned word that contains this maximum field width.
If omitted, the current length of new-filespec is used. If new-filespec is not a fixed-length string, you should specify word-integer-width to ensure that the desired width is used.
resultant-length

OpenVMS usage: word_unsigned

type: word (unsigned)

access: write only

mechanism: by reference

Length of the trimmed file specification, not including any blank padding or truncated characters. The resultant-length argument is the address of an unsigned word that contains this length. This is an optional argument.

Description

This routine trims file specifications in a consistent, predictable manner to fit in a fixed-length field using the same algorithm that Compaq software uses.
LIB$TRIM_FILESPEC allows compilers and other utilities which need to display file specifications in fixed-length fields, such as listing headers, to display file specifications in a consistent fashion.
If necessary to make the file specification fit into the specified field width, LIB$TRIM_FILESPEC removes portions of the file specification in this order:

Node (including access control)
Device
Directory
Version
Type

If, after removing all these fields, the file name is still longer than the field width, the file name is truncated and the alternate success status LIB$_STRTRU is returned.
LIB$TRIM_FILESPEC supports any string class for the old-filespec and new-filespec string arguments.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_STRTRU Success, but the output string was truncated. Significant characters of the trimmed file specification were truncated.

LIB$_INVSTRDES Invalid string descriptor.

LIB$_WRONUMARG Wrong number of arguments.

Any condition values returned by LIB$SCOPY_R_DX, or the $FILESCAN system service.

Example


PROGRAM TRIM_FILESPEC(INPUT,OUTPUT); {+} { This PASCAL example program demonstrates the { use of LIB$TRIM_FILESPEC. {-} TYPE WORD = [WORD] 0..65535; VAR INPUT_FILESPEC : VARYING [255] OF CHAR; OUTPUT_FILESPEC : VARYING [32] OF CHAR; RETURNED_STATUS : INTEGER; [EXTERNAL] FUNCTION LIB$TRIM_FILESPEC( IN_FILE : VARYING [LEN1] OF CHAR; VAR OUT_FILE : VARYING [LEN2] OF CHAR; WIDTH : WORD := %IMMED 0; OUT_LEN : [REFERENCE] WORD := %IMMED 0 ) : INTEGER; EXTERNAL; [EXTERNAL] FUNCTION LIB$STOP( CONDITION_STATUS : [IMMEDIATE,UNSAFE] UNSIGNED; FAO_ARGS : [IMMEDIATE,UNSAFE,LIST] UNSIGNED ) : INTEGER; EXTERNAL; BEGIN {+} { Start with a large INPUT_FILESPEC. {-} INPUT_FILESPEC := 'DISK$NAME:[DIRECTORY1.DIRECTORY2]FILENAME.EXTENSION;1'; {+} { Use LIB$TRIM_FILESPEC to shorten it to fit a smaller variable. {-} RETURNED_STATUS := LIB$TRIM_FILESPEC( INPUT_FILESPEC, OUTPUT_FILESPEC, SIZE(OUTPUT_FILESPEC.BODY)); IF NOT ODD(RETURNED_STATUS) THEN LIB$STOP(RETURNED_STATUS); {+} { Print out the original file name along with the { shortened file name. {-} WRITELN('Original file specification ',INPUT_FILESPEC); WRITELN('Shortened file specification ',OUTPUT_FILESPEC); END.

PROGRAM TRIM_FILESPEC(INPUT,OUTPUT); 
 
{+} 
{ This PASCAL example program demonstrates the 
{ use of LIB$TRIM_FILESPEC. 
{-} 
 
    TYPE 
        WORD = [WORD] 0..65535; 
 
    VAR 
        INPUT_FILESPEC  : VARYING [255] OF CHAR; 
        OUTPUT_FILESPEC : VARYING [32] OF CHAR; 
        RETURNED_STATUS : INTEGER; 
 
    [EXTERNAL] FUNCTION LIB$TRIM_FILESPEC( 
        IN_FILE      : VARYING [LEN1] OF CHAR; 
        VAR OUT_FILE : VARYING [LEN2] OF CHAR; 
        WIDTH        : WORD := %IMMED 0; 
        OUT_LEN      : [REFERENCE] WORD := %IMMED 0 
        ) : INTEGER; EXTERNAL; 
 
    [EXTERNAL] FUNCTION LIB$STOP( 
          CONDITION_STATUS : [IMMEDIATE,UNSAFE] UNSIGNED; 
          FAO_ARGS         : [IMMEDIATE,UNSAFE,LIST] UNSIGNED 
          ) : INTEGER; EXTERNAL; 
 
BEGIN 
 
{+} 
{ Start with a large INPUT_FILESPEC. 
{-} 
 
INPUT_FILESPEC := 'DISK$NAME:[DIRECTORY1.DIRECTORY2]FILENAME.EXTENSION;1'; 
 
{+} 
{ Use LIB$TRIM_FILESPEC to shorten it to fit a smaller variable. 
{-} 
 
RETURNED_STATUS := LIB$TRIM_FILESPEC( 
                      INPUT_FILESPEC, 
                      OUTPUT_FILESPEC, 
                      SIZE(OUTPUT_FILESPEC.BODY)); 
IF NOT ODD(RETURNED_STATUS) 
THEN 
    LIB$STOP(RETURNED_STATUS); 
 
{+} 
{ Print out the original file name along with the 
{ shortened file name. 
{-} 
 
WRITELN('Original file specification  ',INPUT_FILESPEC); 
WRITELN('Shortened file specification ',OUTPUT_FILESPEC); 
 
END.

This Pascal example program demonstrates the use of LIB$TRIM_FILESPEC. The output generated by this program is as follows:
Original file specification DISK$NAME:[DIRECTORY1.DIRECTORY2]FILENAME.EXTENSION;1 Shortened file specification FILENAME.EXTENSION;1

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

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$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 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.

Contents

Index

privacy and legal statement

5932PRO_050.HTML

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

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

SS$_NORMAL	Routine successfully completed.
LIB$_INVARG	If the destination string is a fixed-length string and its length is not the same as the source string length, or if the length of the input string is greater than 65,535 characters, no translation is attempted.
LIB$_INVCHA	One or more occurrences of an untranslatable character have been detected during the translation.

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

SS$_NORMAL	Routine successfully completed.
LIB$_STRTRU	Success, but the output string was truncated. Significant characters of the trimmed file specification were truncated.
LIB$_INVSTRDES	Invalid string descriptor.
LIB$_WRONUMARG	Wrong number of arguments.

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

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.