Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

Previous | Contents | Index

## LIB$MATCHC

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

## 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:

>      Establishing handler...

## 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 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.

## 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 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.

## 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 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.

Previous | Next | Contents | Index

| privacy and legal statement |
5932PRO_031.HTML