|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
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.
LIB$MATCHC sub-string ,source-string
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.
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.
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.
None.
The Match Condition Values routine checks to see if a given condition value matches a list of condition values that you supply.
LIB$MATCH_COND match-condition-value ,compare-condition-value ,...
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.
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.
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.
None.
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 and I64 systems, OpenVMS Alpha and I64 instructions perform the equivalent operation.
LIB$MOVC3 word-integer-length ,source ,destination
None.
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.
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.
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 and I64 systems, OpenVMS Alpha and I64 instructions perform the equivalent operation.
LIB$MOVC5 word-integer-source-length ,source [,fill] ,word-integer-destination-length ,destination
None.
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.
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.
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 and I64 systems, OpenVMS Alpha and I64 instructions perform the equivalent operation.
LIB$MOVTC source-string ,fill-character ,translation-table ,destination-string
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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
Figure lib-7 is the ASCII to EBCDIC reversible translation table.
Figure lib-7 LIB$AB_ASC_EBC_REV
EBCDIC to ASCII Translation Table
Figure lib-8 is the EBCDIC to ASCII translation table.
Figure lib-8 LIB$AB_EBC_ASC
EBCDIC to ASCII Reversible Translation Table
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
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
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
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
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
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
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
Figure lib-17 is the zone to packed decimal translation table.
Figure lib-17 LIB$AB_CVTTP_Z
ASCII Uppercase Translation Table
| Previous | Next | Contents | Index |