HP OpenVMS RTL Library (LIB$) Manual

Contents

Index

LIB$TRAVERSE_TREE

The Traverse a Balanced Binary Tree routine calls an action routine for each node in a binary tree.

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$TRAVERSE_TREE treehead ,user-action-procedure [,user-data-address]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

treehead

OpenVMS usage: address

type: address

access: read only

mechanism: by reference

Tree head of the binary tree. The treehead argument is the address of an unsigned longword that is the tree head in the binary tree traversal.
user-action-procedure

OpenVMS usage: procedure

type: procedure value

access: function call (before return)

mechanism: by value

User-supplied action routine called by LIB$TRAVERSE_TREE for each node in the tree. The user-action-procedure argument must return a success status for LIB$TRAVERSE_TREE to continue traversal.
For more information, see Call Format for an Action Routine in the Description section.
user-data-address

OpenVMS usage: user_arg

type: longword (unsigned)

access: read only

mechanism: by reference

User data that LIB$TRAVERSE_TREE passes to your action routine. The user-data-address argument contains the address of this user data. This is an optional argument; the default value is 0.

Description

LIB$TRAVERSE_TREE calls a user-supplied action routine for each node to traverse a balanced binary tree.
Call Format for an Action Routine

The format of the call is as follows:

user-action-procedure node ,user-data-address

LIB$TRAVERSE_TREE passes the node and user-data-address arguments to your action routine by reference.
This action routine is defined by you to fit your own purposes. A common use of an action routine here is to print the contents of each node during the tree traversal.
The following is one example of a user-supplied action routine.
struct Full_node { void* left_link; void* right_link; short reserved; char Text[80]; }; static long Print_Node(struct Full_node* Node, void* dummy) { /* ** Print the string contained in the current node */ printf("%s\n", Node->Text); return LIB$_NORMAL; }

Condition Values Returned

LIB$_NORMAL Routine successfully completed.

Any condition value returned by your action routine.

Example

The C example provided in the description of LIB$INSERT_TREE also demonstrates the use of LIB$TRAVERSE_TREE. Refer to that example for assistance in using this routine.

LIB$TRAVERSE_TREE_64 (Alpha and I64 Only)

The Traverse a Balanced Binary Tree routine calls an action routine for each node in a binary tree.

Format

LIB$TRAVERSE_TREE_64 treehead ,user-action-procedure [,user-data-address]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

treehead

OpenVMS usage: address

type: address

access: read only

mechanism: by reference

Tree head of the binary tree. The treehead argument is the address of an unsigned quadword that is the tree head in the binary tree traversal.
user-action-procedure

OpenVMS usage: procedure

type: procedure value

access: function call (before return)

mechanism: by value

User-supplied action routine called by LIB$TRAVERSE_TREE_64 for each node in the tree. The user-action-procedure argument must return a success status for LIB$TRAVERSE_TREE_64 to continue traversal.
For more information, see Call Format for an Action Routine in the Description section.
user-data-address

OpenVMS usage: user_arg

type: quadword (unsigned)

access: read only

mechanism: by reference

User data that LIB$TRAVERSE_TREE_64 passes to your action routine. The user-data-address argument contains the address of this user data. This is an optional argument; the default value is 0.

Description

LIB$TRAVERSE_TREE_64 calls a user-supplied action routine for each node to traverse a balanced binary tree.
Call Format for an Action Routine

The format of the call is as follows:

user-action-procedure node ,user-data-address

LIB$TRAVERSE_TREE_64 passes the node and user-data-address arguments to your action routine by reference.
This action routine is defined by you to fit your own purposes. A common use of an action routine here is to print the contents of each node during the tree traversal.
The following is one example of a user-supplied action routine.
struct Full_node { void* left_link; void* right_link; short reserved; char Text[80]; }; static long Print_Node(struct Full_node* Node, void* dummy) { /* ** Print the string contained in the current node */ printf("%s\n", Node->Text); return LIB$_NORMAL; }

Condition Values Returned

LIB$_NORMAL Routine successfully completed.

Any condition value returned by your action routine.

Example

The C example provided in the description of LIB$INSERT_TREE_64 also demonstrates the use of LIB$TRAVERSE_TREE_64. Refer to that example for assistance in using this routine.

LIB$TRA_ASC_EBC

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

Format

LIB$TRA_ASC_EBC source-string ,byte-integer-dest-string

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

source-string

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Source string (ASCII) to be translated by LIB$TRA_ASC_EBC. The source-string argument contains the address of a descriptor pointing to this source string.
byte-integer-dest-string

OpenVMS usage: char_string

type: character string

access: write only

mechanism: by descriptor

Destination string (EBCDIC). The byte-integer-dest-string argument contains the address of a descriptor pointing to this destination string.

Description

LIB$TRA_ASC_EBC translates an ASCII string to an EBCDIC 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 ASCII to EBCDIC translation table, LIB$AB_ASC_EBC, in a routine using LIB$MOVTC, but no testing for untranslatable characters is done under those circumstances.
The LIB$TRA_ASC_EBC routine uses the ASCII to EBCDIC translation table.
ASCII to EBCDIC Translation Table

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

Figure lib-24 is the ASCII to EBCDIC translation table.
Figure lib-24 LIB$AB_ASC_EBC

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

Figure lib-25 ASCII Graphics Not Translated to EBCDIC Equivalent by LIB$TRA_ASC_EBC

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.

Example

This COBOL program uses LIB$TRA_ASC_EBC to translate an ASCII string to EBCDIC. If successful, it then uses LIB$MOVTC to translate the EBCDIC string back to ASCII.


IDENTIFICATION DIVISION. PROGRAM-ID. TRANS. ENVIRONMENT DIVISION. DATA DIVISION. WORKING-STORAGE SECTION. 01 INPUT-STRING PIC X(4). 01 EBCDIC-STRING PIC X(4). 01 OUT-STRING PIC X(4). 01 FILL-CHAR PIC X VALUE "@". 01 SS-STATUS PIC S9(9) COMP. 88 SS-NORMAL VALUE 01. 01 EBCDIC-TABLE. 05 FILLER PIC X(16) VALUE "@@@@@@@@@@@@@@@@". 05 FILLER PIC X(16) VALUE "@@@@@@@@@@@@@@@@". 05 FILLER PIC X(16) VALUE "@@@@@@@@@@@@@@@@". 05 FILLER PIC X(16) VALUE "@@@@@@@@@@@@@@@@". 05 FILLER PIC X(16) VALUE " @@@@@@@@@@.<(+\|". 05 FILLER PIC X(16) VALUE "&@@@@@@@@@!$);@". 05 FILLER PIC X(16) VALUE "-/@@@@@@@@@,%_>?". 05 FILLER PIC X(16) VALUE "@@@@@@@@@@:#@'=""". 05 FILLER PIC X(16) VALUE "@abcdefghi@@@@@@". 05 FILLER PIC X(16) VALUE "@jklmnopqr@@@@@@". 05 FILLER PIC X(16) VALUE "@@stuvwxyz@@@@@@". 05 FILLER PIC X(16) VALUE "@@@@@@@@@@@@@@@@". 05 FILLER PIC X(16) VALUE "@ABCDEFGHI@@@@@@". 05 FILLER PIC X(16) VALUE "!JKLMNOPQR@@@@@@". 05 FILLER PIC X(16) VALUE "@@STUVWXYZ@@@@@@". 05 FILLER PIC X(16) VALUE "0123456789@@@@@@". ROUTINE DIVISION. 001-MAIN. DISPLAY " ". DISPLAY "ENTER 4 CHARACTERS TO BE TRANSLATED ASCII TO EBCDIC: " WITH NO ADVANCING. ACCEPT INPUT-STRING AT END STOP RUN. IF INPUT-STRING = "EXIT" OR "exit" OR " " STOP RUN. CALL "LIB$TRA_ASC_EBC" USING BY DESCRIPTOR INPUT-STRING, EBCDIC-STRING GIVING SS-STATUS. IF SS-NORMAL CALL "LIB$MOVTC" USING BY DESCRIPTOR EBCDIC-STRING, FILL-CHAR, EBCDIC-TABLE, OUT-STRING, GIVING SS-STATUS IF SS-NORMAL DISPLAY "ASCII ENTERED WAS: " INPUT-STRING DISPLAY "EBCDIC TRANSLATED IS: " OUT-STRING ELSE DISPLAY " LIB$MOVTC TRANSLATION UNSUCCESSFUL " ELSE DISPLAY " LIB$TRA_ASC_EBC TRANSLATION UNSUCCESSFUL *". GO TO 001-MAIN.

 
IDENTIFICATION DIVISION. 
PROGRAM-ID. TRANS. 
 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
01 INPUT-STRING PIC X(4). 
01 EBCDIC-STRING   PIC X(4). 
01 OUT-STRING PIC X(4). 
01 FILL-CHAR PIC X  VALUE  "@". 
01 SS-STATUS PIC S9(9)       COMP. 
 88  SS-NORMAL   VALUE 01. 
 
01 EBCDIC-TABLE. 
 05 FILLER PIC X(16) VALUE "@@@@@@@@@@@@@@@@". 
 05 FILLER PIC X(16) VALUE "@@@@@@@@@@@@@@@@". 
 05 FILLER PIC X(16) VALUE "@@@@@@@@@@@@@@@@". 
 05 FILLER PIC X(16) VALUE "@@@@@@@@@@@@@@@@". 
 05 FILLER PIC X(16) VALUE " @@@@@@@@@@.<(+|". 
 05 FILLER PIC X(16) VALUE "&@@@@@@@@@!$*);@". 
 05 FILLER PIC X(16) VALUE "-/@@@@@@@@@,%_>?". 
 05 FILLER PIC X(16) VALUE "@@@@@@@@@@:#@'=""". 
 05 FILLER PIC X(16) VALUE "@abcdefghi@@@@@@". 
 05 FILLER PIC X(16) VALUE "@jklmnopqr@@@@@@". 
 05 FILLER PIC X(16) VALUE "@@stuvwxyz@@@@@@". 
 05 FILLER PIC X(16) VALUE "@@@@@@@@@@@@@@@@". 
 05 FILLER PIC X(16) VALUE "@ABCDEFGHI@@@@@@". 
 05 FILLER PIC X(16) VALUE "!JKLMNOPQR@@@@@@". 
 05 FILLER PIC X(16) VALUE "@@STUVWXYZ@@@@@@". 
 05 FILLER PIC X(16) VALUE "0123456789@@@@@@". 
 
ROUTINE DIVISION. 
 
001-MAIN. 
 DISPLAY " ". 
 DISPLAY "ENTER 4 CHARACTERS TO BE TRANSLATED ASCII TO EBCDIC: " 
     WITH NO ADVANCING. 
 ACCEPT INPUT-STRING 
    AT END STOP RUN. 
 IF INPUT-STRING = "EXIT"  OR  "exit"  OR  "     " 
     STOP RUN. 
 
 CALL "LIB$TRA_ASC_EBC" 
     USING BY DESCRIPTOR INPUT-STRING, EBCDIC-STRING 
     GIVING SS-STATUS. 
 IF SS-NORMAL 
     CALL "LIB$MOVTC" 
  USING BY DESCRIPTOR EBCDIC-STRING, 
      FILL-CHAR, 
      EBCDIC-TABLE, 
      OUT-STRING, 
  GIVING SS-STATUS 
     IF SS-NORMAL 
  DISPLAY "ASCII ENTERED WAS: " INPUT-STRING 
  DISPLAY "EBCDIC TRANSLATED IS: " OUT-STRING 
     ELSE 
  DISPLAY "*** LIB$MOVTC TRANSLATION UNSUCCESSFUL ***" 
 ELSE 
     DISPLAY "*** LIB$TRA_ASC_EBC TRANSLATION UNSUCCESSFUL ***". 
 GO TO 001-MAIN.

To exit from this program, you must press Ctrl/Z. The output generated by this COBOL program is as follows:

$ RUN TRANS ENTER 4 CHARACTERS TO BE TRANSLATED ASCII TO EBCDIC: abdc ASCII ENTERED WAS: abdc EBCDIC TRANSLATED IS: abdc ENTER 4 CHARACTERS TO BE TRANSLATED ASCII TO EBCDIC: ~=b& ASCII ENTERED WAS: ~=b& EBCDIC TRANSLATED IS: @=b& ENTER 4 CHARACTERS TO BE TRANSLATED ASCII TO EBCDIC: 8^%$ ASCII ENTERED WAS: 8^%$ EBCDIC TRANSLATED IS: 8@%$ ENTER 4 CHARACTERS TO BE TRANSLATED ASCII TO EBCDIC: /x\} ASCII ENTERED WAS: /x\} EBCDIC TRANSLATED IS: /x@! ENTER 4 CHARACTERS TO BE TRANSLATED ASCII TO EBCDIC: [Ctrl/Z]

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 HP 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

Contents

Index

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

OpenVMS usage:	address
type:	address
access:	read only
mechanism:	by reference

OpenVMS usage:	procedure
type:	procedure value
access:	function call (before return)
mechanism:	by value

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

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.