PMDF Programmer's Reference Manual
PMDF-PRM-6.0

Pass an input string through a mapping table.

VMS FORMAT

status = PMDF_mapping_apply

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

C FORMAT

status = PMDFmappingApply

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

int PMDFmappingApply (mapping, instr, instr_len, 
                      outstr, outstr_len, flags, match) 
         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 PMDF_mapping_load.

instr

Input string to process with the specified mapping table. The length of the string may 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 bytes in length. (ALFA_SIZE+1 bytes for PMDFmappingApply).

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 PMDF_mapping_apply, 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

PMDF_mapping_apply 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 may 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 PMDF_mapping_apply, 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 PMDF_mapping_apply, 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.