Updated: 11 December 1998

OpenVMS RTL Library (LIB$) Manual

The Match Characters and 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.

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:

Establishing handler...

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 systems, OpenVMS Alpha 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.

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 systems, OpenVMS Alpha 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.

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 systems, OpenVMS Alpha 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 Compaq, or you can create your own. Translation tables supplied by Compaq 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.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5932PRO_030.HTML