 |
HP OpenVMS RTL Library (LIB$) Manual
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.
|
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.
|
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
|
|
