hp.com home products and services support and drivers solutions how to buy
cd-rom home
End of Jump to page title
HP OpenVMS systems
documentation

Jump to content


HP OpenVMS RTL Library (LIB$) Manual

HP OpenVMS RTL Library (LIB$) Manual


Previous 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

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. 
 
 
      

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

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:

  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 


Previous Next Contents Index