Match/Consolidate
Custom Programmer’s Reference
Match/Consolidate 8.00c
April 2009
Copyright information © 2009 SAP® BusinessObjects™. All rights reserved. SAP BusinessObjects and its logos,
BusinessObjects, Crystal Reports®, SAP BusinessObjects Rapid Mart™, SAP BusinessObjects Data Insight™, SAP BusinessObjects Desktop Intelligence™, SAP BusinessObjects
Rapid Marts®, SAP BusinessObjects Watchlist Security™, SAP BusinessObjects Web Intelligence®, and Xcelsius® are trademarks or registered trademarks of Business Objects, an SAP
company and/or affiliated companies in the United States and/or other countries. SAP® is a
registered trademark of SAP AG in Germany and/or other countries. All other names mentioned herein may be trademarks of their respective owners.
2
Match/Consolidate Custom Programmer’s Reference
Contents
Preface .............................................................................................................5
Chapter 1:
Introduction to Match/Consolidate Custom............................................... 7
Purpose of Match/Consolidate Custom............................................................8
Exit points in Match/Consolidate job processing.............................................9
How applications use the Match/Consolidate Custom libraries.....................10
Compiling and linking....................................................................................11
Chapter 2:
Writing exit functions ................................................................................. 13
Introduction to exit functions .........................................................................14
input_processing() exit function.....................................................................16
compare_before() exit function......................................................................18
compare_after_dupe() exit function ...............................................................20
compare_after_nodupe() exit function...........................................................21
dupe_group() exit function.............................................................................22
dupe_group_post() exit function ....................................................................23
output_processing() exit function...................................................................24
parse() exit function .......................................................................................25
Table of exit-support functions by exit point .................................................26
Chapter 3:
Group posting .............................................................................................. 27
Group posting options ....................................................................................28
Setting up external operations........................................................................29
Setting up double operations ..........................................................................30
Exit-support functions for group posting .......................................................31
Chapter 4:
Match/Consolidate Custom library functions .......................................... 33
mpc_get_ap_field() ........................................................................................34
mpc_get_db_field() ........................................................................................36
mpc_get_error_info() .....................................................................................37
mpc_get_exit_type().......................................................................................38
mpc_get_info_in_field().................................................................................39
mpc_get_info_in_file()...................................................................................40
mpc_get_info_key_field()..............................................................................41
mpc_get_info_out_field()...............................................................................42
mpc_get_info_out_file().................................................................................43
mpc_get_info_pw_field()...............................................................................44
mpc_get_job_step()........................................................................................45
mpc_get_key_field() ......................................................................................46
mpc_get_num_current_rec() ..........................................................................47
mpc_get_num_in_files() ................................................................................48
mpc_get_num_recs()......................................................................................49
mpc_get_pw_field() .......................................................................................50
Contents
3
mpc_get_pw_field_id().................................................................................. 51
mpc_get_record()...........................................................................................52
mpc_init()....................................................................................................... 53
mpc_process_job().........................................................................................54
mpc_process_jobv().......................................................................................55
mpc_put_db_field() .......................................................................................56
mpc_put_key_field()...................................................................................... 57
mpc_put_record()...........................................................................................58
mpc_set_ap_field() ........................................................................................ 59
mpc_set_current_rec() ................................................................................... 60
mpc_set_dupes() ............................................................................................61
mpc_set_exit() ............................................................................................... 62
mpc_set_gpst_name() .................................................................................... 63
mpc_set_gpst_num_ops() .............................................................................. 64
mpc_set_gpst_result().................................................................................... 65
mpc_set_group_pos()..................................................................................... 66
mpc_set_process() ......................................................................................... 67
mpc_set_unique()...........................................................................................68
mpc_term().....................................................................................................69
simscore()....................................................................................................... 70
Index.............................................................................................................. 71
4
Match/Consolidate Custom Programmer’s Reference
Preface
About this guide
Conventions
This manual is a reference for C programmers who are working with Match/
Consolidate Custom. This manual explains how to make your application
work with Match/Consolidate Custom, and provides detailed reference pages
about each of the functions.
In writing this manual, we assume that you are already familiar with the C
programming language, your operating system, and with basic concepts of
database management, mail processing, and address processing.
This document follows these conventions:
Convention Description
Bold We use bold type for file names, paths, emphasis, and text that you
should type exactly as shown. For example, “Type
Italics We use italics for emphasis and text for which you should substitute
your own data or values. For example, “Type a name for your file,
Menu
commands
!
and the
We indicate commands that you choose from menus in the following format: Menu Name > Command Name. For example, “Choose
File > New.”
We use this symbol to alert you to important information and potential problems.
.txt
extension (
testfile
.txt
).”
cd\dirs
.”
We use this symbol to point out special cases that you should know
about.
We use this symbol to draw your attention to tips that may be useful
to you.
Preface
5
Documentation
Other documentation Documents related to this manual include the following:
Document Description
Access the latest
documentation
System Administrator’s
Explains how to install your software.
Guide
Database Prep
Explains how to prepare input files for processing, including how to create DEF, FMT, and DMT files.
Match/Consolidate
User’s Guide to Record
Matching
Explains the concepts behind name and address matching
software and provides examples of how to implement,
analyze, and fine-tune match detection strategies for the
best results.
Match/Consolidate
Job-File Reference
Match/Consolidate
Extended Matching
Contains the operational how-to instructions for setting
up the Match/Consolidate job file.
Contains the operational how-to instructions for setting
up extended matching.
Reference
Quick Reference
Contains descriptions of the input and output fields, and
the command line for the Match/Consolidate job file.
You can access Firstlogic documentation in several places:
On your computer. Release notes, manuals, and other documents for
each Firstlogic product that you’ve installed are available in the
Documentation folder. Choose Start > Programs > Firstlogic
Applications > Documentation.
On the SAP Service Market Place. Go to http://help.sap.com, and then
click the Business Objects tab. Here, you can search for your products’
documentation.
6
Match/Consolidate Custom Programmer’s Reference
Chapter 1:
Introduction to Match/Consolidate Custom
This chapter explains the purpose of Match/Consolidate Custom. It provides
information about the exit points in Match/Consolidate job processing, how
applications use the Match/Consolidate Custom libraries, and about compiling
and linking.
Chapter 1: Introduction to Match/Consolidate Custom
7
Purpose of Match/Consolidate Custom
The purpose of using Match/Consolidate Custom, rather than the off-the-shelf
Match/Consolidate program, is two-fold:
Match/Consolidate Custom enables you to run Match/Consolidate jobs from
within your own C application. You might want to develop a proprietary user
interface, for example.
Match/Consolidate Custom gives you greater control over Match/
Consolidate processing. At selected points within the process, Match/
Consolidate calls your functions. Your routines, called exit functions, may
alter the results that Match/Consolidate would otherwise produce.
To use Match/Consolidate Custom, you
will create one or two layers of software:
one above our Match/Consolidate batch
application, and the other underneath.
(See the figure at the right.)
Match/Consolidate Custom includes
libraries of C functions for each layer. The
setup functions are called by your main
program; the exit-support functions
provide information to your exit routines.
Exit functions are optional. If you don’t
use them, you will obtain the same
results from Match/Consolidate that you
would obtain from our off-the-shelf
program.
Your application
Match/Consolidate Custom
Match/Consolidate
batch application
Your exit functions
Match/Consolidate Custom
exit support library
Match/Consolidate Custom is based on the batch-oriented Match/Consolidate
program. Match/Consolidate Custom is not appropriate for interactive
applications.
8
Match/Consolidate Custom Programmer’s Reference
Exit points in Match/Consolidate job processing
Eight exit types An exit function is a C function that is written by you and called by Match/
Consolidate. The eight types of exit functions are listed below and described in
full detail in “Writing exit functions” on page 13. You need not use the function
names listed here; however, we will use them in this manual to avoid confusion.
input_processing()
compare_before()
compare_after_dupe()
compare_after_nodupe()
dupe_group()
dupe_group_post()
output_processing()
parse()
Three exit states As listed in the following table, an exit function may be called in any of three
states. Note that this refers to a state that Match/Consolidate is in, not a state of
your application.
State of exit
function
Description
Initialization Before a processing step begins, Match/Consolidate may call your
exit function in the init state. Such a call will be made only once, and
then usually to allocate memory or open files.
Process During processing, Match/Consolidate may call your exit function in
the process state. This call will be made once for each item to be
processed (input record, pair of records, dupe group, or output
record). Obviously, any exit function called in this state may have a
dramatic effect on the rate of processing.
Termination After completing the step, Match/Consolidate may call your exit
function in the term state. Such a call will be made only once—
usually, to free memory, close files, or write a report.
Unsupported exits Match/Consolidate Custom does not support exits for reading a record from an
input file or writing a record to an output file. Neither does Match/Consolidate
Custom support exits during the creation of reports, posting to an input file, or
purging of dupes from input files.
Chapter 1: Introduction to Match/Consolidate Custom
9
How applications use the Match/Consolidate Custom libraries
Setup library Your application will call just a few functions in the Match/Consolidate Custom
setup library. They are listed here in the order that you would call them:
Function Description
mpc_init() Initializes Match/Consolidate Custom and allocates memory
for Match/Consolidate Custom processing.
mpc_set_exit() Signals to Match/Consolidate Custom that an exit function will
be called, and sets the address of that exit function. Because
there are eight types of exit functions, you may need to call
mpc_set_exit() up to eight times.
mpc_process_job() Starts Match/Consolidate batch processing. This function
passes an entire command line to Match/Consolidate.
An alternative form of this call, mpc_process_jobv(), enables
you to pass command-line arguments from your main function
to Match/Consolidate.
mpc_term() Halts Match/Consolidate Custom and frees all memory allo-
cated for Match/Consolidate Custom.
There are two more functions that pertain to group posting in the setup library.
For more information about group posting, see “Group posting” on page 27.
Exit-support library The library of exit-support functions is described in “Writing exit functions” on
page 13. There, you will find complete information about how to write exit
functions.
Errors To retrieve information about an error during Match/Consolidate processing, you
may call mpc_get_error_info(). You may call this function from your main
program or from your exit functions.
Most Match/Consolidate Custom functions return MPC_OK if the function
completed successfully. If an error occurs, the global variable mpc_errno is set to
an error value and MPC_ERROR is returned. If your application detects
MPC_ERROR, it may call mpc_get_error_info() to get more information.
Sample program To see an example of an application calling Match/Consolidate Custom, see the
sample program mpc_test.c.
The sample program is for use only as a learning tool. It is not a prototype or
product. Firstlogic does not support or authorize any use for commercial purposes
and disclaims any warranty regarding such use.
10
Match/Consolidate Custom Programmer’s Reference
Compiling and linking
All copies of Match/Consolidate Custom are shipped compiled and ready to link;
source code is not available.
UNIX We compile the Match/Consolidate Custom Library with cc(1).
On some UNIX platforms, you must link in specific operating system libraries.
For details about which system libraries to link in, see the sample build script,
build. For information about your operating system libraries, consult your
operating system manuals or vendor.
To build our sample application, see the build file. Read the instructions in the file
and edit it before using it. You can use the build file to build our sample program
(mpc_test). To build our mpc_test application, you would type the command
build mpc_test.
Windows We compile using Microsoft Visual C++ (MSVC).
To build our sample applications, follow the guidelines in read_mpc.me.
Chapter 1: Introduction to Match/Consolidate Custom
11
12
Match/Consolidate Custom Programmer’s Reference
Chapter 2:
Writing exit functions
This chapter provides information about exit functions and a table of exit-support
functions by exit point.
Chapter 2: Writing exit functions
13
Introduction to exit functions
The Match/Consolidate Custom library allows your application to gain control of
job file processing at certain key intervals by way of exit functions. An exit
function is a callable function that is written by the user and is called by the
Match/Consolidate code. There are eight types of exit functions:
input_processing()
compare_before()
compare_after_dupe()
compare_after_nodupe()
dupe_group()
dupe_group_post()
output_processing()
parse()
Exit information As listed in the following table, an exit function may be called in any of three
states. Note that this refers to a state that Match/Consolidate is in, not a state of
your application.
State of exit
function
Description
Initialization Before a processing step begins, Match/Consolidate may call your
exit function in the initialization (init) state. Such a call will be
made only once, and then usually to allocate memory or open files.
Process During processing, Match/Consolidate may call your exit function
in the process state. This call will be made once for each item to be
processed (input record, pair of records, dupe group, or output
record). Any exit function called in this state may have a dramatic
effect on the rate of processing.
Termination After completing the step, Match/Consolidate may call your exit
function in the termination (term) state. Such a call will be made
only once, and then usually to free memory, close files, or write a
report.
It is your responsibility to free any memory that you allocate, and
close any files that you open. Ordinarily, this will be accomplished
by another call to your exit function in the termination state.
Match/Consolidate will not free memory or close files opened by
your application.
When you set up your exit function, you will also select the state(s) in which that
exit function will be called.
14
Match/Consolidate Custom Programmer’s Reference
State passed as argument
You will write up to eight exit functions, as listed on the previous page. You will
not write 24 exit functions (eight exit function types times three states). Instead,
Match/Consolidate Custom will pass the state when it calls your exit function,
and your exit function should act accordingly.
Data retrieval Match/Consolidate Custom offers several get functions to retrieve fields or whole
records, or get information about the input file or fields. For details, see the
“Table of exit-support functions by exit point” on page 26.
Match/Consolidate can retrieve data much faster from its key file than from the
input files. For best performance, we recommend that whenever possible, you use
mpc_get_key_field() instead of mpc_get_db_field() or mpc_get_pw_field(). In
our early tests, retrieval from the key file has been about three times faster than
retrieval from input files.
For performance reasons, you may wish to create extra key fields for use by your
exit functions. These key fields need not be used in the Match/Consolidate
matching process. See the Quick Reference for information about the PW fields
Merg_Purg1 through Merg_Purg5.
Error handling Most Match/Consolidate Custom functions return MPC_OK if the function
completed successfully. If an error occurs, the global variable mpc_errno is set to
an error value and MPC_ERROR is returned. If your exit function detects
MPC_ERROR, it may call mpc_get_error_info() to get more information. Values
for mpc_errno are defined in the header file mpc.h.
Return status Your exit functions should return either of the integers MPC_OK or
MPC_ERROR. If Match/Consolidate detects an MPC_ERROR return, it will
shut down gracefully. It is your responsibility, in your exit functions, to report the
error to the user.
Modifying Match/ Consolidate results
Your application should not modify Match/Consolidate results except as provided
for in the Match/Consolidate Custom exit-support library. In particular, do not
modify the Match/Consolidate work files.
A stated purpose of Match/Consolidate Custom is to enable you to modify Match/
Consolidate results. However, one of our design goals for the Match/Consolidate
Custom exit-support library is to preserve the integrity of Match/Consolidate
processing. That’s why there are some functions that you won’t find in the
library; for example, there is no mpc_put_key_field() function.
Chapter 2: Writing exit functions
15
input_processing() exit function
If you declare an input_processing() exit function, it will be called during the
processing step called Read Records (see the Execution block in the Match/
Consolidate job file). The input_processing() exit function can perform three
tasks:
Exclude a record from all processing
Exclude a record from the dupe search
Modify a record
Exclude from all processing
Your input_processing() exit function may determine that an input record should
not be included in any further processing. To carry out this decision, your
input_processing() exit function should call mpc_set_process() with the argument
MPC_DECISION_NO. Match/Consolidate will treat the record as if it had failed
the input filter.
If a record fails the input filter, you have no way of reversing that decision,
because your input_processing() exit function will not be called.
Exclude from the dupe search
Your input_processing() exit function may determine that a record should be
excluded from the search for dupes. In other words, a record may be declared to
be unique. To carry out this decision, your input_processing() exit function
should call mpc_set_unique() with the argument MPC_DECISION_YES.
Modify a record Your input_processing() exit function may modify an input record. For this
purpose, Match/Consolidate Custom offers several get functions to retrieve fields
or whole records, or get information about the input file or fields. For details, see
the “Table of exit-support functions by exit point” on page 26.
If your input_processing() exit function modifies a record, Match/Consolidate
Custom will write the modified record back into the input file and use it for all
subsequent processing.
Initialization call You might want Match/Consolidate to call your input_processing() exit function
in the initialization state in order to allocate memory or open files. At the time of
this initialization call:
Match/Consolidate has opened the job file with exclusive access.
The input files have been opened with read/write access.
The DEF and FMT files have been read and closed.
Note that it is your responsibility to free any memory that you allocate and to
close any files that you open. Ordinarily, this will be accomplished by another
call to your input_processing() exit function in the termination state. Match/
Consolidate will not free memory or close files opened by your application.
16
Match/Consolidate Custom Programmer’s Reference
Process call At the Read Records step, Match/Consolidate Custom follows these steps:
1. Reads a record from the input file.
2. Runs the record through the input filter. If the record fails the input filter, the
input_processing() exit function will not be called.
3. Calls the input_processing() exit function in the process state, if one has been
set. You perform the remaining steps only if your exit function does not
exclude the record from processing (see previous page).
4. Determines to which list the record belongs.
5. Parses (and perhaps standardizes) the name and address data.
6. Generates key fields and stores them in the key file.
If an input_processing() exit function has been set, it is called after a record is run
through the input filter, but before Match/Consolidate assigns the record to a list.
Termination call You might want Match/Consolidate to call your input_processing() exit function
in the termination state in order to generate a report, free memory, and close files.
At the time of this call, the job file and all input files are still open.
Chapter 2: Writing exit functions
17
compare_before() exit function
The compare_before() exit function is called during the Find Duplicates step of
job processing.
Compare records When called in the process state, your compare_before() exit function will be
presented a pair of records that are about to be compared. Your function may
determine that the pair of records are dupes. For example, you might decide that
if two records match on the Social Security Number, they are definitely a match,
no matter what the normal comparison might determine.
To carry out this decision, your exit function may call mpc_set_dupes(). As listed
in the following table, there are three possible arguments to this call:
Argument Description
Yes The records are accepted as a match and Match/Consolidate cancels its
own comparison.
No The records are accepted as a nonmatch and Match/Consolidate cancels
its own comparison.
Undecided This is the default state. Match/Consolidate will compare the records as
usual, according to the match criteria and options set up in the job file.
Support functions Your compare_before() function will deal with pairs of records. To manage this,
you may call mpc_get_num_current_rec() to determine which record of the pair
is the current record; this will return a 1 or 2. You may also call
mpc_set_current_rec() to select one record from the pair to be the current record.
Match/Consolidate Custom also offers several get functions to retrieve fields or
whole records, or get information about the input file or fields. For details, see the
“Table of exit-support functions by exit point” on page 26.
Match/Consolidate Custom lets you compare multiline unparsed addresses as
well. See the next page for more information on comparing addresses in Match/
Consolidate Custom.
Performance If your compare_before() exit function is to be called in the process state, please
note: Your exit function may be called millions, or even trillions of times in a
single job, Exit processing may reduce the overall Match/Consolidate processing
rate, so keep this in mind when designing your exit function. Of course, the time
taken for exit processing may be partially offset if, because of your Yes or No
decision, Match/Consolidate cancels its normal comparison.
Excluded records Match/Consolidate cancels some comparisons. Note that your compare_before()
exit function will not be called when Match/Consolidate cancels a comparison.
18
Match/Consolidate Custom Programmer’s Reference
Multiline unparsed comparisons
You can also compare unparsed records. Multiline unparsed comparisons, and
parsed to unparsed comparisons (if the records are in the same break group) are
possible. This includes comparison of foreign addresses.
Below is one example of how you may use the compare_before() exit function to
compare unparsed records. This comparison matches on first name and the
overall similarity of two records. The example given below could easily be
expanded to include more database or non-address key fields.
int status; /* return status */
int percent; /* match_percent */
char rec_buf1[1024]; /* buffer for whole record 1 */
char rec_buf2[1024]; /* buffer for whole record 2 */
char fname_buf1 [20]; /* buffer for first name 1 */
char fname_buf2 [20]; /* buffer for first name 2 */
char parse_buf1 [2]; /* buffer for parse status of record 1 */
char parse_buf2 [2]; /* buffer for parse status of record 2 */
/* get record 1 comparison info */
status = mpc_set_current_rec(1);
status = mpc_get_ap_field(MPG_AP_PARSE, parse_buf1);
status = mpc_get_key_field(MPG_KEY_FIRSTNAME, fname_buf1);
status = mpc_get_record(rec_buf1);
/* get record 2 comparison info */
status = mpc_set_current_rec(2);
status = mpc_get_ap_field(MPG_AP_PARSE, parse_buf2);
status = mpc_get_key_field(MPG_KEY_FIRSTNAME, fname_buf2);
status = mpc_get_record(rec_buf2);
/* UNPARSED RECORD MATCHING */
/* If one of the records is unparsed, first names must be 80% alike
and the records must be at least 75% alike overall in this example.
*/
if (parse_buf1[0] !=32 || parse_buf2[0] !=32 { /* one or both
recs unparsed */
percent = simscore(recbuf1, strlen(rec_buf1), rec_buf2,
strlen(rec_buf2));
if (percent >= 75 &&
simscore(fname_buf1, strlen(fname_buf1), fname_buf2,
strlen(fname_buf2)) {
fprintf(stdout, “UNPARSED MATCH DETECTED!\n”);
status = mpc_set_dupes(MPC_DECISION_YES) /* DUPE OVERRIDE */
}
Chapter 2: Writing exit functions
19
compare_after_dupe() exit function
Re-compare duplicates
The compare_after_dupe() exit function is called during the Find Duplicates step
of job processing. When called in the process state, your compare_after_dupe()
function will be presented a pair of records that have been compared and found to
be dupes—either by the normal Match/Consolidate comparison, or by your
compare_before() exit function.
For example, you might set rather loose match criteria in the job file. This will
cause Match/Consolidate to err on the side of matching. Then your
compare_after_dupe() exit function could re-evaluate each “matching” pair, to
reduce false alarms (see the diagram below).
Your compare_after_dupe() exit function may determine, despite the previous
finding, that the pair of records are not dupes. To carry out this decision, your exit
function may call mpc_set_dupes().
Match/Consolidate
says the records match.
Match/Consolidate
says the records do not
match.
To you, the records
are duplicates.
Correct detection False match
Missed duplicate Correct non-detection
To you, the records are
not duplicates.
If your compare_after_dupe() exit function is to be called in the process state,
please note: Your exit function may be called thousands of times in a single job.
Obviously, exit processing may reduce the overall Match/Consolidate processing
rate, perhaps dramatically. Please bear this in mind when designing your exit
function.
Support functions Your compare_after_dupe() exit function will deal with pairs of records. To
manage this function you may call mpc_get_num_current_rec() to determine
which record of the pair is the current record; this will return a 1 or 2. You may
also call mpc_set_current_rec() to select one record from the pair to be the
current record.
Match/Consolidate Custom also offers several get functions to retrieve fields or
whole records, or get information about the input file or fields. For details, see the
“Table of exit-support functions by exit point” on page 26.
20
Match/Consolidate Custom Programmer’s Reference
compare_after_nodupe() exit function
Re-compare non-duplicates
The compare_after_nodupe() exit function is called during the Find Duplicates
step of job processing. When called in the process state, your
compare_after_nodupe() function will be presented a pair of records that have
been compared and found not to be dupes—either by the normal Match/
Consolidate comparison, or by your compare_before() exit function.
For example, you might set rather tight match criteria in the job file. This will
cause Match/Consolidate to err on the side of not matching. Then your
compare_after_nodupe() exit function could re-evaluate each nonmatching pair,
to reduce missed dupes (see the diagram below).
Your compare_after_nodupe() exit function may determine, despite the previous
finding, that the pair of records are dupes. To carry out this decision, your exit
function may call mpc_set_dupes().
Match/Consolidate
says the records match.
Match/Consolidate
says the records do not
match.
To you, the records are
duplicates.
Correct detection False match
Missed duplicate Correct non-detection
To you, the records are not
duplicates.
If your compare_after_nodupe() exit function is to be called in the process state,
your exit function may be called thousands or even millions of times in a single
job. Obviously, exit processing may reduce the overall Match/Consolidate
processing rate, perhaps dramatically. Please bear this in mind when designing
your exit function.
Support functions Your compare_after_nodupe() exit function will deal with pairs of records. To
manage this, you may call mpc_get_num_current_rec() to determine which
record of the pair is the current record; this will return a 1 or 2. You may also call
mpc_set_current_rec() to select one record from the pair to be the current record.
Match/Consolidate Custom also offers several get functions to retrieve fields or
whole records, or get information about the input file or fields. For details, see the
“Table of exit-support functions by exit point” on page 26.
Chapter 2: Writing exit functions
21
dupe_group() exit function
The dupe_group() exit function is called after the Find Duplicates step is
completed and after the records in each dupe group have been prioritized. For
information about dupe groups and prioritization, see the User’s Guide to Record
Matching.
Choose a new master dupe
If the dupe_group() exit function is active, it is called once for each dupe group.
The dupe_group() exit function will be able to change the positions of records in
the dupe group. In theory, you may alter the sequence of subordinate dupes. More
typically, the purpose of calling mpc_set_group_pos() will be to choose a new
master dupe. You should not alter the data in the master dupe; that is the purpose
of the dupe_group_post() exit function.
For example, your program might determine, for whatever reason, that one of the subordinate dupes should be elevated to be the master dupe. Be sure to make that subordinate dupe the current record (see Support functions below).
Then to carry out your decision, call mpc_set_group_pos() to set the new position
of the current record in the dupe group. The position of other group members will
be adjusted as necessary.
If your dupe_group() exit function is to be called in the process state, note that it
is impossible to predict how many dupe groups there will be, or how many times
your function will be called. That depends on how the job file is set up and on the
input lists.
Support functions When called in the process state, your dupe_group() exit function will process
groups of unknown size. One member of the group is the current record. Initially,
this is the first record in the group, the master dupe. Your exit functions may call
the following:
Function Description
mpc_get_num_recs() Determine how many records are in the dupe group.
mpc_get_num_current_rec() Determine which record in the group is the
current record.
mpc_set_current_rec() Select one record from the group to be the
current record.
pc_set_group_pos() Set the new position of the current record in the
dupe group.
Match/Consolidate Custom also offers several get functions to retrieve fields or
whole records, or get information about the input file or fields. For details, see the
“Table of exit-support functions by exit point” on page 26.
22
Match/Consolidate Custom Programmer’s Reference
dupe_group_post() exit function
The dupe_group_post() exit function is called whenever dupe group posting is
normally performed—that is, in the course of either purging an input file of bad
records or writing good records to an output file.
If the dupe_group_post() exit function is active, it is called immediately after
Match/Consolidate performs the group posting operations specified in the job
file. The modified master record and all the subordinates are passed to the
dupe_group_post() exit function. The dupe_group_post() exit function may
modify the master record.
For a complete discussion of group posting in Match/Consolidate Custom, see
“Group posting” on page 27.
Chapter 2: Writing exit functions
23
output_processing() exit function
If you declare an output_processing() exit function, it will be called during the
creation of an output file. In the job file (see the Execution block), this stage of
processing may be called any of the following:
Create Match/Consolidate File
Create Multi-Occurrence File
Create All-Duplicates File
Create Custom Match/Consolidate File
Examine output records
Exclude a record from the output file
When writing to an output file, Match/Consolidate reads each input record and
determines whether it is eligible for output. A record’s eligibility depends on
many factors, including whether it passes the output filter, its status (unique,
master, etc.) and type (suppression or normal), and more. Only eligible records—
as determined by whatever is set up in the job file—are presented to your
output_processing() exit function.
If the record is eligible, Match/Consolidate copies data from the input record to
the output record, and then appends the output record to the output file.
If the output_processing() exit function is active, it is called just before the output
record is appended to the output file. The output_processing() exit function is not
called if the record is dropped.
Two records will be presented to your output_processing() exit function: The
output record (#1), and the input record (#2). Of course, the formats of these two
records may be different. The data read from the input record may have been
modified by a group-posting operation.
The output_processing() exit function can perform two tasks: First, you may
decide to exclude a record from the output. If you decide to include the record,
you may modify it before it is written out.
Your output_processing() exit function may determine that a record should not be
included in the output file. To carry out this decision, call mpc_set_process() and
set it to No. Match/Consolidate treats the record as if it had failed the output filter.
If a record fails the output filter that was set up in the job file, you have no
way of reversing that decision, because your output_processing() exit
function will not be called.
Modify a record Your output_processing() exit function may also modify an output record. For
this purpose, Match/Consolidate Custom offers several get functions to retrieve
fields or whole records, or get information about the input file or fields. For
details, see the “Table of exit-support functions by exit point” on page 26.
24
Match/Consolidate Custom Programmer’s Reference
parse() exit function
This type of exit function is available only during the Read Records processing
step. It is called while reading records when parsing is performed.
In previous versions of the manual, we referred to this exit as
name_address_parse().
Perform your own data parsing
You can use the parse() exit function to populate specific fields with the data you
want.
For example, Match/Consolidate can parse United States addresses but not
addresses from other countries. You might set up a parse() for non-U.S.
addresses. During the exit, you could parse the address data, put the data into the
appropriate key fields, and reset the AP parse status fields—for example, you
might set the status of the address data to OK.
Support functions During the parse() exit, you might call these support functions:
Function Description
mpc_get_ap_field() Find the current parse status of the record. For example, if you
were targeting non-U.S. records, you could check the
MPG_AP_LL_ERROR field for the code E403, which indicates a non-U.S. address.
mpc_get_db_field()
mpc_get_pw_field()
mpc_get_key_field()
mpc_put_db_field()
mpc_put_key_field()
mpc_set_ap_field() Set an AP field. For example you might set a value in one of
Get the original data or key data.
Put data into database fields or key fields.
the parse-status fields: MPG_AP_NAME_ERROR,
MPG_AP_FIRM_ERROR, MPG_AP_ADDR_ERROR, or
MPG_AP_LL_ERROR.
Do not call ACE or TrueName
Do not call either ACE Library or TrueName Library from this parse exit. If
either of those programs is initiated in the parse exit, their functions will conflict
with Match/Consolidate’s use of those same functions.
If you feel you need to call either ACE or TrueName from the parse exit, consider
using the extended parsing settings in the Match Options block of your Match/
Consolidate job, instead. You should be able to get the results you want through
that approach.
Chapter 2: Writing exit functions
25
Table of exit-support functions by exit point
The following table shows which exit-support functions you can call from each
type of exit function.
Exit support function Exit function
input_
proc
mpc_get_ap_field() P P P P P P P P
mpc_get_db_field() P P P P P P P P
mpc_get_error_info() Yes Yes Yes Yes Yes Yes Yes Yes
mpc_get_exit_type() Yes Yes Yes Yes Yes Yes Yes Yes
mpc_get_info_in_field() Yes Yes Yes Yes Yes Yes Yes Yes
mpc_get_info_in_file() Yes Yes Yes Yes Yes Yes Yes Yes
mpc_get_info_key_field() Yes Yes Yes Yes Yes Yes Yes Yes
mpc_get_info_out_field() No No No No No No P P
mpc_get_info_out_file() No No No No No No P P
mpc_get_info_pw_field() Yes Yes Yes Yes Yes Yes Yes Yes
mpc_get_job_step() Yes Yes Yes Yes Yes Yes Yes Yes
mpc_get_key_field() No P P P No No No No
mpc_get_num_current_rec() 1 P P P P P P P
mpc_get_num_in_files() Yes Yes Yes Yes Yes Yes Yes Yes
mpc_get_num_recs() 1 2 2 2 P P 2 1
mpc_get_pw_field() P P P P P P P P
mpc_get_pw_field_id() P P P P P P P P
mpc_get_record() P P P P P P P P
mpc_put_db_field() P No No No No P P P
mpc_put_key_field() No No No No No No No P
mpc_put_record() P No No No No P P Yes
mpc_set_ap_field() No No No No No No No P
mpc_set_current_rec() 1 P P P P P P P
mpc_set_dupes() No P P P No No No No
mpc_set_gpst_result() No No No No No P No No
mpc_set_group_pos() No No No No P No No No
mpc_set_process() P No No No No No P P
mpc_set_unique() P No No No No No No No
simscore() Yes Yes Yes Yes Yes Yes Yes Yes
comp_
before
comp_
after_
dupe
comp_
after_
nondupe
dupe_
group
dupe_
group_
post
output
_proc
parse
Yes = You can call this support function when the exit function is in any of the three states.
No = You cannot call this support function.
P = You can call this support function only when the exit function is in the process state.
1 = You can call this support function, but it will always return a 1.
2 = You can call this support function, but it will always return a 2.
26
Match/Consolidate Custom Programmer’s Reference
Chapter 3:
Group posting
This chapter explains the available options for performing group posting in
Match/Consolidate Custom.
Chapter 3: Group posting
27
Group posting options
You may perform group posting by any of three methods:
Method Description
Internal You may perform group posting entirely within the normal Match/Consoli-
External You may perform group posting entirely outside of normal Match/Consoli-
Both You may perform group posting both internally and externally. That is, the
date job, by using Group Posting blocks in your job file. We will call this an
internal group-posting operation.
date processing. We will call this an external group-posting operation.
user may set up operations through the job file, and then your exit function
may perform postprocessing or additional operations.
28
Match/Consolidate Custom Programmer’s Reference
Setting up external operations
You may perform group posting entirely outside of normal Match/Consolidate
processing. We will call this an external group-posting operation.
Job file Under this method, no Group Posting blocks are used in the job file. However, the
job file should include a block for the group-posting report. And in the blocks for
output file or purge, the Do Group Posting parameter must be set to Yes.
Match/Consolidate Custom setup calls
To set up external operations, your main program (not an exit function) should
call three functions in the Match/Consolidate Custom library:
Call mpc_set_gpst_num_ops() to set the number of external operations to be
performed.
Call mpc_set_gpst_name() to name your external operation(s). Call once per
operation, as necessary. This call has the same effect as the parameter Group
Post Name in the Group Posting block. The name that you set is used on the
group-posting report, simply to identify each operation. Operations will be
listed in the order that you set their names.
Call mpc_set_exit() to set up your exit function. Make sure that your exit
function will be called at least in the process state, and perhaps in the init and
term states as well. To repeat, your exit function will be called only if the user
has set the Do Group Posting parameter in the Execution block of the job file
to Yes.
In the process state, the entire dupe group will be presented to your exit function
for processing. In the master dupe, you may perform any transfer or manipulation
of data that you desire.
Remember that the format of the source and destination records (subordinate and
master dupes) are their format from the input file. The format of your output file
does not matter, because group posting is performed before the output record is
assembled.
Chapter 3: Group posting
29
Setting up double operations
You may perform group posting both internally and externally. That is, the user
may set up operations through the job file; then your exit function may perform
postprocessing or additional operations.
Job file Under this method, Group Posting blocks are used in the job file as usual. The job
file should also include a block for the group-posting report. And in the output
file block(s), the Do Group Posting parameter must be set to Yes.
Custom setup calls You r ma i n program should call three functions in the Match/Consolidate
Custom library:
Call mpc_set_gpst_num_ops() to set the number of external operations to be
performed, over and above whatever may be set up in the job file.
For example, if the job file contains three Group Posting blocks, and there are
two external group-posting operations, the argument to
mpc_set_gpst_num_ops() is 2, but five operations will appear on
the report.
Call mpc_set_gpst_name() to name your external group-posting operation(s).
Call once per operation, as necessary. This call has the same effect as the
parameter Group Post Name in the Group Posting block.
The name that you set is used on the group-posting report, simply to identify
each operation. Operations will be listed in the order that you set their names.
Internal group-posting operations are listed first, followed by the external
operations.
Call mpc_set_exit() to set up your exit function. Make sure it will be called at
least in the process state, and perhaps in the init and term states as well. To
repeat, your exit function will be called only if the user has set the Do Group
Posting parameter in the Execution block of the job file to Yes.
When called in the process state, your dupe_group_post() exit function will be
called after Match/Consolidate has performed any operations specified in the job
file. The entire dupe group, including a possibly modified master dupe, will be
presented to your exit function for processing. In the master dupe, you may
perform any transfer or manipulation of data that you desire.
Remember that the format of the source and destination records (subordinate and
master dupes) reflects their format from the input file. The format of your output
file does not matter, because group posting is performed before the output record
is assembled.
30
Match/Consolidate Custom Programmer’s Reference
Exit-support functions for group posting
Reporting results Before returning, your dupe_group_post() exit function should declare the
outcome of the operation by calling mpc_set_gpst_result().
By default, Match/Consolidate Custom assumes that your posting operations
were successfully completed, and counts them so on the group-posting report.
When an operation has some other outcome, notify Match/Consolidate Custom so
that the report will be accurate.
You may not specify any of the internal operations that were set up in the job
file. Though you are perfectly free to modify the data after an internal
operation, you may not alter the report on that operation. Any postprocessing
on your part will be reflected in a separate line on the group-posting report.
Other exit-support functions
When called in the process state, your dupe_group_post() exit function will
process groups of unknown size. One member of the group is the current record.
Initially, this is the first record in the group—the master dupe. Your exit functions
may call the following:
mpc_get_num_recs() to determine how many records are in the group.
mpc_get_num_current_rec() to determine which is the current record.
mpc_set_current_rec() to select one record to be the current record.
Match/Consolidate Custom also offers several get functions to retrieve fields or
records, or get information about the input file or fields.
Chapter 3: Group posting
31
32
Match/Consolidate Custom Programmer’s Reference
Chapter 4:
Match/Consolidate Custom library
functions
This chapter provides information that describes each function in the
Match/Consolidate Custom libraries.
Chapter 4: Match/Consolidate Custom library functions
33
mpc_get_ap_field()
Synopsis int mpc_get_ap_field(field_number, field_buffer);
int field_number application field to get (see mpgfld.h)
MPG_AP_GROUP_TYPE
MPG_AP_GROUP_RANK
MPG_AP_GROUP_ORDER
MPG_AP_LB_PRIOR
MPG_AP_PARSE
MPG_AP_LIST_CNT
MPG_AP_GROUP_CNT
MPG_AP_GROUP_NO
MPG_AP_FILE_NO
MPG_AP_LIST_NO
MPG_AP_RECORD_NO
MPG_AP_NEWLINE
MPG_AP_SL_COUNT
MPG_AP_LIST_NAME
MPG_AP_SL_NAME
MPG_AP_SL_NUMBER
MPG_AP_LIST_TYPE
MPG_AP_NAME_ERROR
MPG_AP_FIRM_ERROR
MPG_AP_ADDR_ERROR
MPG_AP_LL_ERROR
MPG_AP_GENDER
MPG_AP_PARSE_TYPE
MPG_AP_NUM_NAMES
MPG_AP_UNIQUE_NO
MPG_AP_NUM
char *field_buffer buffer to hold application field data
Description Call the mpc_get_ap_field() function to retrieve an application field for the
current record. The destination buffer must be large enough to hold the entire
field, plus one byte for the null terminator.
For a description and length of each application field, see the Quick Reference.
34
Match/Consolidate Custom Programmer’s Reference
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function, or
was called from an exit function in an invalid state. For
more information, see the “Table of exit-support functions
by exit point” on page 26.
MPC_ERR_INVFIELDNO An invalid field_number was given.
MPC_ERR_SYSTEM
Example int status;
char apbuf[64];
/* get the record number of the current record */
status = mpc_get_ap_field(MPG_AP_RECORD_NO, apbuf);
A system call failed, typically because of insufficient
memory or an I/O error.
Chapter 4: Match/Consolidate Custom library functions
35
mpc_get_db_field()
Synopsis int mpc_get_db_field(field_number, field_buffer);
int field_number database field to get (1 to n)
char *field_buffer buffer to hold data
Description Call the mpc_get_db_field() function to retrieve a database field from the current
record.
The destination buffer must be large enough to hold the entire field, plus one byte
for a null terminator.
Match/Consolidate can retrieve data much faster from its key file than from the
input files. For best performance, we recommend that whenever possible, you use
mpc_get_key_field() instead of mpc_get_db_field().
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function, or
MPC_ERR_INVFIELDNO An invalid field_number was given.
MPC_ERR_SYSTEM A system call failed, typically because of insufficient
Example int status;
char dbbuf[512];
/* get the first database field of the current record */
status = mpc_get_db_field(1, dbbuf);
was called from an exit function of an invalid state. For
more information, see the “Table of exit-support func-
tions by exit point” on page 26.
memory or an I/O error.
36
Match/Consolidate Custom Programmer’s Reference
mpc_get_error_info()
Synopsis void mpc_get_error_info(standard_message, detailed_message);
char **standard_message pointer to standard message buffer
char **detailed_message pointer to detailed message buffer
Description The mpc_err_info() function can be used to get information after a Match/
Consolidate Custom function fails. The standard_message will be set to point to
the standard error message buffer and the detailed_message will be set to point to
the detail message buffer. These message buffers will be overwritten the next time
a Match/Consolidate Custom function fails.
The detailed_message is never set.
Returns No return value.
Example int status;
/* initialize the mpc code */
if (mpc_init() != MPC_OK) {
char *standard_message, *detailed_message;
/* get the error information */
mpc_get_error_info(&standard_message, &detailed_message);
/* print an error message */
printf("mpc_init() failed: %s %s\n", standard_message, detailed_message);
break;
}
Chapter 4: Match/Consolidate Custom library functions
37
mpc_get_exit_type()
Synopsis int mpc_get_exit_type(exit_type);
int *exit_type current exit type (see mpc.h)
MPC_EXIT_READ (input processing)
MPC_EXIT_CMP_BEFORE
MPC_EXIT_CMP_AFTER_DUPE
MPC_EXIT_CMP_AFTER_NODUPE
MPC_EXIT_DUPE_GRP
MPC_EXIT_DUPE_GRP_POST
MPC_EXIT_WRITE (output processing)
MPC_EXIT_PARSE
MPC_EXIT_NUM
Description Call the mpc_get_exit_type() function to get the type of the exit function
currently executing.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function.
Example int status, type;
/* get the type of the current exit function */
status = mpc_get_exit_type(&exit_type);
38
Match/Consolidate Custom Programmer’s Reference
mpc_get_info_in_field()
Synopsis int mpc_get_info_in_field(file_number, field_number, db_field_info);
int file_number input file number (1 to n)
int field_number db field to get info on (1 to n)
MPC_DBFLDINFO *db_field_info buffer for field information
Description Call the mpc_get_info_in_field() function to get information about a database
field. It copies the information shown below into a MPC_DBFLDINFO buffer.
This type is defined in the header file mpc.h.
typedef struct {
char *title; /* field title (allocated memory) */
int position; /* starting position in the record */
int length; /* field length */
int length_text; /* field length using mpc_get_db_field */
char type; /* field type */
} MPC_DBFLDINFO;
The “title” element of the MPC_DBFLDINFO structure is allocated and
should be freed.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was not called from an exit function.
MPC_ERR_INVFILENO An invalid file_number was given.
MPC_ERR_INVFIELDNO An invalid field_number was given.
MPC_ERR_SYSTEM A system call failed.
Example MPC_DBFLDINFO db_field_info;
/* get info on the 2nd field in the first input file */
if (mpc_get_info_in_field(1, 2, &db_field_info) != MPC_OK) {
break;
}
/* print the title */
printf("title: %s\n", db_field_info.title);
/* free allocated memory */
free(db_field_info.title);
Chapter 4: Match/Consolidate Custom library functions
39
mpc_get_info_in_file()
Synopsis int mpc_get_info_in_file(file_number, db_info);
int file_number input file number
MPC_DBINFO *db_info buffer to hold info about file
Description Call the mpc_get_info_in_file() function to get information about a database file.
It copies the information shown below into an MPC_DBINFO buffer. This type is
defined in the header file mpc.h.
typedef struct {
char *name; /* database name (allocated memory) */
int num_fields; /* number of fields */
int record_length; /* record length */
} MPC_DBINFO;
The “name” element of the MPC_DBINFO structure is allocated and should
be freed.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called
MPC_ERR_IGNORED Function was not called from an exit function.
MPC_ERR_INVFILENO An invalid file_number was given.
MPC_ERR_SYSTEM A system call failed.
Example MPC_DBINFO db_info;
/* get info about the second input file */
if (mpc_get_info_in_file(2, &db_info) != MPC_OK) {
break;
}
/* print the name of the database */
printf("name: %s\n", db_info.name);
/* free allocated memory */
free(db_info.name);
40
Match/Consolidate Custom Programmer’s Reference
mpc_get_info_key_field()
Synopsis int mpc_get_info_key_field(field_number, key_field_info);
int field_number key field to get info on (see mpgfld.h)
MPC_KEYFLDINFO *key_field_info buffer to hold the key data
Description Call the mpc_get_info_key_field() function to get information about a key field.
It copies the information shown below into an MPC_KEYFLDINFO buffer. This
type is defined in the header file mpc.h.
typedef struct {
int key_length; /* field length */
int match_position; /* match position */
} MPC_KEYFLDINFO
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was not called from an exit function.
MPC_ERR_INVFIELDNO An invalid field_number was given.
Example MPC_KEYFLDINFO key_field_info;
/* get the key field info of the ZIP key field */
if (mpc_get_info_key_field(MPG_KEY_ZIP, &key_field_info) != MPC_OK)
{
break;
}
/* print the zip length */
printf("zip length: %d\n", key_field_info.key_length);
Chapter 4: Match/Consolidate Custom library functions
41
mpc_get_info_out_field()
Synopsis int mpc_get_info_out_field(field_number, db_field_info);
int field_number db field to get info on (1 to n)
MPC_DBFLDINFO *db_field_info buffer to hold the field info
Description Call the mpc_get_info_out_field() function to get information about a field in the
current output file. It copies the information shown below into the
MPC_DBFLDINFO buffer. This type is defined in the header file mpc.h.
typedef struct {
char *title; /* field title (allocated memory) */
int position; /* starting position in the record */
int length; /* field length */
int length_text; /* field length using mpc_get_db_field */
char type; /* field type */
} MPC_DBFLDINFO;
The “title” element of the MPC_DBFLDINFO structure is allocated and
should be freed.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function, or
was called from an exit function of an invalid type or
state. For more information, see the “Table of exit-sup-
port functions by exit point” on page 26.
MPC_ERR_INVFIELDNO An invalid field_number was given.
MPC_ERR_SYSTEM A system call failed.
Example MPC_DBFLDINFO db_field_info;
/* get the db field info of the output file's first field */
if (mpc_get_info_out_field(1, &db_field_info) != MPC_OK) {
break;
}
/* print the title */
printf("title: %s\n", db_field_info.title);
/* free allocated memory */
free(db_field_info.title);
42
Match/Consolidate Custom Programmer’s Reference
mpc_get_info_out_file()
Synopsis int mpc_get_info_out_file(db_info);
MPC_DBINFO *db_info buffer to hold the file info
Description Call the mpc_get_info_out_file() function to get information about the current
output file. It copies the information shown below into an MPC_DBINFO buffer.
This type is defined in the header file mpc.h.
typedef struct {
char *name; /* database name (allocated memory) */
int num_fields; /* number of fields */
int record_length; /* record length */
} MPC_DBINFO;
The “name” element of the MPC_DBINFO structure is allocated and should
be freed.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function, or was
MPC_ERR_SYSTEM A system call failed (typically because of insufficient mem-
Example MPC_DBINFO db_info;
/* get the db info of the output file */
if (mpc_get_info_out_file(&db_info) != MPC_OK) {
break;
}
/* print the name of the database */
printf("name: %s\n", db_info.name);
/* free allocated memory */
free(db_info.name);
called from an exit function of an invalid type or state. For
more information, see the “Table of exit-support functions by
exit point” on page 26.
ory or an I/O error).
Chapter 4: Match/Consolidate Custom library functions
43
mpc_get_info_pw_field()
Synopsis int mpc_get_info_pw_field(field_number, pw_field_info);
int field_number PW field to get info on (see pwfld.h)
MPC_PWFLDINFO *pw_field_info buffer to hold field info
Description Call the mpc_get_info_pw_field() function to get information about a PW field. It
copies the information shown below into an MPC_PWFLDINFO buffer. This
type is defined in the header file mpc.h:
typedef struct {
int length; /* field length */
} MPC_PWFLDINFO
Values for the PW field_number are defined in the header file pwfld.h. The
format of these definitions is similar to that of PW field names in Match/
Consolidate. However, instead of the “PW.” prefix, you should use “PW_”. For
example, in Match/Consolidate Custom you would spell the name “PW_CITY”
instead of “PW.City.”
You may find the Quick Reference a convenient source of information about
PW fields.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function, or
was called from an exit function in an invalid state. For
more information, see the “Table of exit-support func-
tions by exit point” on page 26.
MPC_ERR_INVFIELDNO An invalid field_number was given.
Example MPC_PWFLDINFO pw_field_info;
/* get the pw field info of the ZIP pw field */
if (mpc_get_info_pw_field(PW_ZIP, &pw_field_info) != MPC_OK) {
break;
}
/* print the zip length */
printf("zip length: %d\n", pw_field_info.length);
44
Match/Consolidate Custom Programmer’s Reference
mpc_get_job_step()
Synopsis int mpc_get_job_step(step);
int *step job step of the Match/Consolidate process
MPC_JOBSTEP_INIT
MPC_JOBSTEP_READ
MPC_JOBSTEP_READ_REPORTS
MPC_JOBSTEP_FIND_DUPES
MPC_JOBSTEP_MARK_DUPES
MPC_JOBSTEP_FIND_REPORTS
MPC_JOBSTEP_MERGE
MPC_JOBSTEP_POST
MPC_JOBSTEP_PURGE
MPC_JOBSTEP_STATS_FILES
MPC_JOBSTEP_PRETERM_REPORTS
MPC_JOBSTEP_TERM_REPORTS
MPC_JOBSTEP_TERM
Description Call the mpc_get_job_step() function to get information about the current job
step. It copies the information into the buffer step.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error; mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function, or was
called from an exit function of an invalid type or state.
MPC_ERR_SYSTEM A system call failed.
Example Get the current process step:
int step;
status = mpc_get_job_step(&step);
Chapter 4: Match/Consolidate Custom library functions
45
mpc_get_key_field()
Synopsis int mpc_get_key_field(field_type, field_number, field_buffer)
int field_type key field type to get (see mpgfld.h)
MPG_KEY_*
int field_number which field of that type
char *field_buffer buffer to hold the key field
Description Call the mpc_get_key_field() function to retrieve a key field. This function copies
the key field type specified by field_type into the field_buffer. The field_buffer
must be large enough to hold the entire key plus one byte for the null terminator.
Your key field length depends on what you set in the job file.
The field_number identifies which field of that type should be retrieved.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error; mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function, or
was called from an exit function of an invalid type
or state.
MPC_ERR_INVFIELDNO An invalid field_number was given.
MPC_ERR_INVFIELDTYPE An invalid field_type was given.
MPC_ERR_SYSTEM A system call failed.
Example Get the first CITY key field of the current record
int status;
char field_buffer[256];
status = mpc_get_key_field(MPG_KEY_CITY, 1, field_buffer);
46
Match/Consolidate Custom Programmer’s Reference
mpc_get_num_current_rec()
Synopsis int mpc_get_num_current_rec(current_record_number);
long *current_record_number number of current record (1-n)
Description Call the mpc_get_num_current_rec() function to find out which of the available
records is the current record. This may range from 1 to the number of records
available.
The number returned is not a record number from any file. It is simply an
integer indicating the record’s position in the set of available records. For
example, if you are manipulating a dupe group of 10 records,
mpc_get_num_current_rec() will return a number from 1 and 10, inclusive.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function, or was
called from an exit function in an invalid state. For more
information, see the “Table of exit-support functions by exit
point” on page 26.
Example long current_record_number;
int status;
/* get the number of the current record */
status = mpc_get_num_current_rec(¤t_record_number);
See also mpc_get_num_recs()
Chapter 4: Match/Consolidate Custom library functions
47
mpc_get_num_in_files()
Synopsis int mpc_get_num_in_files(num_input_files)
int *num_input_files number of input files (1 to n)
Description Call the mpc_get_num_in_files() function to find out how many input files are
involved in the current job.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function.
Example int status, num_input_files;
/* get the number of input db files */
status = mpc_get_num_in_files(&num_input_files);
48
Match/Consolidate Custom Programmer’s Reference
mpc_get_num_recs()
Synopsis int mpc_get_num_recs(num_recs);
long *num_recs number of records available
Description Call the mpc_get_num_recs() function from an exit function to find out the
number of records available for manipulation. For example, a function that
processes dupe groups needs the number of records in the current dupe group.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function, or
was called from an exit function in an invalid state. For
more information, see the “Table of exit-support functions
by exit point” on page 26.
Example long num_recs;
int status;
/* get the number of records currently available */
status = mpc_get_num_recs(&num_recs);
See also mpc_get_num_current_rec()
Chapter 4: Match/Consolidate Custom library functions
49
mpc_get_pw_field()
Synopsis int mpc_get_pw_field(field_number, field_buffer);
int field_number PW field number to get
char *field_buffer buffer to hold the PW field
Description Call the mpc_get_pw_field() function to get PW field data. This function copies
the field_number PW field into the field_buffer. The buffer must be large enough
to hold the entire field, plus one byte for a null terminator.
To get the valid field_number, use mpc_get_pw_field_id() to convert the PW
field name to the field number.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates
an error.
Example Get the CITY PW field of the current record:
int status;
char field_buffer[256];
int field_id;
if (status = (mpc_get_pw_field_id(&field_id, “CITY”) ) == MPC_OK) {
status = mpc_get_pw_field(field_id, field_buffer);
}
50
Match/Consolidate Custom Programmer’s Reference
mpc_get_pw_field_id()
Synopsis int mpc_get_pw_field_id(field_name, field_id)
char *field_name PW field name (see pwfld.h)
int *field_id buffer to hold the field identifier
Description Call this function to get the PW field number for a given field name.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function, or was
called from an exit function of an invalid type or state.
MPC_ERR_SYSTEM A system call failed.
Example Get the field identifier for the ZIP PW field:
int status;
int field_id;
status = mpc_get_pw_field_id("ZIP", &field_id);
Chapter 4: Match/Consolidate Custom library functions
51
mpc_get_record()
Synopsis int mpc_get_record(record_buffer);
char *record_buffer buffer to hold database record
Description Call the mpc_get_record() function to retrieve the contents of the current record
into a buffer.
The destination record_buffer must be large enough to hold the entire record.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function, or
was called from an exit function in an invalid state. For
more information, see the “Table of exit-support functions
by exit point” on page 26.
MPC_ERR_SYSTEM A system call failed.
Example int status;
char record_buffer[512];
/* get the current record */
status = mpc_get_record(record_buffer);
52
Match/Consolidate Custom Programmer’s Reference
mpc_init()
Synopsis int mpc_init(void);
Description The mpc_init() function initializes the Match/Consolidate Custom code. It cannot
be called from an exit function.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_IGNORED Function was called from an exit function.
MPC_ERR_SYSTEM A system call failed, typically caused by a shortage of
free memory.
Example int status;
/* initialize the Match/Consolidate Custom code */
status = mpc_init();
See also mpc_term()
Chapter 4: Match/Consolidate Custom library functions
53
mpc_process_job()
Synopsis int mpc_process_job(command_line);
char *command_line command line passed
Description The mpc_process_job() function processes a Match/Consolidate job file. The sole
argument is a complete pwmpg command line. Use the same command syntax as
when a Match/Consolidate job is started from the operating system prompt.
For command-line options, see the Quick Reference.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from an exit function.
MPC_ERR_NOARGS A blank command_line was given.
MPC_ERR_JOB The job file did not complete successfully.
MPC_ERR_SYSTEM A system call failed.
Example int status;
/* process job mail.mpg, affirm all prompts */
status = mpc_process_job("pwmpg /a mail.mpg");
See also mpc_process_jobv()
54
Match/Consolidate Custom Programmer’s Reference
mpc_process_jobv()
Synopsis int mpc_process_jobv(argc, argv);
int argc number of arguments
char **argv pointer to array of arguments
Description The mpc_process_jobv() function processes a Match/Consolidate job file. It is
useful when you wish to pass command-line arguments from the main program to
Match/Consolidate.
Use the same command syntax as when a Match/Consolidate job is started from
the operating system prompt.
If your application accepts command-line arguments that Match/Consolidate
does not, those arguments must be removed from the argv array (and argc
adjusted) before the call is made to mpc_process_jobv().
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from an exit function.
MPC_ERR_NOARGS An invalid argc was given (less than one).
MPC_ERR_JOB The job file did not complete successfully.
Example main(argc, argv)
int argc
char **argv
{
int status;
/* process job specified by the command-line arguments */
status = mpc_process_jobv(argc, argv);
See also mpc_process_job()
Chapter 4: Match/Consolidate Custom library functions
55
mpc_put_db_field()
Synopsis int mpc_put_db_field(field_number, field_buffer);
int field_number database field number to put (1 to n)
char *field_buffer buffer that holds database field data
Description After manipulating a database field, call the mpc_put_db_field() function to put it
back into the current record.
The current record number must be 1. Calling this function modifies the current
record.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function, or
was called from an exit function of an invalid type or
state. For more information, see the “Table of exit-sup-
port functions by exit point” on page 26.
MPC_ERR_INVFIELDNO An invalid field_number was given.
MPC_ERR_SYSTEM A system call failed.
Example int status;
char field_buffer[512];
/* put the first database field of the current record */
status = mpc_put_db_field(1, field_buffer);
56
Match/Consolidate Custom Programmer’s Reference
mpc_put_key_field()
Synopsis int mpc_put_key_field(field_type, field_number, is_standardized,
field_buffer);
int field_type type of key field (see mpgfld.h)
int field_number which field of this type (1 or 2)
int is_standardized standardized data or not (1 or 0)
char *field_buffer buffer to hold the PW field
Description Call the mpc_put_key_field() function to copy field_buffer into the correct key
field in the current key. It must be a null-terminated string. The field_number
identifies whether the first or second field of this type should be used. If the data
is standardized, the value of is_standardized is 1; if not, its value is 0.
This function can be called only during the name and address parse exit functions.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error; mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function,
or was called from an exit function of an invalid type
or state.
MPC_ERR_INVFIELDNO An invalid field_number was given.
MPC_ERR_INVFIELDTYPE An invalid field_type was given.
MPC_ERR_SYSTEM A system call failed.
Example Put the first prename into the key as unstandardized data
int status;
char fldbuf[256];
status = mpc_put_key_field(MPG_KEY_PRENAME, 1, 0, field_buffer);
Chapter 4: Match/Consolidate Custom library functions
57
mpc_put_record()
Synopsis int mpc_put_record(record_buffer);
char *record_buffer buffer that holds database record
Description After manipulating a record, call the mpc_put_record() function to write it over
the current record.
The current record number must be 1. Calling this function modifies the current
record.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function, or
was called from an exit function of an invalid type or state.
For more information, see the “Table of exit-support func-
tions by exit point” on page 26.
MPC_ERR_SYSTEM A system call failed.
Example int status;
char record_buffer[512];
/* replace the current record */
status = mpc_put_record(record_buffer);
58
Match/Consolidate Custom Programmer’s Reference
mpc_set_ap_field()
Synopsis int mpc_set_ap_field(field_type, field_buffer)
int field_type AP field type (see mtcfld.h)
char *field_buffer error code (see mpc.h)
Description Call the mpc_set_ap_field() function to set a value in the current key. This
function copies field_buffer into the correct application field (AP field) in the
current key. The only field types currently supported are the parse errors. The
field_buffer must be a null-terminated string. This type is defined in the header
file mpc.h.
This function can be called only during the parse exit function.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates
an error.
Example Set the AP field address parse error to invalid address:
int status;
status = mpc_set_ap_field(MPG_AP_ADDR_ERROR,
MPC_PARSE_BAD_ADDRESS_CODE);
Chapter 4: Match/Consolidate Custom library functions
59
mpc_set_current_rec()
Synopsis int mpc_set_current_rec(current_record);
long current_record current record (1 to n)
Description Call the mpc_set_current_rec() function to set which of the available records is
the current record.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function, or
was called from an exit function in an invalid state. For
more information, see the “Table of exit-support func-
tions by exit point” on page 26.
MPC_ERR_INVELEMENT An invalid current_record was given.
Example long current_record;
int status;
/* set the current record to 2 */
current_rec = 2;
status = mpc_set_current_rec(current_record);
60
Match/Consolidate Custom Programmer’s Reference
mpc_set_dupes()
Synopsis int mpc_set_dupes(decision);
int decision decision status
MPC_DECISION_YES
MPC_DECISION_NO
MPC_DECISION_UNDECIDED
Description Call the mpc_set_dupes() function to alter the decision whether two records are a
match.
When called from a compare_before exit function, all three decision values
are valid.
When called from a compare_after_dupe exit function, only the NO value
has any effect.
When called from a compare_after_nodupe exit function, only the YES value
has any effect.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function, or was
MPC_ERR_INVDCSN An invalid value for decision was given.
Example int status;
/* set the dupe decision to "not dupes" */
status = mpc_set_dupes(MPC_DECISION_NO);
called from an exit function of an invalid type or state. For
more information, see the “Table of exit-support functions
by exit point” on page 26.
Chapter 4: Match/Consolidate Custom library functions
61
mpc_set_exit()
Synopsis int mpc_set_exit(exit_type, func_ptr, call_init, call_process, call_term);
int exit_type type of exit function to set
MPC_EXIT_READ
MPC_EXIT_CMP_BEFORE
MPC_EXIT_CMP_AFTER_DUPE
MPC_EXIT_CMP_AFTER_NODUPE
MPC_EXIT_DUPE_GRP
MPC_EXIT_DUPE_GRP_POST
MPC_EXIT_WRITE
int (*func_ptr)(void) pointer to exit function
int call_init enable/disable initialization call
MPC_TRUE
MPC_FALSE
int call_process enable/disable process call
MPC_TRUE
MPC_FALSE
int call_term enable/disable termination call
MPC_TRUE
MPC_FALSE
Description
Call the mpc_set_exit() function to set up an exit function. The last three
arguments control whether the exit function will be called in the initialization,
process, and termination states, respectively.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from an exit function.
MPC_ERR_INVTYPE An invalid exit_type was given.
Example int status;
int my_read_exit(void);
/* set read exit to called during process state only */
status = mpc_set_exit(MPC_EXIT_READ, my_read_exit,
MPC_FALSE, MPC_TRUE, MPC_FALSE);
62
Match/Consolidate Custom Programmer’s Reference
mpc_set_gpst_name()
Synopsis int mpc_set_gpst_name(operation, op_name);
int operation number of operation to set
char *op_name name of the operation (max 20 chars)
Description Call the mpc_set_gpst_name() function to set the name of an external group-
posting operation. The name is a null-terminated string that may be up to 20
characters long (not counting the null character). By default, each posting
operation’s name is set to “Exit function”.
You must call mpc_set_gpst_name() from your main application, not from any
exit function.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from an exit function.
MPC_ERR_INVELEMENT Invalid operation was given.
MPC_ERR_INVLEN The length of op_name was invalid.
Example /* set the number of group posting operations to two */
if (mpc_set_gpst_num_ops(2) != MPC_OK) {
break;
}
/* set the first operation's name */
if (mpc_set_gpst_name(1, "Salvage Info") != MPC_OK) {
break;
}
See also mpc_set_gpst_num_ops()
Chapter 4: Match/Consolidate Custom library functions
63
mpc_set_gpst_num_ops()
Synopsis int mpc_set_gpst_num_ops(num_ops);
int num_ops number of group posting operations
Description Call the mpc_set_gpst_num_ops() function to set the number of external group-
posting operations to be performed by the dupe_group_post() exit function.
This setting only affects the Posted Dupe Groups Report. Each operation will be
displayed as a line in the report.
The default number of operations is 1. Your value must be greater than or equal to
zero. Do not count any operations set up by blocks in the job file.
You must call mpc_set_gpst_num_ops() from your main application, not from
any exit function.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from an exit function.
MPC_ERR_INVELEMENT An invalid num_ops was given.
MPC_ERR_SYSTEM A system call failed.
Example int status;
/* set the number of group posting operations to two */
status = mpc_set_gpst_num_ops(2);
See also mpc_set_gpst_name()
64
Match/Consolidate Custom Programmer’s Reference
mpc_set_gpst_result()
Synopsis int mpc_set_gpst_result(operation, result);
int operation group posting operation
int result result of the group posting operation
MPC_GPST_RESULT_COMPLETE
MPC_GPST_RESULT_PURGE
MPC_GPST_RESULT_DSTFLD
MPC_GPST_RESULT_FILTER
Description
Before returning, your dupe_group_post() exit function should declare the
outcome of the group-posting operation by calling the mpc_set_gpst_result()
function. By default, Match/Consolidate Custom assumes that your group-posting
operations were successfully completed, and counts them accordingly on the
group-posting report. When an operation has some other outcome, notify Match/
Consolidate Custom so that the report will be accurate.
The first argument is a number identifying the operation. External operations are
numbered 1, 2, 3, and so on, according to the sequence of your calls to
mpc_set_gpst_name(). Possible results include the following:
Result Description
Complete Successful completion (default).
Purge The operation was canceled because the group members were purge-
type. For more information, see the parameter Group Post to the Purge
Lists.
Hint:
Call mpc_get_ap_field() and check the value of
MPC_AP_GROUP_TYPE.
Dest_field The operation was canceled because the destination field that was speci-
fied does not exist in the destination record.
Filter The operation was canceled because the group-posting filter returned
False. For more information, see the Group Posting Filter parameter.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function,
or was called from an exit function of an invalid type
or state. For more information, see the “Table of exit-
support functions by exit point” on page 26.
MPC_ERR_INVELEMENT An invalid operation
MPC_ERR_INVDCSN An invalid result was given.
Chapter 4: Match/Consolidate Custom library functions
was given.
65
mpc_set_group_pos()
Synopsis int mpc_set_group_pos(group_pos);
long group_pos position in dupe group
Description Call the mpc_set_group_pos() function to set the position in the dupe group of the
current record. The position of other group members will be adjusted as
necessary.
The sole argument is the new position of the current record in the dupe group.
This may range from 1 to the number of members in the dupe group; to find that
number, call mpc_get_num_recs(). Please note that we are using a long integer
here, instead of the character designations used in the Match/Consolidate
application field AP.Group_Rank.
The mpc_set_group_pos() function should only be called from the dupe_group()
exit function in the process state. After mpc_set_group_pos() returns, the same
record is still the current record, but it has a new position in the dupe group, so
mpc_get_num_current_rec() would yield a different result.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function,
MPC_ERR_INVELEMENT An invalid group_pos was given.
MPC_ERR_SYSTEM A system call failed.
Example long group_pos;
int status;
/* set the group position of the current record to 2 */
group_pos = 2;
status = mpc_set_group_pos(group_pos);
or was called from an exit function of an invalid type
or state. For more information, see the “Table of exit-
support functions by exit point” on page 26.
66
Match/Consolidate Custom Programmer’s Reference
mpc_set_process()
Synopsis int mpc_set_process(decision);
int decision decision whether to process the record
MPC_DECISION_YES
MPC_DECISION_NO
Description
Call the mpc_set_process() function to pre-empt the Match/Consolidate decision
whether or not the current record is to be processed.
When called from an input_processing() or an output_processing() exit function,
both decision values are valid, though only the no value has effect.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function,
or was called from an exit function of an invalid type
or state. For more information, see the “Table of exit-
support functions by exit point” on page 26.
MPC_ERR_INVDCSN An invalid value for decision was given.
Example int status;
/* set the process decision to "process" */
status = mpc_set_process(MPC_DECISION_YES);
Chapter 4: Match/Consolidate Custom library functions
67
mpc_set_unique()
Synopsis int mpc_set_unique(decision);
int decision decision whether the record is unique
MPC_DECISION_YES
MPC_DECISION_NO
MPC_DECISION_UNDECIDED
(default)
Description
Call the mpc_set_unique() function to pre-empt the Match/Consolidate decision
whether or not the current record is unique. If you call mpc_set_unique() with the
argument MPC_DECISION_YES, a flag will be set in the key file, and the
current record will be excluded from the search for duplicates.
By default, the unique decision is set to MPC_DECISION_NO.
The arguments MPC_DECISION_NO and MPC_DECISION_UNDECIDED are
accepted, but they have no effect.
The mpc_set_unique() function can be called only from the input_processing()
exit function in the process state.
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to one of the following values:
Value Description
MPC_ERR_UNINIT mpc_init() was not called.
MPC_ERR_IGNORED Function was called from other than an exit function,
or was called from an exit function of an invalid type
or state. For more information, see the “Table of exit-
support functions by exit point” on page 26.
MPC_ERR_INVDCSN An invalid value for decision was given.
Example int status;
/* set the unique decision to "unique" */
status = mpc_set_unique(MPC_DECISION_YES);
68
Match/Consolidate Custom Programmer’s Reference
mpc_term()
Synopsis int mpc_term(void)
Description Call the mpc_term() function to terminate the Match/Consolidate Custom code.
This function frees memory allocated by mpc_init().
Returns Returns MPC_OK if successful. A return value of MPC_ERROR indicates an
error, and mpc_errno is set to this value:
Value Description
MPC_ERR_IGNORED Function was called from an exit function.
Example int status;
/* terminate the Match/Consolidate custom session */
status = mpc_term();
See also mpc_init()
Chapter 4: Match/Consolidate Custom library functions
69
simscore()
Synopsis int simscore(string1, length1, string2, length2)
char *string1; pointer to first string
int length1; length of first string
char *string2; pointer to second string
int length2; length of second string
Description The simscore() function, like the Simscore executable, enables you to compare
the similarity of two strings.
You may call simscore() from any exit function in any state. Most often,
simscore() will be used in the compare_before() and compare_after_dupe() exit
functions.
For more information on Simscore and the meaning of scores, see the User’s
Guide to Record Matching.
Returns Returns the percentage of similarity between two strings as an integer.
Example int percent;
percent = simscore(str1, len1, str2, len2);
printf(“\n%s and %s are %d percent alike\n”, str1, str2, percent);
70
Match/Consolidate Custom Programmer’s Reference
Index
A
AP field
get data, 34
set value in current key, 59
C
command line, 54, 55
compare_after_dupe() exit function, 20
compare_after_nodupe() exit function, 21
compare_before() exit function, 18
comparisons cancelled, 18
compile/link lines, 11
D
database field
, 36
get data
get information about, 39, 42
put back into record, 56
dupe_group() exit function, 22
dupe_group_post() exit function, 23, 31
dupes
alter decision
dupe groups, 22, 23
, 61
E
error handling, 15
error information, 37
exit functions, 15, 26
compare_after_dupe(), 20
compare_after_nodupe(), 21
compare_before(), 18
dupe_group(), 22
dupe_group_post(), 23, 31
input_processing(), 16
output_processing(), 24
parse(), 25
states, 14, 15, 26
F
Find Duplicates
compare_after_dupe() exit function
compare_after_nodupe() exit function, 21
compare_before() exit function, 18
dupe_group() exit function, 22
G
group posting, 27
declare outcome, 65
dupe_group_post() exit function, 23
exit support functions, 31
external, 29
, 20
internal and external, 30
options, 28
set name, 63
set number of operations, 64
H
header files, 15
I
init state, 14, 26
initialization, 53
input_processing() exit function, 16
K
key field
copy into current key, 57
get data, 46
get information about, 41
key file, 15
M
master dupes, 22
mpc.h, 15
mpc_get_ap_field(), 34
mpc_get_db_field(), 36
mpc_get_error_info(), 37
mpc_get_exit_type(), 38
mpc_get_info_in_field(), 39
mpc_get_info_in_file(), 40
mpc_get_info_key_field(), 41
mpc_get_info_out_field(), 42
mpc_get_info_out_file(), 43
mpc_get_info_pw_field(), 44
mpc_get_job_step(), 45
mpc_get_key_field(), 46
mpc_get_num_current_rec(), 47
mpc_get_num_in_files(), 48
mpc_get_num_recs(), 49
mpc_get_pw_field(), 50
mpc_get_pw_field_id(), 51
mpc_get_record(), 52
mpc_init(), 53
mpc_process_job(), 54
mpc_process_jobv(), 55
mpc_put_db_field(), 56
mpc_put_key_field(), 57
mpc_put_record(), 58
mpc_set_ap_field(), 59
mpc_set_current_rec(), 60
mpc_set_dupes(), 18, 20, 21, 61
mpc_set_exit(), 29, 30, 62
mpc_set_gpst_name(), 29, 30, 31, 63
Index
71
mpc_set_gpst_num_ops(), 29, 30, 64
mpc_set_gpst_result(), 31, 65
mpc_set_group_pos(), 22, 66
mpc_set_process(), 16, 24, 67
mpc_set_unique(), 16, 68
mpc_term(), 69
mpc_test.c, 11
multiline address comparison, 18
N
name_address_parse(), 25
O
output file
exit function, 24
get information about, 43
output_processing() exit function, 24
P
parse() exit function, 25
performance, 15
compare_after_dupe() exit function, 20
compare_after_nodupe() exit function, 21
compare_before() exit function, 18
prioritization of dupes, 22
process a Match/Consolidate job, 54, 55
process state, 14, 26
PW field
get data, 50
get field number, 51
get information about, 44
R
rate of processing, 15
Read Records processing step, 16
record
get contents of, 52
mark as unique (or not), 68
number for current record, 47
set current, 60
set position in dupe group, 66
set to be processed, 67
total number available, 49
write over current record, 58
S
setup library, 10
simscore(), 70
speed of processing, 15
states, 14
subordinate dupes, 22
T
term state, 14, 26
termination, 69
U
UNIX compiler/linker, 11
W
Windows compiler/linker, 11
work files, 15
72
Match/Consolidate Custom Programmer’s Reference
Loading...