The name of the Service as defined in the Service Group definition. The supplied Fast-start Service Group definitions simply use the name

MATCH.

This parameter is filled in by the Service to indicate the success or otherwise of the Call, a value of

00

in the first two positions indicates that all was well, any other value flags a warning or an error. For a description on how to check Response Codes, turn to the

How an Application Should Test the Response Code

section.

The

Function

parameter is used to control what type of results are returned by

MATCH

to the calling program. An example of a result is a Score.

A

MATCH

Function is comprised of one or more

MATCH

Function Keywords, initiated and terminated by an asterisk(*). The maximum length of the total Function specification is 1024 bytes. Here is an example of a valid Function,

*SCORE-ONLY*

The

MATCH

Function can also be defined in the Service Group definition as a

MATCH

Function ’definition’, and given a name. See the Service Group section in the

DEFINITION and CUSTOMIZATION GUIDE FOR SSA-NAME3 SERVICE GROUPS

for more details. The

MATCH

Function definition ’name’ is then passed as a parameter instead of the explicit Function keywords. For example, if the Service Group definition contains:

FUNCTIONS-DEFINITION
SCORE:SCORE-ONLY

Then, when calling the

MATCH

Service, the predefined function name ’

SCORE

’ can be used instead of the explicit keyword

SCORE-ONLY

. When a Function definition name is used, it must be left justified in a 32 byte field and padded with spaces. Note that no * are used around the Function definition name.

The

Function

parameter can contain a combination of both

Function

keywords and Function definitions, by use of the

BASE=

keyword. For example,

*BASE=SCORE,MTBL=208*

would use both the Function definition keywords specified by

SCORE

as well as the keyword

MTBL=

.

MATCH

Functions or Function definition names can also be defined within the Matching Scheme definition.

MATCH

Function keywords are fully described in the Service Group section of the

DEFINITION and CUSTOMIZATION GUIDE FOR SSA-NAME3 SERVICE GROUPS

. Some important keywords are:

Keyword	Description
SCORE-ONLY	Return only a 3-byte Score in the Result parameter.
VERBOSE	Specifies that the Result parameter field will contain results in a label=value syntax rather than fixed formatted.
ACCEPT-LIMIT=	Specifies a score equal to and above which a record will be ruled ’accepted’.
REJECT-LIMIT=	Specifies a score below which a record will be ruled ’rejected’.
LIMIT=	Used instead of specifying both ACCEPT-LIMIT and REJECT-LIMIT to set ACCEPT-LIMIT/REJECT-LIMIT to the same value
MTBL=n	Return a Method table of n bytes in the Method-table parameter. Where n is calculated as follows: (25 + (number of methods * 61) + 4) Or, if NEW-MTBL is also specified: (25 + (number of methods * 67) + 4)
NEW-MTBL	Return an extended Method table showing the position of the fields that matched in a multi-valued matching field, ie. using REPEAT= keyword. (Requires MTBL= to be specified.) Only available in Matching Method, N3SCM .
EXTRACT=	Used to extract the result value from a verbose label=value Result parameter field.
NULL-SCORE=	Specifies a score between 0-100 to be returned if the sum of weights from all matching methods in a scheme is zero.
FIELDS=	Override, at run-time, the length and offset of a field specified in the matching scheme. Format is FIELDS=ooooolllllrrrrr (i.e. offset|length|repeat count ).
SCACHE=	Specify an additional work-area to be used to cache the processed search record, saving on repetitive processing for each match call. Format is SCACHE=oooooollllll (i.e. offset|length into work-area for additional work-area).
EARLY=	Specify a score that the first method in a multi-method scheme must achieve, or the entire record will be rejected. Format is EARLY=nnn , where nnn specifies the threshold score.

The Scheme name as defined in the Matching Scheme Definition File. A Scheme is a collection of rules describing how two records should be compared. It must be pre-defined before it can be used by an application program. The Matching Scheme Definition File may have been set up to contain a number of different Scheme Definitions. These are identified by lines of the following type in the Definition File:

SCHEME-NAME=Scheme Name

The programmer must ensure they are using the correct Scheme for their application and that the layout of the Scheme matches the layout of the Search and File records defined below.

One of the names or records to be matched. This is usually the reference record against which other records will be matched. The size and structure of the Search Record must be as defined in the Matching Scheme definition file for the Scheme Name being used.

The other record to be matched. The File Record must have the same size and structure as the Search Record.

This parameter contains the result (or results) of the

MATCH

Service Call. Its length and contents depend on the setting of the Function parameter.

OPTION 3 - If the Function contains a keyword of

VERBOSE

, this parameter will contain results in a

label=value

format. Each

label=value

entry is separate by a comma and the last entry is terminated with an asterisk (*). The length of the Result parameter using this option should be 19. The result value of a specific label can be extracted on a subsequent Call to MATCH by using the

EXTRACT=label

function. For more information on how to perform this Call, see the

EXTRACT= Call

section. The labels which can currently be returned are,

Result Field Label	Description
SCORE=	Always returned. This Result label precedes a 3-byte character representation of the score. The score has a value between 000 and 100. For example, if two records achieve a score of 80, the Result field will contain: SCORE=080*
RULING=	Returned if any one of ACCEPT-LIMIT= , REJECT-LIMIT= or LIMIT= are specified as Function keywords. The RULING= Result label precedes a 1-byte character which identifies the judgment on the matched records. The judgment can be either ’Accept’ (" RULING=A "), ’Reject’ (" RULING=R "), or ’Undecided’ (" RULING=U "). For example, if two records achieve a score of 80 and ACCEPT-LIMIT=70 is specified as a Function, the Result field will contain: SCORE=080,RULING=A*

A Matching Scheme consists of one or more Matching Methods which are used by the

MATCH

Service to compare like fields in the Search & File records. There are Matching Methods available for Strings, Dates, Names & Addresses, and other special purposes. These are explained in detail in the Matching Scheme Definition section of the

DEFINITION & CUSTOMIZATION GUIDE FOR SSA-NAME3 SERVICE GROUPS

.

The Method Table (MTBL) contains the details of what Methods were used by a Scheme and the individual match results they achieved.

It is composed of a header and n elements, where n represents the number of Methods called. Each method creates an entry in the table to describe its parameters and matching result. The table is terminated with a 4-byte terminator entry.

To obtain a Method table, the

MTBL=

function keyword and value must be specified. If it is not specified, this parameter must still exist and can be set to 1-byte.

The MTBL header is 25 bytes and is composed of the following fields:

Offset	Size	Description
0	4	Total MTBL length (inclusive)
4	4	Table-id, always " MTBL "
8	3	Table header size
11	3	Table entry size
14	3	Number of table entries
17	8	Scheme Name

The header is followed by a variable number of 61-byte MTBL entries:

Offset	Size	Description
0	8	Method Name
8	8	Method Entry-point Name
16	8	Algorithm associated with this method
24	5	Field offset
29	3	Field length
32	20	Response code from method
52	3	Method score
55	3	Method weight
58	3	Method weight modifier

If the

NEW-MTBL

keyword is also specified, an additional 6 bytes are added to a Method table entry, increasing it to 67 bytes:

Offset	Size	Description
61	3	First matching search record field occurrence (occurrence 1 = 000)
64	3	First matching file record field occurrence (occurrence 1 = 000)

To determine the size of the

MTBL=

keyword value, refer to the Service Group/MATCH Function Keywords section of the

DEFINITION and CUSTOMIZATION GUIDE FOR SSA-NAME3 SERVICE GROUPS

.

A general purpose Work-area used by the Service.

For examples of how to invoke the

MATCH Service

, refer to the

Pseudo Code Examples

section.