Help >

ddlFind() - isolate records in a collection

Version 7.11

ddlFind() - isolate records in a collection

Prototype:

   void ddlFind(
      CONTROL *ctl,
      char *OptnStr,
      char *ArgList);

Permitted values in OptnStr:

   /Cn - return first n values only
   /F  - enable field-to-field query
   /K  - case sensitive find (non-keyed only)
   /N  - force non-keyed query

Form of ArgList:
      <cx> [<TableName>] [WHERE] <expression>

Where:

<cx> is the name of the collection <TableName> is the name of the target table. If <TableName> is omitted, the global collection is used. <query-expression> has the form:           <condition1> {AND OR XOR EXCEPT} <condition2> ... <conditionN>           <conditionN> can be prefixed with the NOT operator in either a unary or binary context; <conditionN> can be any one of the following:          cxN - i.e., the name of a collection;          fieldN OP valueN;          fieldN OP %variableN;          %variableN OP valueN;          fieldN OP fieldN' (if /N option is present);          #SavedCollection - i.e., the name of a saved collection          cxN TableNameN - refer to Note 6) below

Description:

The ddlFind() API function isolates the subset of interest into a specified collection. The <query-expression> determines the subset of interest. If the <TableName> argument is specified, the function operates only on the specified table, and the specified part of the collection. If the <TableName> argument is not specified, the function operates only on all tables, and the global collection. The query value for a DATE field can be in either the default external format 'mm/dd/yyyy', 'mm-dd-yyyy' or 'mm.dd.yyyy'; or it can be in the system DATE format 'yyyymmdd'. That is, the only valid forms for a date literal in ddlFind() are:      'yyyymmdd'      'mm/dd/yyyy' or 'mm/dd/yy'      'mm-dd-yyyy' or 'mm-dd-yy'      'mm.dd.yyyy' or 'mm.dd.yy' The query value for a DATETIME field can be in either the default external format 'mm/dd/yyyy hh:nn:ss.ttt', 'mm-dd-yyyy hh:nn:ss.ttt' or 'mm.dd.yyyy hh:nn:ss.ttt'; or it can be in the system DATETIME format 'yyyymmddhhnnssttt'. The query value for a DateTimeEx or TIME field must be in the default format as specified in the Default Templates section. In all cases, the default template can be modified with the ddlMode() DATEFORM function. The query value for a BYTE field is expressed as a hex character string in the form 0xnnnnnnn ... Refer to ddlFind() - additional details and examples for additional information.

Notes:

1) In a context where there are no nulls, the expressions:       <Field> NOT EQ <Value>       NOT <Field> EQ <Value> are identical. However, in a context where there are nulls, the two expressions are not identical; as the first form explicity excludes nulls after the complement; whereas the second does not. 2) Use of the boolean NOT is limited, as of TB API release 8.0.142, to these forms:        FIND A = NOT <condition>        FIND A = <condition1> AND NOT <condition2>        FIND A = NOT <condition1> AND <condition2>        FIND A = NOT <condition1> AND NOT <condition2>        FIND A = <condition1> OR NOT <condition2>        FIND A = NOT <condition1> OR <condition2> Use of the boolean NOT is not allowed, as of TB API release 8.0.142, in these forms:        FIND A = NOT <condition1> OR NOT <condition2> 3) The form:        FIND <cx> <TableName> WHERE <cxN> <TableNameN> is intended to provide a method for copying a collection to/from/between a table and its aliases.

Values returned in Control Structure:

Control.Ans1 Total number of records selected (32 bit) Control.Ans2 If the /Cn option was used, this is the number of records selected before the /Cnnn limit was applied; else, it is a duplicate of Control.Ans1

Back to top