piba_search

This function searches the batch database for matching batches.

Wildcard searches are performed on batchid, unit, and product if they are specified.

The strings must be set to zero length if they are not to be used in the wildcard search, i.e., a null character in array position 0.

Searchflag should be set to 0 for the initial search and set to non-zero for subsequent matching batches. -1 is returned when no more matching batches are available.

The timeout parameter is supplied to prevent excessive blocking in searches.

Searches are carried out in multiple calls. The initial search call with searchflag set to 0 establishes a search context using the provided batchid, unit and product arguments and returns the first matching batch.

In successive calls the search flag should be set to 1 to retrieve other matching batches. The batchid, unit and product are ignored unless the searchflag is 0 (i.e. an initial search)

Valid wildcard characters are * to match 1 or more characters and ? to match single characters.

C format

int32 piba_search (

char PIPTR * batchid,

int32 len0,

char PIPTR * unit,

int32 len1,

char PIPTR * product,

int32 len2,

int32 PIPTR * startime,

int32 PIPTR * endtime,

int32 searchflag,

int32 timeout );

Returns

>1

System error

No records found

Success

-1

Finished; no more found

-2

No valid search made yet but searchflag is non-zero

-3

Search flag is non-zero but a previous search has not been made on the current server.

-78

Call timed out

-285

Input string buffer too large 

-411

String truncated

-991,-994

API access to batch not supported by the version of PI on the server

-1002

No batch subsystem present on server.

Arguments

batchid (passed, returned)

Batchid search mask, passed; the matching Batchid, returned

len0 (passed)

Size of the passed batchid buffer. This should be at least 33 bytes to avoid truncation, but less than 256 (PI 3.2) or 80 (PI3.1 and earlier).

unit (passed, returned)

Unit search mask, passed, matching Unit, returned

len1 (passed)

Size of the passed unit buffer. This should be at least 13 bytes to avoid truncation, but less than 256 (PI 3.2) or 80 (PI3.1 and earlier).

product (passed, returned)

Product search mask, passed; matching Product, returned

len2 (passed)

Size of the passed product buffer. This should be at least 13 bytes to avoid truncation, but less than 256 (PI 3.2) or 80 (PI3.1 and earlier).

starttime (passed, returned)

Start time of search, passed; matching Batch start time, returned. Setting this value to zero and endtime to zero starts the search at the most current batch moving backward through time. If starttime < endtime the direction of search is forward through time. If startime > endtime the direction of search is backward through time

endtime (passed, returned)

End time of search, passed; matching Batch end time, returned.

searchflag (passed)

Batch search flag. For initial searches, searchflag must be set to 0; this establishes the search context and returns the first matching batch. To retrieve subsequent matching batches searchflag must be set to non-zero.

timeout (passed)

The time, in seconds, to search the batch database for matching before giving up the search. A timeout of zero will cause this routine to search until a match is found or the end of the batch database is reached.

Usage Notes

When piba_search is called with a non-zero searchflag and the current Server does not match the Server on which the search was initiated, it returns a -3 error. piba_search should always be called first with a searchflag of 0 after switching to a different Server. Note that if you call piba_search on one Server, switch to a different Server and switch back without an intervening call to piba_search, you can pass a non-zero search flag and continue your search as the last Server where a search was initiated matches the current Server.

When a batch is in progress the end time is returned as 0.

Input string buffers are limited to 79 characters for PI3.1 and earlier and 255 characters for PI3.2 and later versions.

For PI3 Servers, batches are indexed on unit then on time. If no unit is provided for this call, the search could be slow.

Example

char batchid[81] = "";

char unit[81] = "reactor1"; 

char product[81] = ""; 

int32 starttime = 0; 

int32 endtime = 0; 

int32 result; 

int32 timeout = 20; 

result = piba_search ( batchid, sizeof(batchid),unit, 

  sizeof(unit), product, sizeof(product),

&starttime,  &endtime, 0, timeout ); 

/* Find the most recent 100 batches on REACTOR1 */  

while ( (result == 0) && (count++ < 100) )  

{  

result = piba_search ( batchid, sizeof(batchid),  

 unit, sizeof(unit), product,sizeof(product), 

 &starttime, &endtime, 1, timeout ); 

 

Enabling Operational Intelligence