PAGC Library Function Reference

pagc_init

Prototype

PAGC_DLL_HANDLE_RET pagc_init( int , const char * ,const char * )

Short Description

Returns to the client a handle (PAGC_HANDLE) with which to access pagc functions. This function opens the library for use.

Arguments

Arg1: Boolean (int) 1 or 0 : Log (1) or (0) don't log initializations.

Arg2: Pointer ( const char *) to a NUL-terminated string that is the pathname for the directory to look first for the standardization files. This pointer can be set to NULL if the files are in one of the standard locations.

Arg3: Pointer ( const char *) to NUL-terminated string -- the file name for the error log to create. This pointer can be set to NULL if no error log is to be created.

Returns

NULL error. See global error log for error details
PAGC_HANDLE on success

pagc_close

Prototype

PAGC_DLL_RET pagc_close( PAGC_HANDLE )

Short Description

Called by client with the PAGC_HANDLE to close and exit the library. pagc_close will close any open matching contexts or schemas. Do not use the PAGC_HANDLE after calling this function.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init).

Returns

0 error - see global log for error details
1 success

pagc_add_schema

Prototype

PAGC_DLL_RET pagc_add_schema( PAGC_HANDLE , const char * , int , int )

Short Description

Function for client to add a built schema (a schema created at some prior time with pagc_create_schema to the matching process by providing the shapeset pathname. The integer returned is the schema index for this reference and serves as a handle. The function determines if the reference has been built by looking for a .pgc file for the reference pathname.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: Pointer ( const char * ) to the NUL-terminated string giving the pathname for the reference dataset. No extension. This will be the directory in which the dataset was build using pagc_create_schema on some earlier occasion.

Arg3: This int (int) should be set to 0

Arg4: Boolean (int) 1 or 0 : Log initialization of the schema. Initialization log entries will go to the log specified in pagc_init

Returns

0 error - see global log for error details
a number (int) that serves as the schema index

pagc_add_context

Prototype

PAGC_DLL_RET pagc_add_context( PAGC_HANDLE , int , int , int , const char * )

Short Description

Used to create a matching context. A matching context will be bound to a schema index, which indicates an open, pagc-normalized dataset. Client matching against this schema occurs within the context, as well as do all scoring and geocoding. The context index obtained from this function serves as a handle.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The schema index (int). (obtained from pagc_add_schema).

Arg3: The scoring strategy ( int ) for the matching context. Set to 0 if only using this context for addresses and 1 if only using this context for intersections. Set to 2 if geocoding both intersections and addresses.

Arg4: Boolean ( 1 or 0 ) switch. If true (1), a context-specific error log is created. Errors encountered in matching will be recorded in this log. Clients can add errors in this log using pagc_register_context_error and retrieve them using pagc_fetch_context_error.

Arg5: Pointer ( const char *) to the NUL-terminated string that gives the filename for the context error log. No extension.

Returns

0 error - see global log for error details
a number (int) that serves as the context index

pagc_reset_context_schema

Prototype

PAGC_DLL_RET pagc_reset_context_schema( PAGC_HANDLE , int , int )

Short Description

This function switch the schema currently associated with the context with a new one. This function is used when a matching context wishes to switch between two schemas within a matching session.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The new schema index (obtained from pagc_add_schema).

Arg3: The context index(int). (obtained from pagc_add_context). This integer specifies which matching context is being used.

Returns

0 error - see context log for error details
1 success

pagc_get_schema_flags

Prototype

PAGC_DLL_RET pagc_get_schema_flags( PAGC_HANDLE , int , unsigned int * )

Short Description

This function returns in the third argument, a pointer to an unsigned int, the schema's flags OR'd together. This permits the client, by checking the proper bit, to see if a particular flag is set for this schema.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The schema index (int). (obtained from pagc_add_schema).

Arg3: Integer Output Pointer (unsigned int *) to which the flags should be copied.

Returns

0 error - see context log for error details
1 success

pagc_match_item

Prototype

PAGC_DLL_RET pagc_match_item( PAGC_HANDLE , int , char * , char *, char * , char * , int , int )

Short Description

This function performs the matching function. The address provided is matched against the reference database. This function is used for both site and intersection addresses. The function distinguishes between the two on the presence or absence of a second street name string (Arg4). The main effect of this function is to produce a matched candidate list (stored internally). The candidates collected onto this list are not, initially, geocoded.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context). This integer specifies which matching context is being used.

Arg3: A Pointer (char * to the NUL-terminated string giving the Street Number Street Name and Occupancy query line.

Arg4: A Pointer (char *) to the NUL-terminated string giving the second street (for INTERSECTION). Must be NULL for non-intersection queries.

Arg5: A Pointer (char *) to the NUL-terminated string giving the City, State, Postal and Nation query data.

Arg6: A Pointer (char *) to the NUL-terminated string giving City, State, Postal and Nation query data.

Arg7: This argument (int) is reserved for future use -- it should be set to 0.

Arg8: A flag to retain candidates from previous matching. (int). It is 1 if they are to be retained, otherwise 0. The effect obtained is to add (by score) the candidates of this matching to the candidates obtained in the previous matching. It should be set to 0 unless this effect is desired. This flag is intended to allow the client to match adaptively (try various variations of the query address) and combine the best of the results.

Returns

-2, error (see context log).
-1, could not standardize
0, no candidates
1, candidates
2, perfect match : one candidate

pagc_set_intersection_cutoff

Prototype

PAGC_DLL_RET pagc_set_intersection_cutoff( PAGC_HANDLE , int , int , double )

Short Description

This function sets the intersection cutoff distance.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context)

Arg3: Boolean (int) 1 or 0 : if 1 all distinct points in an intersection are to be collected.

Arg4: The cutoff distance for points to be considered in an intersection. double. If Argument 3 is 1, then the fourth argument is ignored and the default cutoff of 30 meters is used.

Returns

0 error - see context log for error details
1 success

pagc_geocode_intersection_candidate

Prototype

PAGC_DLL_RET pagc_geocode_intersection_candidate( PAGC_HANDLE , int , int , PAGC_POINT * )

Short Description

Function to get the coordinates (latitude and longitude) of a given intersection candidate.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context)

Arg3: The candidate number (int). This is the number of a candidate on the context's matched candidate list. The first candidate's candidate number is 0. This arg must not equal or exceed the number of candidates (obtained from pagc_numb_cands)

Arg4: Pointer to the point (PAGC_POINT in which the coordinates are to be stored. A PAGC_POINT is typedef'd as a structure containing two doubles, the first for the latitude and second for the longitude.

Returns

0 error - see context log for error details
1 success

pagc_geocode_address_candidate

Prototype

PAGC_DLL_RET pagc_geocode_address_candidate( PAGC_HANDLE , int , int , PAGC_POINT * ,int * , double )

Short Description

Function to get the coordinates of a given address candidate.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context)

Arg3: The candidate number (int). This is the position of a candidate on the context's matched candidate list. The first candidate's candidate number is 0. This arg must not equal or exceed the number of candidates (obtained from pagc_numb_cands)

Arg5: Pointer ( int * ) to which the interpolation house number for SITE_INTERPOLATE is stored. This is provided to the client for use in formating an interpolated address using a block range reference record with pagc_format_address

Arg6: double giving distance from street to locate an interpolated point (for SITE_INTERPOLATE). (double)

Returns

-1, error (see context log)
0, not geocodable ( address doesn't fit into a blockrange )
1, success, with the coordinates copied to the location indicated by the fourth argument.

pagc_create_schema

Prototype

PAGC_DLL_RET pagc_create_schema( PAGC_HANDLE , char * , char * , unsigned int , int , int )

Short Description

This is the function that builds the normalized reference database and the schema for it from an input reference shapeset and a schema table

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: Pointer ( char * ) to a NUL-terminated string giving the pathname (no extension) of the PAGC schema table (an xbase file) for the reference shapeset.

Arg3: Pointer ( char * ) to a NUL-terminated string giving the pathname (no extension) of the reference shapeset.

Arg4: Or'd - together flags for the schema (unsigned int). Flags may be set here or in the schema table.

Arg5: Start record number (int). If <= 0, start at first record of the shapeset. Otherwise number is record to start standardizing at. Must be a number less than the number of records in the file. Set to 0 if building the entire shapeset.

Arg6: End record number ( int ). If <=0, end on last record. Otherwise number is record to stop standardizing at. Set to 0 if building the entire shapeset.

Returns

0 error - see global log for error details
1 success

pagc_format_candidate

Prototype

PAGC_DLL_RET pagc_format_candidate( PAGC_HANDLE , int , int , char * , int , int , int )

Short Description

This function formats a candidate in street address data standard format.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context)

Arg4: Pointer (char *) to the buffer into which the formatted candidate data (max 4096 characters) is to be copied (as a NUL-terminated string).

Arg5: The interpolation house number (obtained from pagc_match_item) for SITE_INTERPOLATE queries. Because the candidate record is a block range, the formatter needs to substitute the client's actual house number.

Arg6: Format Selector. The Format Selector is an int which is one of the following three values:

0, for CSV (comma-separated values)
1, for JSON.
2, for XML.

Arg7: Strategy selector (int). One of :

- 0. SITE_MATCH - 1. SITE_INTERPOLATE - 2. INTERSECTION - 3. ADDRESS_RANGE_2 - 4. ADDRESS_RANGE_4

Arg8: Pointer to int ( int * ) in which either 1 (TRUE) or 0 (FALSE) will be copied, to indicate if address number parity is consistent with others in the address range. This can be ignored except for SITE_INTERPOLATE.

Arg9: Pointer to buffer (char *) in which the address's record identifier is to be copied. This can be ignored in INTERSECTION requests and where the schema is not flagged to copy this field.

Returns

0 error - see context log for error details
1 success

pagc_format_candidate_ols

Prototype

PAGC_DLL_RET pagc_format_candidate_ols( PAGC_HANDLE , int , int , char * , int , int , int * , char * )

Short Description

This function formats a candidate in open location service formatting.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context)

Arg4: Pointer (char *) to the buffer into which the formatted candidate data (max 4096 characters) is to be copied (as a NUL-terminated string).

Arg6: Strategy selector (int). One of :

- 0. SITE_MATCH - 1. SITE_INTERPOLATE - 2. INTERSECTION

Arg7: Pointer to int ( int * ) in which either 1 (TRUE) or 0 (FALSE) will be copied, to indicate if address number parity is consistent with others in the address range. This can be ignored except for SITE_INTERPOLATE.

Arg8: Pointer to the buffer ( char * ) in which the OLS country code is stored.

Returns

0 error - see context log for error details
1 success

pagc_get_address_candidate_raw

Prototype

PAGC_DLL_RET pagc_get_address_candidate_raw( PAGC_HANDLE , int , int , char * )

Short Description

This function returns, in the buffer pointed to by the third arg, an unformatted address candidate.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context)

Arg4: Pointer (char *) to the buffer into which the formatted candidate data (max 256 characters) is to be copied (as a NUL-terminated string): (candidate number): address data score record number

Returns

0 error - see context log for error details
1 success

pagc_next_block_up_down

Prototype

PAGC_DLL_RET pagc_next_block_up_down( PAGC_HANDLE , int , int , int )

Short Description

Used for interpolation geocoding. This function returns the next block up (or down) from a candidate addressrange. If found the block is moved into the candidate 0 position, where it may be edited using pagc_read_alpha_field and pagc_replace_alpha_field so that it can be geocoded. The schema must have been built with the ENABLE_PSEUDO flag (Otherwise it does not possess the index required for the search).

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context)

Arg4: Up-down flag. Up is 1, Down is 0. Up and down are in relation to the direction of the address range.

Returns

0 error - see context log for error details
1 success

pagc_read_alpha_field

Prototype

PAGC_DLL_RET pagc_read_alpha_field( PAGC_HANDLE , int , int , int , char * , int * )

Short Description

This function is called to ascertain the contents of the field of the unstandardized xbase record that serves as the source for the candidate. This function is called as part of the process of amending, on the fly, the candidate's data in order to make an ungeocodable candidate geocodable. In other words the client will get the unnormalized contents of the original shapeset record, for the field specified.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context)

Arg4: The field number (int). The first field's number is 0. This arg must not exceed the number of fields used to derive address data from the xbase record (obtained from Argument 6).

Arg5: Pointer (char *) to buffer in which the contents of the field shall be copied. The string has the format
(n) field name : field contents

Arg6: Pointer (int *) to an integer into which will be copied the total number of fields for the record.

Returns

0 error - see context log for error details
1 success

pagc_replace_alpha_field

Prototype

PAGC_DLL_RET pagc_replace_alpha_field( PAGC_HANDLE , int , int, int, char * )

Short Description

This function is called to replace the contents of a field of the unstandardized xbase record that serves as the source for the candidate. This function is called as part of the process of amending, on the fly, the candidate's data in order to make an ungeocodable candidate geocodable

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context)

Arg4: The field number (int). The first field's number is 0. This arg must not exceed the number of fields used to derive address data from the xbase record (obtained from pagc_read_alpha_field).

Arg5: Pointer ( char * ) to the NUL-terminated string that will replace the contents of the indicated field.

Returns

0 error - see context log for error details
1 success

pagc_cand_header_list

Prototype

PAGC_DLL_RET pagc_cand_header_list( PAGC_HANDLE , int , int , char * )

Short Description

This function returns the headers for a candidate in street address data standard format.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context)

Arg3: Strategy selector (int). One of :

- 0. SITE_MATCH - 1. SITE_INTERPOLATE - 2. INTERSECTION - 3. ADDRESS_RANGE_2 - 4. ADDRESS_RANGE_4

Arg4: Pointer ( char * ) to a buffer where the NUL-terminated string representing the CSV-style field headers is to be copied.

Returns

0 error - see context log for error details
1 success

pagc_get_normalized_score

Prototype

PAGC_DLL_RET pagc_get_normalized_score( PAGC_HANDLE , int , int , int , double * )

Short Description

This function obtains the normalized score of a candidate.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context)

Arg3: Candidate Number

The candidate number (int). This is the number of a candidate on the context's matched candidate list. The first candidate's candidate number is 0. This arg must not equal or exceed the number of candidates (obtained from pagc_numb_cands)

Arg4: Strategy selector (int). One of :

- 0. SITE_MATCH - 1. SITE_INTERPOLATE - 2. INTERSECTION - 3. ADDRESS_RANGE_2 - 4. ADDRESS_RANGE_4

Arg5: Pointer to double in which the candidate's normalized score is to be copied (double *). This will be a value between 0.0 and 1.0, with higher values indicating a better match.

Returns

0 error - see context log for error details
1 success

pagc_numb_cands

Prototype

PAGC_DLL_RET pagc_numb_cands( PAGC_HANDLE , int , int *)

Short Description

This function obtains the number of candidates collected for a matching.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context)

Arg3: Pointer (int *) into which the number of candidates will be copied.

Returns

0 error - see context log for error details
1 success

pagc_open_user_dbf

Prototype

PAGC_DLL_RET pagc_open_user_dbf( PAGC_HANDLE , int , char * , char * , char * , int * )

Short Description

This opens and prepares the user's address dbf for matching.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context)

Arg3: Pointer (char *) to the pathname of schema reference table.

Arg4: Pointer (char *) to the pathname of the user's attribute xbase file.

Arg5: Pointer (char *) to the pathname of an xbase table giving the read order of fields in the user's address xbase table. This pointer may be NULL -- in which case PAGC will attempt to determine the fields by probing.

Arg6: Pointer (int *) into which an integer denoting the number of rows in the user's attribute table will be copied.

Returns

0 error - see context log for error details
1 success

pagc_match_user_dbf_record

Prototype

PAGC_DLL_RET pagc_match_user_dbf_record( PAGC_HANDLE , int , int )

Short Description

This function performs the matching against the user's dbf record.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context)

Arg3: The row number in the user's xbase attribute table which is to be matched against. The first row number is 0 and the number must not equal or exceed the total number of rows (obtained in pagc_open_user_dbf).

. If producing a point shapeset these records will be read sequentially.

Returns

0 error - see context log for error details. If an error is encountered, an attempt is made to write a null record (instead of a point) into the user's shapefile.
1 - no perfect match, candidate selection is needed.
2 - perfect match. A geocoded record is written into the user's shapefile.

pagc_write_point_shape

Prototype

PAGC_DLL_RET pagc_write_point_shape( PAGC_HANDLE , int , int, PAGC_POINT * )

Short Description

This function writes the geocoded point to the user's shape file at the record number given in Arg3. Geocoded points are done in sequence. This function is used to create a shape record for a selected candidate (ie pagc_match_user_dbf_record has not done it automatically).

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context)

Arg3: The user's xbase record number (int). This same record number is the record number of the created point shape.

Arg4: Pointer to a point structure (PAGC_POINT *) in memory, consisting of a double for the X coordinate and a double for the Y coordinate. The geocoded point is copied into this structure.

Returns

0 if a point cannot be created. A null shape is output to the shapefile (instead of a point) at the record number corresponding to Arg3.
1 success - and a shape point is output to the shapefile.

pagc_select_candidate_interactive

Prototype

PAGC_DLL_RET pagc_select_candidate_interactive( PAGC_HANDLE , int , int )

Short Description

This allows the user to interactively select a candidate from the list collected using the terminal commandline.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context)

Arg3: The user's xbase record number (int). If producing an output shapefile these records should be given sequentially.

Returns

0 error - see context log for error details
1 success

pagc_fetch_context_error

Prototype

PAGC_DLL_RET pagc_fetch_context_error( PAGC_HANDLE , int , int *, char * )

Short Description

This function copies to the user's buffer the earliest unflushed error message for a context.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context)

Arg3: Integer Output Pointer to which a 1 or 0 is copied. 1 denotes that this error is a system error.

Arg4: Pointer (char *) to buffer in which the error message is to be copied.

Returns

0 error
1 success

pagc_register_context_error

Prototype

PAGC_DLL_RET pagc_register_context_error( PAGC_HANDLE , int , int , char * )

Short Description

This function explicitly registers an error for the matching context. It does not handle the error. The length of the error string should not be longer than 255 characters.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context)

Arg3: Boolean (int) 1 or 0 : 1 denotes that this error is a system error, 0 a client error.

Arg4: Pointer to the string (char *) to the NUL-terminated string (the error message).

Returns

0 error
1 success

pagc_print_beta_range_4

Prototype

PAGC_DLL_RET pagc_print_beta_range_4( PAGC_HANDLE , int , int , int )

Short Description

Prints a beta (standardized) record in street address data standard format.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The matching context index (int). (obtained from pagc_add_context).

Arg3: The beta record number (int) to display.

Arg4: Format Selector. The Format Selector is an int which is one of the following three values:

0, for CSV (comma-separated values)
1, for JSON.
2, for XML.

Returns

0 error - see context log for error details
1 success

pagc_dump_reference

Prototype

PAGC_DLL_RET pagc_dump_reference( PAGC_HANDLE , int )

Short Description

print to stdout the contents of the beta (standardized reference) file.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context) (Note: the beta file belongs to the schema bound to the context)

Returns

0 error - see context log for error details
1 success

pagc_dump_index

Prototype

PAGC_DLL_RET pagc_dump_index( PAGC_HANDLE , int , int )

Short Description

print to stdout the contents of a database index.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: The context index (int). (obtained from pagc_add_context) (The index belongs to the schema bound to the context)

Arg3: index number (int) of the index to print to stdout. This integer will correspond to the last digit in the file extension. Note : not all indices are present in all schemas.

FULL_FEATURE 0
STREET_POSTAL_EXACT 1
STREET_POSTAL_SOUNDEX 2
STREET_POSTAL_APPROX 3
POINT_INDEX_TYPE 4
SHAPE_INDEX_TYPE 5
CONCAT_INDEX 6
CONCAT_SOUNDEX 7
CONCAT_APPROX 8

Returns

0 error - see context log for error details
1 success

pagc_start_stand

Prototype

PAGC_DLL_RET pagc_start_stand( PAGC_HANDLE )

Short Description

Start a standardizer instance outside of a context.

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Returns

0 error - see global log for error details
1 success

pagc_standardize_address

Prototype

PAGC_DLL_RET pagc_standardize_address( PAGC_HANDLE , int , int , char * , char * )

Short Description

Standardization test

Arguments

Arg1: PAGC_HANDLE (obtained from pagc_init)

Arg2: Format Selector. The Format Selector is an int which is one of the following three values:

0, for CSV (comma-separated values)
1, for JSON.
2, for XML.

Arg3: Boolean (int) 1 or 0 : add statistics to output

Arg4: Pointer (char *) to micro portion of address (address, street, occupancy) to be standardized.

Arg5: Pointer (char *) to macro portion of address (city, nation, postal code) to be standardized.

Returns

0 error - see global log for error details
1 success. Output goes to stdout