Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

Previous | 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:

> 1. Node (including access control)
> 2. Device
> 3. Directory
> 4. Version
> 5. 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.

> 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

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

Previous | Next | Contents | Index

| privacy and legal statement |
5932PRO_050.HTML