Only used if your application is calling the SSA-NAME3 Server, otherwise it should be set to

-1

. If using the SSA-NAME3 server, the

ssan3_connect

call will allocate a valid socket handle which should then be used on all subsequent calls.

Should be either -1 on the

ssan3_open

call, if opening a new session, or a valid Session ID (as returned from

ssan3_open

) on any other call. For more information on Sessions, refer to SSA-NAME3 Sessions.

Qualifies and defines the location of the Population Rules to be used in the call. It corresponds to the name of the sub-directory (within the

pr

directory), or low-level extension of the PR dataset in z/OS environments, in which the Population Files (YSPs, YCPs or YLPs) are stored.

The name of the Population rule set to be used. This generally corresponds to a Country/Language rule set (example, Australia, Brazil, UK, and USA); however, it could be any set of rules, especially if using a Custom Population (example, English Song Titles, or USA OFAC). Use the Population that corresponds to the data you are using. SSA-NAME3 will search for the Population in the location defined by the

SSAPR

environment variable and System parameter. It will search for Populations in the following order:

Population.ylp
(Local Population)
Population.ycp
(Custom Population)
Population.ysp
(Standard Population)

When calling many of the API functions, it is necessary to specify "Controls" to be used. These Controls define and refine the behaviour of the function. The format and content of the Controls will be dependent on the function being called and are described in the Controls section.

Indicates the success or failure of a call to SSA-NAME3. A Response Code value of zero indicates a successful call. If the Response Code is not zero, then a description of the problem will be reported in the Error Message parameter.

The SSA-NAME3 calls

ssan3_get_keys_encoded

,

ssan3_get_ranges_encoded

and

ssan3_match_encoded

all require data to work on. This is the user’s identity data and will take the form of names, addresses, ID numbers, dates and other attributes. The name of the parameter for

ssan3_get_keys_encoded

and

ssan3_get_ranges_encoded

is Key Field Data, and for the

ssan3_match_encoded

call is Search Data and File Data.

Key Field Data contains the field value(s) to be used for the building of the SSA-NAME3 Keys when using the

ssan3_get_keys_encoded

function and for building search ranges when using the

ssan3_get_ranges_encoded

function.

Search Data contains the field value(s) from the search or transaction record (example, taken from a screen or input file) to be used to compare against the File data in an

ssan3_match_encoded

call.

File Data contains the field value(s) from the file record (example, the candidate record) to be used to compare against the Search data in an

ssan3_match_encoded

call.

The data fields required for each Key-Field or Match Purpose are shown in the Developer’s Workbench for your Population.

Any field can be repeated. An example of a repeating field might be passing a person’s current name and their former name in the one call for key-building.

The data can be provided by the calling application in either of two formats:

Tagged Data Format (the default)

The Tagged Data Format is the default method of supplying data in the

ssan3_get_keys_encoded

,

ssan3_get_ranges_encoded

and

ssan3_match_encoded

function calls.

By using the Tagged Data Format, the offsets and lengths of the data fields being passed do not need to be specified. Instead, a notation of field-names and delimiters is used to break up the fields. The field names are reserved words. The field names available for your Population rule-set can be found in the Developer’s Workbench.

Note the use of the 3 delimiters to terminate the data. For example, if building keys for a Person’s Name, the format would be similar to:

*Person_Name*Jane Smith***

Where

Person_Name

is the field name, the "*" is the delimiter, and "Jane Smith" is user-supplied data.

An example of building keys on a repeating field (in this case, current name and former name):

*Person_Name*Jane Smith*Person_Name*Jane Brown***

The following example shows the data supplied to an

ssan3_match

call for a Match Purpose that is using a person’s name and address. The tagged data format for the

Search

and

File

Data will look like:

*Person_Name*Andrew Barker*Address_Part1*23 Acacia Drive Sheffield*Address_Part2*Yorkshire

Where

Person_Name

and

Address_Part1

are the field names, the "*" is the delimiter, and the rest is user-supplied data.

A special format exists for Filters used in Multi-Purpose matching. This format is as follows:

*Filtern*<single value>

or

*Filtern(List(value1,value2,... valuen)

For more information on Filters, refer to the Controls section for the

ssan3_match

call.

By default the delimiter is an asterisk, however, it can be overridden by using the

DELIMITER=

Control in the appropriate function call.

If your data can contain asterisks, make sure that these are either cleaned out prior to calling the SSA-NAME3 functions, or use a different

DELIMITER=

setting.

It is possible to pass redundant data as part of the Tagged Data Format string, meaning that the application program can make use of the same structure when calling

ssan3_get_keys

,

ssan3_get_ranges

or

ssan3_match

.

Scatter/Gather Format

A Scatter/Gather data format can also be used to supply data with the

ssan3_get_keys_encoded

,

ssan3_get_ranges_encoded

and

ssan3_match_encoded

function calls.

There are three formats:

Offset1,Length1,... ,Offsetn,Lengthn

and

Field1,Offset1,Length1,... ,Fieldn,Offsetn,Lengthn
Field1,Offset1,Length1,Encoding1... ,Fieldn,Offsetn,Lengthn,Encodingn

The first format may be used when passing Key Field Data to the

ssan3_get_keys_encoded

and

ssan3_get_ranges_encoded

calls. The second format must be used when passing Search Data and File Data to the

ssan3_match_encoded

call, and may also be used to pass Key Field Data. The third format can be used when passing Search Data and File Data to the

ssan3_match_encoded

call, and may also be used to pass Key Field Data.

Following are all valid scatter / gather examples for passing

Key Field Data

:

FIELD=Person_Name Layout=0,50

Passes a single name, to be found at offset 0 in the

Key Field Data

parameter, for a length of 50.

FIELD=Person_Name Layout=0,50,50,50

Passes two names (example, a current name and a former name). The first name is found at offset 0 in the

Key Field Data

parameter, for a length of 50. The second name is found at offset 50 in the

Key Field Data

, also for a length 50.

FIELD=Person_Name Layout=Person_Name,0,50

Passes a single name, to be found at offset 0 in the

Key Field Data

parameter, for a length of 50.

FIELD=Person_Name
Layout=Person_Name,0,50,Person_Name,50,50

Passes two names (example, a current name and a former name). The first name is found at offset 0 in the

Key Field Data

parameter, for a length of 50. The second name is found at offset 50 in the

Key Field Data

, also for a length 50.

FIELD=Person_Name Layout=Person_Name,0,50,
Address_Part1,50,50

Passes a single name, to be found at offset 0 in the Key Field Data parameter, for a length of 50.

Address_Part1

is ignored.

The following example shows the valid scatter / gather formats for passing Search and File Data to the

ssan3_match_encoded

call:

PURPOSE=Resident Search=Person_Name,0,50,
Address_Part1,50,100,Address_Part2,150,50
File=Person_Name,0,50,Address_Part1,50,100,
Address_Part2,150,50

Passes a single name, to be found at offset 0 in the

Key Field Data

parameter, for a length of 50, a single street address, to be found at offset 50, for a length of 100, and a single locality line, to be found at offset 150, for a length of 50.

PURPOSE=Resident Search=Person_Name,0,50,
Person_Name,200,50,Address_Part1,50,100,
Address_Part2,150,50 File=Person_Name,0,50,
Person_Name,200,50,Address_Part1,50,100,
Address_Part2,150,50

Passes a single name (example, current name), to be found at offset 0 in the Key Field Data parameter, for a length of 50, a single street address, to be found at offset 50, for a length of 100, a single locality line, to be found at offset 150, for a length of 50, and another name (e.g. a former name), to be found at offset 200, for a length of 50.

PURPOSE=Resident Search=Organization_Name,0,50,
Person_Name,50,50,Address_Part1,100,100,
Address_Part2,200,50 File=Organization_Name,0,50,
Person_Name,50,50,Address_Part1,100,100,
Address_Part2,200,50

Passes a single name, to be found at offset 50 in the Key Field Data parameter, for a length of 50, a single street address, to be found at offset 100, for a length of 100, and a single locality line, to be found at offset 200, for a length of 50.

PURPOSE=Resident Search=Organization_Name,0,50,8,
Person_Name,50,50,8,Address_Part1,100,100,8,
Address_Part2,200,50,8 File=Organization_Name,0,50,8,
Person_Name,50,50,8,Address_Part1,100,100,8,
Address_Part2,200,50,8

This is the same as the previous example except it also specifies the encoding for each field. In this example the encoding is ’8’ for UTF-8. The encoding can be different for each field. The values are as described for the

UNICODE_ENCODING¯

Control.

By using the syntax that includes the field name, it is possible to pass redundant fields which will be ignored by the function. The function will only access the fields needed by the Key Field Data or Match Purpose. In this way, the calling application can use a common data structure for

ssan3_get_keys_encoded

,

ssan3_get_ranges_encoded

and

ssan3_match_encoded

.

It is highly recommend that the scatter/gather format be used in all cases where the data is not in the same character set.

Whichever format is used to pass the data, either Tagged or Scatter/Gather, the maximum number of fields which may be passed in a single call is 256.

The length for each field in the scatter/gather or tagged format is 2048. There is no limit to the total length of the Data Field other than that imposed by the programming language.

The three SSA-NAME3 calls,

ssan3_get_keys_encoded

,

ssan3_get_ranges_encoded

and

ssan3_match_encoded

all require the length of the Data field to be supplied.

The three SSA-NAME3 calls,

ssan3_get_keys_encoded

,

ssan3_get_ranges_encoded

and

ssan3_match_encoded

, all require the data type or encoding. The encoding could be one of the Unicode encodings or a standard single or double byte character encoding.

The valid values for this field are:

Encoding	Meaning
TEXT	Data is not in a Unicode encoding
UTF-8	Unicode UTF-8 format
UTF-16	Unicode UTF-16 format
UTF-16LE	Unicode UTF-16 format Little Endian
UTF-16BE	Unicode UTF-16 format Big Endian
UTF-32	Unicode UTF-32 format
UCS-2	Same as Unicode UTF-16 format
UCS-4	Unicode UTF-32 format
CP932	Japanese CP932 Codepage (shift-JIS)
CP936	Chinese CP936 Codepage (GBK or Simplified Chinese)
CP949	Korean CP949 Codepage
CP950	Chinese CP950 Codepage (Big5 or Traditional Chinese)
UTF8	All keywords can be specified witout the "-"

There are short forms for these values:

Encoding	Meaning
Y	Unicode UTF-8 format
8	Unicode UTF-8 format
6	Unicode UTF-16 format
L	Unicode UTF-16LE format
B	Unicode UTF-16BE format
4	Unicode UCS-4 or UTF-32 format
J	Japanese CP932 codepage (Shift-JIS)
S	Chinese CP936 codepage (Simplified Chinese)
K	Korean CP949 codepage
T	Chinese CP950 codepage (Traditional Chinese)