find2SFormInstance( )

Find an instance of the repeating section in a two-section form that contains a value which matches the search value using a supplied operator.

This function is similar to findMatching2SForm( ). However, it allows the rule designer to specify matching operands (=, >, <, >=, <=).

This is an aggregation function. The rule is run for each instance in the case where the target is on the repeating section in a two-section form.

Syntax

find2SFormInstance(formInstance, DateMask, 'variable1', 'compareOperator1', value1, 'variable2', ...)

Parameters

Note:

It is allowed to reuse variables passed into this function elsewhere in the rule expression, however you must add the variable as a parameter using single quotes.
Parameter Required/Optional Description
formInstance Optional Indicates the form instance in which the search is to be performed.
  • If formInstance is null and variable is in flat section, the flat portion across all instances is searched.
  • If formInstance is null and variable is in a table row, the search is across all table rows in all instances.
  • If formInstance value is provided, the search is across the table rows of the specified instance.
DateMask Optional Flag to specify how partial dates should be handled:
  • If null, ignores partial dates when doing comparisons.
  • If a value is provided (in string format), replaces the UNK component in the partial date with the specified value.

    For example: entering '10-Apr' substitutes with '10' every UNK value of Day (DD) component and with 'Apr' every UNK value of Month (MMM) component.

Note: Use mask only for date elements and do not use it for time elements. Any missing value in the time part is considered as 00.
variable(s) Required Item variable to search, passed in using single quotes.
compareOperator Required
Operator to use for the comparison of the provided variable and value:
  • =
  • >
  • <
  • >=
  • <=
value Required Value to compare variable with as a string.
  • Date values can be provided as a Javascript Date variable or as a string in the following formats:
    • 'Date(dd-mmm-yyyy)'
    • 'Date(dd-mmm-yyyy hh:mm:ss)'
    • 'dd-mmm-yyyy'
    • 'dd-mmm-yyyy hh:mm:ss'
  • Time values can be provided as 'Time(hh:mm:ss)'

Return value

Number (>0) that represents the index of the instance where the matching value was found.
  • If multiple instances are found, only the first index is returned.
  • Returns -1 if no matches are found.

Usage tips

  • Values in the custom function should be JavaScript variables or direct values. Do not use operand variables directly in the custom function expression.
  • If other operands/variables are to be used for a value, it has to be assigned first to the JavaScript variable and then used in the function expression.
  • Use 'DD-MON' format as DateMask to substitute unknown (UNK) values in the partial date values. For example, if the mask is '01-MAR':
    Partial date value Masked date Notes
    'UNK-FEB-2020' '01-FEB-2020' Made effective for calculation using the day part of the mask.
    'UNK-UNK-2020' '01-MAR-2020' Made effective for calculation using both, the day and month parts of the mask.

Examples

Example 3-71 Raise a query if there is an instance of pulse greater than a given value

// Raise a query if there is an instance of pulse > 100
return (find2SFormInstance(null, null, 'pulseVal','>', 100) > 0)?false:true;        //query is raised when false is returned

Example 3-72 Raise a query if there is an instance of a date variable on or after a given date value

// Raise a query if there's an instance where onDate is >= 10-Jun-2010 
//(onDate is partial UNK-UNK-YYYY) 
return (Find2SFormInstance(null, '10-Jun', 'onDate', '>=', '10-Jun-2010') > 0)?false:true;


//Example using operand variable values
//Raise a query if there's an instance where onDate is on or after the enddt
dtval=enddt;
return (Find2SFormInstance(null, '10-Jun', 'onDate', '>=', dtval) > 0)?false:true;

Example 3-73 Raise a query if there is an instance of a datetime variable on or after a given datetime value

return (find2SFormInstance(2, '10-Jun', onDateTime , '>=', '10-Jun-2010 11:12:15') > 0)?false:true;
//or
return (find2SFormInstance(2, '10-Jun', 'onDateTime' , '>=', 'Date(10-Jun-2010 11:12:15)') > 0)?false:true;

Example 3-74 Raise a query if there is an instance of a Time variable on or after a given time value

return (find2SFormInstance(2, null, 'onTime' ,'>=', 'Time(11:12:15)') > 0)?false:true;

Parent topic: Two-section form functions