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 (=, >, <, >=, <=).

Note:

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

formInstance

• 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

Flag to specify how partial dates should be handled.

• null. Ignore partial dates when doing comparisons.
• value. Replace 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

Item variables to search.

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.

compareOperator

Operator to use for the comparison: =, >, <, >=, <=.

value

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

Returns -1 if no matches are found or the index number (>0) of the repeating section instance if at least one matching instance is found. If multiple instances are found, only the first index is returned.

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.

Example 3-69 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-70 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-71 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-72 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;