Pass an input string through a mapping table.

PASCAL

status = PMDF_mapping_apply

(mapping, instr, outstr, outstr_len, flags, match)

argument information

Argument	Data type	Access	Mechanism
mapping	signed longword	read	value
instr	descriptor	read	reference
outstr	descriptor	read/write	reference
outstr_len	unsigned word	write	reference
flags	descriptor	read/write	reference
match	boolean	write	reference

C

status = PMDFmappingApply

(mapping, instr, instr_len, outstr, outstr_len, flags, match)

argument information

int PMDFmappingApply(int mapping, char *instr, int instr_len, char *outstr, int *outstr_len, unsigned char *flags, int *match)

Arguments

mapping

Reference to a mapping table returned by PMDFmappingLoad .

instr

Input string to process with the specified mapping table. The length of the string can not exceed ALFA_SIZE bytes.

instr_len

Length in bytes of the input string, instr.

outstr

String to receive the output, if any, of the mapping. Must be at least ALFA_SIZE+1 bytes in length.

outstr_len

Length in bytes of the output of the mapping. Will be set to 0 if no output is produced. Callers using PMDFmappingApply must, on input, supply the maximum length in bytes of outstr.

flags

Bit array of length at least 32 bytes (256 bits) which, on output, will contain bit encoded information about the mapping process.

match

For PMDFmappingApply , a boolean indicating whether or not a match was found. For PMDFmappingApply an integer indicating whether or not a match was found. If true (1) a match was found; if false (0) no match was found.

Description

PMDFmappingApply is used to apply a previously loaded mapping table to an input string. Consult the PMDF System Manager's Guide for details on the use of mapping tables and the mapping file in which mapping tables reside. If the input string matches an entry in the table, then the result of the mapping is returned in outstr and match set true. Otherwise, match will be false and outstr_len set to zero. Applications can require that special sequences such as $Y or $N be used in mapping table templates. The presence of such sequences are indicated in the flags bit array. These sequences, called metacharacters, will not appear in the output string itself. The output string produced by a template with a $Y in it will not contain $Y . However, bit 89, the ordinal value of the ASCII character Y, will be set in flags. The interpretation of the first 256 bits in flags are given in the table below. Bit 0 is the low-order bit of the first byte in flags, bit 7 is the high-order bit of that same byte, bit 8 is the low-order bit of the next byte, and so forth.

Bit	Description
0---31	For 0 <= n <= 31 , bit n set indicates that n+1 matches occurred. When bit n is set, bits n-1 , n-2 , ..., 0 will also be set.
32	When bit 32 is set, 32 or more matches occurred.
33---255	When bit n , 33 <= n <= 255 , is set, then the two character sequence $ x appeared in the output string, where x is the ASCII character with ordinal index n . This sequence will not actually appear in the output string itself. Bits 36, 67, 99, 69, 101, 76, 108, 82, and 114 are never set; they correspond to the sequences $$, $C, $c, $E, $e, $L, $l, $R, and $r used by the mapping facilities.

To illustrate the usage of flags, consider the mapping table

SAMPLE-TABLE 1 2$A$R 2 3$B

The input string 1 will match the first entry of the table, and produce the output string 2 . Because of the $R metacharacter, the mapping will be reapplied using 2 as the new input string. When 2 is mapped, it will match the second entry and produce the output string 3 . Now, when 1 is mapped with PMDFmappingApply , the final output string will be 3 , and bits 0, 1, 65, and 66 of flags will be set. The first two bits indicate that two matches in the mapping table were made. Bits 65 and 66 indicate that the metacharacters $A and $B were encountered in the templates of those matching entries. If 2 is mapped with PMDFmappingApply , then the output string will again be be 3 , but flags will have only bits 0 and 66 set. If any other string is mapped, then no output string will be returned and no bits in flags will be set.

Return Values

PMDF__OK	Normal, successful completion.
PMDF__FATERRLIB	Call to LIB$SCOPY_R_DX failed owing to a fatal internal error in the OpenVMS Run Time Library. Mapping result not resturned.
PMDF__INSVIRMEM	Insufficient virtual memory: call to LIB$GET_VM made by LIB$SCOPY_R_DX has failed. Channel name not returned.
PMDF__INVSTRDES	Invalid string descriptor for instr, outstr, or flags: one or more of the descriptors has an invalid value in its DSC$B_CLASS field. Mapping not performed or results not returned.
PMDF__STRTRU	Mapping result was too long to fit into the supplied output string; result truncated to fit.
PMDF__STRTRUERR	Input string is too long or flags string too short. Mapping not performed.