dt_mer_progob

Daylight v4.9
Release Date: 1 February 2008

Name

dt_mer_progob_compare - invoke a program object comparison

Generic Prototype

dt_mer_progob_compare(dt_Handle, dt_Handle, dt_Handle, dt_Integer, dt_Handle, dt_Handle, dt_Integer *) => dt_Integer

C Prototype

#include "dt_merlin.h"

dt_Integer dt_mer_progob_compare( dt_Handle hitlist, dt_Handle target_column, dt_Handle result_column, dt_Integer iprogob, dt_Handle pattern_binary, dt_Handle parameters, dt_Integer *status)

FORTRAN Prototype

include 'dt_f_merlin.inc'

integer*4 dt_f_mer_progob_compare(hitlist, binary, target_column, result_column, iprogob, sos, status)

integer*4 hitlist
integer*4 target_column
integer*4 result_column
integer*4 iprogob,
integer*4 pattern_binary
integer*4 parameters
integer*4 status

Description

This function uses a program object (see dt_mer_progob_compute(3)) to compare a binary datafield to the contents of a column of binary data, and stores the results of the comparisons in a column of numeric data. The parameter "pattern_binary" is ascii-encoded binary data; see dt_binary2ascii(3).

The parameter "parameters" is a sequence or stream object. Each object in the sequence or stream must respond to dt_stringvalue(); if it does not (i.e. dt_stringvalue(3) returns the 'invalid string'), an empty string is used in its place. The strings in "parameters" are sent to the program object as optional parameters to control the program object's computations; their interpretation is entirely up to the program object. This function has the side effect of resetting "parameters" (see dt_reset(3)).

(For details on how the program object receives the data send by this, function, see the example program "merlinbintalk.c" in the directory "$DY_ROOT/contrib/src/tutorial/C/progob".)

At the start of each search, the values in "results_column" are cleared. This means that even if the search is aborted before completion, the data in the column are modified.

Return Value

The status of the search task is returned in 'status' (see dt_continue(3) for descriptions). If the hitlist is short enough that time-slicing is not required, the value of 'status' will be DX_STATUS_DONE. Otherwise, the status will be DX_STATUS_IN_PROGRESS and dt_continue(3) will be required to finish the task.