HP OpenVMS RTL Library (LIB$) Manual
LIB$MATCHC
The Match Characters, Return Relative Position routine searches a
source string for a specified substring and returns an index, which is
the relative position of the first occurrence of a substring in the
source string. The relative character positions returned by LIB$MATCHC
are numbered 1, 2,..., n. Thus, zero means that the substring
was not found.
Format
LIB$MATCHC sub-string ,source-string
RETURNS
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
The relative position of the first character of the substring if found,
or zero if not found.
Arguments
sub-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Substring to be found. The sub-string argument is the
address of a descriptor pointing to this substring.
source-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Source string to be searched by LIB$MATCHC. The
source-string argument is the address of a descriptor
pointing to this source string.
Description
LIB$MATCHC searches a source string for a specified substring and
returns an index, which is the relative position of the first
occurrence of a substring in the source string.
The relative character positions returned by LIB$MATCHC are numbered 1,
2,..., n. Thus, zero means that the substring was not found.
If the substring has a zero length, LIB$MATCHC returns the value 1,
indicating success, no matter how long the source string is. If the
source string has a zero length and the substring has a nonzero length,
zero is returned, indicating that the substring was not found.
Condition Values Returned
None.
LIB$MATCH_COND
The Match Condition Values routine checks to see if a given condition
value matches a list of condition values that you supply.
Format
LIB$MATCH_COND match-condition-value ,compare-condition-value ,...
RETURNS
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
A zero, if the input condition value did not match any condition value
in the list, or i-1 , for a match between the first argument and the
ith argument.
Arguments
match-condition-value
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Condition value to be matched. The
match-condition-value argument is the address of an
unsigned longword that contains this condition value.
compare-condition-value
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
The condition values to be compared to
match-condition-value. The
compare-condition-value arguments are the addresses of
the unsigned longwords that contain these condition values.
Description
LIB$MATCH_COND checks for a match between the condition value addressed
by match-condition-value and the condition values
addressed by the subsequent arguments. Each argument is the address of
a longword containing a condition value.
LIB$MATCH_COND is provided for programmers who want to match a list of
one or more condition values. It is designed to be used in multipath
branch statements available in most higher-level languages.
LIB$MATCH_COND compares the portion (STS$V_COND_ID) of the condition
value referenced by the first argument to the same portion of the
condition value referenced by the second through Nth arguments. If the
facility-specific bit (STS$V_FAC_SP = bit 15) is clear in
match-condition-value (meaning that the condition
value is systemwide rather than facility specific), the facility code
field (STS$V_FAC_NO = bits 27:17) is ignored and only the STS$V_MSG_ID
fields (bits 15:3) are compared.
The routine returns a 0 if a match is not found, a 1 if the condition
value matches the first condition value in the list (the second
argument), a 2 if it matches the second condition value (the third
argument), and so on. LIB$MATCH_COND checks for null argument entries
in the argument list.
When LIB$MATCH_COND is called with only two arguments, the possible
values for the value returned are true (1) or false (0).
Each condition handler must examine the signal argument vector to
determine which condition is being signaled. If the condition is not
one that the handler knows about, the handler should resignal. A
handler should not assume that only one kind of condition can occur in
the routine which established it or in any routines it calls. However,
because a condition value may be modified by an intervening handler,
each handler should only compare that part of the condition value that
distinguishes it from another.
Condition Values Returned
None.
Example
|
C+
C This Fortran program demonstrates the use of
C LIB$MATCH_COND.
C
C Declare handler routine as external.
C-
EXTERNAL HANDLER
C+
C Declare the handler that will be used.
C-
TYPE *, 'Establishing handler...'
CALL LIB$ESTABLISH ( HANDLER )
OPEN ( UNIT = 1, NAME = 'MATCH.DAT', STATUS = 'OLD')
C+
C Revert to normal error processing.
C-
CALL LIB$REVERT
CLOSE ( UNIT = 1 )
CALL EXIT
END
C+
C This is the handler routine.
C-
INTEGER*4 FUNCTION HANDLER ( SIGARGS, MECHARGS )
INTEGER*4 SIGARGS(*), STATUS
INCLUDE '($SSDEF)'
INCLUDE '($FORDEF)'
INCLUDE '($CHFDEF)'
RECORD /CHFDEF2/ MECHARGS
HANDLER = SS$_CONTINUE
C+
C This handler will type out an error message. In this case the
C message is regarding a file open status.
C-
TYPE *, 'Entering handler...'
STATUS = LIB$MATCH_COND ( SIGARGS (2) , FOR$_FILNOTFOU,
1 FOR$_NO_SUCDEV, FOR$_FILNAMSPE, FOR$_OPEFAI )
GOTO ( 100, 200, 300, 400 ) STATUS
HANDLER = SS$_RESIGNAL
GOTO 1000
100 TYPE *, 'ERROR -- File not found'
GOTO 1000
200 TYPE *, 'ERROR -- No such device'
GOTO 1000
300 TYPE *, 'ERROR -- File name specification'
GOTO 1000
400 TYPE *, 'ERROR -- Open failure'
GOTO 1000
C+
C On OpenVMS Alpha systems use MECHARGS.CHF$IS_MCH_DEPTH
C On OpenVMS VAX systems use MECHARGS.CHF$L_MCH_DEPTH
C-
1000 CALL SYS$UNWIND ( MECHARGS.CHF$IS_MCH_DEPTH , ) ! For OpenVMS Alpha
C 1000 CALL SYS$UNWIND ( MECHARGS.CHF$L_MCH_DEPTH , ) ! For OpenVMS VAX
TYPE *, 'Returning from handler...'
RETURN
END
|
This Fortran program uses a computed GOTO to alter the program
execution sequence on a condition value.
If the file called MATCH.DAT does not exist, the following output is
returned:
Establishing handler...
Entering handler...
ERROR -- File not found
Returning from handler...
|
If the file MATCH.DAT does exist, the output returned is as follows:
LIB$MOVC3
The Move Characters routine makes the VAX MOVC3 instruction available
as a callable routine. The source item is moved to the destination
item. Overlap of the source and destination items does not affect the
result.
Note
On Alpha and I64 systems, OpenVMS Alpha and I64 instructions perform
the equivalent operation.
|
Format
LIB$MOVC3 word-integer-length ,source ,destination
RETURNS
None.
Arguments
word-integer-length
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Number of bytes to be moved from source to
destination by LIB$MOVC3. The
word-integer-length argument is the address of an
unsigned word that contains this number of bytes. The maximum transfer
is 65,535 bytes.
source
| OpenVMS usage: |
unspecified |
| type: |
unspecified |
| access: |
read only |
| mechanism: |
by reference |
Item to be moved. The source argument is the address
of this item.
destination
| OpenVMS usage: |
unspecified |
| type: |
unspecified |
| access: |
write only |
| mechanism: |
by reference |
Item into which source will be moved. The
destination argument is the address of this item.
Description
LIB$MOVC3 is useful for moving large blocks of data, such as arrays,
when such an operation would otherwise have to be performed by a
programmed loop.
For more information, see the VAX Architecture Reference Manual or the Alpha Architecture Reference Manual. See
also OTS$MOVE3.
Condition Values Returned
None.
LIB$MOVC5
The Move Characters with Fill routine makes the VAX MOVC5 instruction
available as a callable routine. The source item is moved to the
destination item. Overlap of the source and destination items does not
affect the result.
Note
On Alpha and I64 systems, OpenVMS Alpha and I64 instructions perform
the equivalent operation.
|
Format
LIB$MOVC5 word-integer-source-length ,source [,fill]
,word-integer-destination-length ,destination
RETURNS
None.
Arguments
word-integer-source-length
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Number of bytes in the source item. The
word-integer-source-length argument is the address of
an unsigned word that contains this number of bytes. The maximum length
of source is 65,535 bytes.
source
| OpenVMS usage: |
unspecified |
| type: |
unspecified |
| access: |
read only |
| mechanism: |
by reference |
Item to be moved by LIB$MOVC5. The source argument is
the address of this item. If
word-integer-source-length is zero, indicating that
destination is to be entirely filled by the fill
character, then source is ignored by LIB$MOVC5.
fill
| OpenVMS usage: |
byte_signed |
| type: |
byte integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Character used to pad source to the length of
destination. The fill argument is the
address of a signed byte integer that contains this fill character. If
word-integer-destination-length is less than or equal
to word-integer-source-length, fill
is unused and may be omitted.
word-integer-destination-length
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Length of destination in bytes. The
word-integer-destination-length argument is the
address of an unsigned word that contains this number of bytes. The
maximum value of word-integer-destination-length is
65,535 bytes.
destination
| OpenVMS usage: |
unspecified |
| type: |
unspecified |
| access: |
write only |
| mechanism: |
by reference |
Item into which source will be moved. The
destination argument is the address of this item.
Description
If the destination item is shorter than the source item, the
highest-addressed bytes of the source are not moved.
For more information, see the VAX Architecture Reference Manual. See also OTS$MOVE5.
Condition Values Returned
None.
LIB$MOVTC
The Move Translated Characters routine moves the source string,
character by character, to the destination string after translating
each character using the specified translation table. LIB$MOVTC makes
the VAX MOVTC instruction available as a callable routine.
Note
On Alpha and I64 systems, OpenVMS Alpha and I64 instructions perform
the equivalent operation.
|
Format
LIB$MOVTC source-string ,fill-character ,translation-table
,destination-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 to be translated and moved by LIB$MOVTC. The
source-string argument is the address of a descriptor
pointing to this source string.
fill-character
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Fill character used to pad source-string to the length
of destination-string. The
fill-character argument is the address of a descriptor
pointing to a string. The first character of this string is used as the
fill character. The length of this string is not checked and
fill-character is not translated.
translation-table
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Translation table used by LIB$MOVTC. The
translation-table argument is the address of a
descriptor pointing to the translation table string. The translation
table string is assumed to be 256 characters long.
You can use any one of the translation tables included in the
Description section that follows, supplied by HP, or you can create
your own. Translation tables supplied by HP have names in the format
LIB$AB_xxx_yyy, which represent the addresses of the
256-byte translation tables and can be accessed as external (string)
variables. If a particular language cannot generate descriptors for
external strings, then you must create them manually. The example
following the Description section shows the creation of a string
descriptor for a translation table using VAX BASIC.
destination-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Destination string into which LIB$MOVTC writes the translated
source-string. The destination-string
argument is the address of a descriptor pointing to this destination
string.
Description
Each character in the source string is used as an index into the
translation table. The byte found is then placed into the destination
string. The fill character is used if the destination string is longer
than the source string. If the source string is longer than the
destination string, the source string is truncated. Overlap of the
source and destination strings does not affect execution.
The translation tables used by LIB$MOVTC and LIB$MOVTUC follow. Each
table is preceded by explanatory text.
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-6 is the ASCII to EBCDIC translation table.
Figure lib-6 LIB$AB_ASC_EBC
ASCII to EBCDIC Reversible 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 represents the equivalent
EBCDIC characters in hexadecimal notation.
Figure lib-7 is the ASCII to EBCDIC reversible translation table.
Figure lib-7 LIB$AB_ASC_EBC_REV
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.
Figure lib-8 is the EBCDIC to ASCII translation table.
Figure lib-8 LIB$AB_EBC_ASC
EBCDIC to ASCII Reversible 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.
Figure lib-9 is the EBCDIC to ASCII reversible translation table.
Figure lib-9 LIB$AB_EBC_ASC_REV
Packed Decimal to Trailing Overpunch Numeric Value Translation Table
- The numbers on the left represent the low-order bits of the packed
decimal values in hexadecimal notation.
- The numbers across the top represent the high-order bits of the
packed decimal values in hexadecimal notation.
- The numbers in the body of the table represent the equivalent
trailing overpunch numeric values in hexadecimal notation.
Figure lib-10 is the packed decimal to trailing overpunch numeric value
translation table.
Figure lib-10 LIB$AB_CVTPT_O
Packed Decimal to Unsigned Trailing Numeric Value Translation Table
- The numbers on the left represent the low-order bits of the packed
decimal values in hexadecimal notation.
- The numbers across the top represent the high-order bits of the
packed decimal values in hexadecimal notation.
- The numbers in the body of the table represent the equivalent
unsigned trailing numeric values in hexadecimal notation.
Figure lib-11 is the packed decimal to unsigned trailing numeric value
translation table.
Figure lib-11 LIB$AB_CVTPT_U
Trailing Overpunch Numeric to Packed Decimal Value Translation Table
- The numbers on the left represent the low-order bits of the
trailing overpunch numeric values in hexadecimal notation.
- The numbers across the top represent the high-order bits of the
trailing overpunch numeric values in hexadecimal notation.
- The numbers in the body of the table represent the equivalent
packed decimal values in hexadecimal notation.
Figure lib-12 is the trailing overpunch numeric to packed decimal value
translation table.
Figure lib-12 LIB$AB_CVTTP_O
Unsigned Numeric to Packed Decimal Value Translation Table
- The numbers on the left represent the low-order bits of the
unsigned numeric values in hexadecimal notation.
- The numbers across the top represent the high-order bits of the
unsigned numeric values in hexadecimal notation.
- The numbers in the body of the table represent the equivalent
packed decimal values in hexadecimal notation.
Figure lib-13 is the unsigned numeric to packed decimal value
translation table.
Figure lib-13 LIB$AB_CVTTP_U
Trailing Overpunch Numeric to Unsigned Numeric Value Translation Table
- The numbers on the left represent the low-order bits of the
trailing overpunch numeric values in hexadecimal notation.
- The numbers across the top represent the high-order bits of the
trailing overpunch numeric values in hexadecimal notation.
- The numbers in the body of the table represent the equivalent
unsigned numeric values in hexadecimal notation.
Figure lib-14 is the trailing overpunch numeric to unsigned numeric
value translation table.
Figure lib-14 LIB$AB_CVT_O_U
Unsigned Numeric to Trailing Overpunch Translation Table
Figure lib-15 is indexed by 0 through 9 for the positive overpunches
and 10 through 19 for the negative overpunches.
The unsigned binary representation of the least significant digit is
moved into R2. Then, if you require a positive result, the following
code results:
MOVC3 LIB$AB_CVT_U_O[R2], #1,R0
|
If you require a negative result, the following code is generated:
MOVC3 LIB$AV_CVT_U_O + 10[R2], #1,R0
|
The result is the overpunch representation for the last byte of the
negative number.
Figure lib-15 is the unsigned numeric to trailing overpunch translation
table.
Figure lib-15 LIB$AB_CVT_U_O
Packed Decimal to Zone Numeric Translation Table
- The numbers on the left represent the low-order bits of the packed
decimal values in hexadecimal notation.
- The numbers across the top represent the high-order bits of the
packed decimal values in hexadecimal notation.
- The numbers in the body of the table represent the equivalent zoned
numeric values in hexadecimal notation.
Figure lib-16 is the packed decimal to zone numeric translation table.
Figure lib-16 LIB$AB_CVTPT_Z
Zone to Packed Decimal Translation Table
- The numbers on the left represent the low-order bits of the zoned
numeric values in hexadecimal notation.
- The numbers across the top represent the high-order bits of the
zoned numeric values in hexadecimal notation.
- The numbers in the body of the table represent the equivalent
packed decimal values in hexadecimal notation.
Figure lib-17 is the zone to packed decimal translation table.
Figure lib-17 LIB$AB_CVTTP_Z
ASCII Uppercase 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
uppercase ASCII characters in hexadecimal notation.
|
