Scoring a Set of Records (lkt_scorerecords)

This command is similar to the lkt_dbsearch command except that it applies the query to a given set of records instead of to an in-memory table of records.

dvkerr_t lkt_scorerecords( lpar_t host, lpar_t rec_def, 
                           lpar_t querypar, lpar_t srchpars, 
                           lpar_t rec_list, lpar_t *stats, 
                           lpar_t *matches, lpar_t *minfo );

This command runs a query against a set of records, returning the query results for each record in the given set. Unlike the lkt_dbsearch command it does not find and return the best matches. Instead it scores every record given returning the query match information for each record. The key differences between lkt_scorerecords and lkt_dbsearch are:

•

Instead of passing the name of a table or set of tables to be searched the definition of the record layout and a set of records is passed in.

•

Joined searches are not supported by the lkt_scorerecords command. As no tables are involved the concept of joined tables does not apply.

•

All records passed in are always scored and returned. lkt_scorerecords is explicitly a request to calculate and return the query score for a set of records. It is NOT a request to find records. Therefore all records are always returned, even if the record has been assigned a "reject" score.

•

Filtering predicates do not apply. There is no way to specify a filtering predicate.

•

prefilters are never used, so all prefilter options are ignored.

•

Cutoffs do not apply. So all cutoff options are ignored.

•

A query that has no query data is not considered an error when used with the lkt_scorerecords command. The lkt_dbsearch command must have some query data to provide a basis for selecting a set records. The lkt_scorerecords command does not select records, so this restriction does not apply.

Generally, the lkt_scorerecords command ignores options that do not apply rather than reject them. This helps the exact same query and search parameters to be used with lkt_dbsearch and lkt_scorerecords.

Input

host (optional)

is used to identify the server.

For more information, see Communicating with TIBCO Patterns Servers

rec_def (required)

is used to define the field names and field types of the records to be searched. This parameter accepts the same lpar structure as the dbpars parameter of the lkt_dbload command except the LPAR_STRARR_FIELDNAMES lpar is required in all cases. All values except LPAR_STRARR_FIELDNAMES, LPAR_STRARR_CHARMAPS and LPAR_INTARR_FIELDTYPES are ignored. As with the lkt_dbload command the character maps default to DVK_CMAP_STDNAME and the field types default to LKT_FLD_TYPE_SRCHTEXT.

query (required)

This is the query to be applied. It is identical to the query parameter of the lkt_dbsearch command. Details on query construction are covered in Query Construction.

srchpars (optional)

This is the same as the srchpars parameter to the lkt_dbsearch command. The following parameter values have no effect: LPAR_INT_STARTMATCH, LPAR_LST_CUTOFF (and all associated entries), LPAR_BOOL_DOMAXWORK, LPAR_BOOL_GIPSEARCH, LPAR_BOOL_SORTSEARCH, LPAR_BOOL_PSISEARCH, LPAR_BLKARR_SORTLOOKUPFIELDS, LPAR_BLKARR_PSILOOKUPFIELDS, LPAR_INT_FETCH_SIZE, LPAR_INT_PC_SIZE, LPAR_INT_PSI_DENSITY.

rec_list (required)

This is a generic list of records to be scored. All records must have the same number of fields as defined by LPAR_STRARR_FIELDNAMES in the rec_def parameter.

Output

stats (required)

is identical to the stats output parameter of the lkt_dbsearch command. The filter times and filter sizes output lists only the last, filter stage 2, filter step as the other filter steps are not run for the lkt_scorerecords command.

matches (required)

is identical to the matches output parameter of the lkt_dbsearch command.

minfo (required)

is identical to the minfo output parameter of the lkt_dbsearch command, except that it is required for the lkt_scorerecords command. The entire purpose of this command is to return this scoring information, so it makes no sense to run the command without this output parameter.

Error codes and items returned by lkt_scorerecords

ARRAYLEN	array lpar with wrong number of values
CHARCONV	Record containing invalid UTF-8 character
DBPARAM	Record definition item that is not valid
EXPECTDBDESC
EXPECTLIST	item that should have been a list lpar
EXPECTQUERY	item that should have been a search query
FEATURESET	item specifying an unsupported feature
INTERNAL	item being processed at the time of the error, or a detailed description of the error
LOOKUP	(none) error in scoring operation
MODEL_UNSUPPORTED	(none) issued when the Learn Model version is not supported
NOCHARMAP	specified character map doesn't exist
NOQUERY	(none) A query parameter was missing
NORLINKMODEL	Learn Model name - the model is not loaded, query parameter - no Learn Model name is specified
NOSYSINIT	(none) DevKit is not initialized
NOWGTFLD	query expression missing the LPAR_STR_WGTFLD_NAME
NSFIELD	field selection lpar with name of non-existant field
NUMFEATURESMISMATCH	Learn expression lpar with wrong number of entries for the specified model.
NUMFIELDS	Record containing incorrect number of fields
PARAMCONFLICT	lpar that contains a parameter conflicting with an earlier parameter.
PARAMMISSING	the list missing a required item
PARAMVAL	lpar that contains an illegal value
PREDSTRING	LPAR_STR_ERRORDETAILS describing predicate syntax error
QUERYEXPR	lpar that contains the invalid query specification
SRCHPARAM	item that should have been a search parameter
THESNOTFOUND	name of thesaurus not found
UNKFIELD	A field name lpar containing a field not listed in the rec_def LPAR_STRARR_FIELDNAMES list.