findMatching2SForm( )

Find a repeating section instance of a two-section form, identified by the row ID, that matches the item value provided as a search key. This function supports partial dates.

  • Drop downs, radio buttons, and checkbox values are not supported as a function parameter or as a target.
  • If a variable is designed to hold a partial date then provide the value for that parameter in the same partial date format. You can use partial dates in the following formats:
    • <dd-mmm-yyyy hh:mm>
    • <dd-mmm-yyyy hh>
    • <dd-mmm-yyyy>
    • <mmm-yyyy>
    • <yyyy>

    Note:

    The presence of any partial date among instances will make other full dates to be taken in the same format for comparison. For example, if there is a partial date instance 'UNK-JAN-2022', only the month and year values in other dates will be taken for the comparison, even if they are full dates. Similarly, if there is a partial date instance 'UNK-UNK-2022', only the year value will be used for comparison in all dates.

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

Syntax

findMatching2SForm(formInstance, 'variable1', value1, 'variable2', value2, ...)

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 null, the search considers an array of existing instances of two-section forms. Ideally this should be used with variables inside the flat section of the form.
  • If a value is provided, the search considers an array of existing table rows on the specified instance of the two-section form.
variable(s) Required Item variable to check, passed in using single quotes.
value(s) Required Value for the given variable to search.
These valuesmust be hard-coded and cannot be rule variables:
  • Dates must be provided inside the string 'Date(dd-mmm-yyyy hh:mm:ss)'.
  • You can use partial dates in the following formats:
    • <dd-mmm-yyyy hh:mm>
    • <dd-mmm-yyyy hh>
    • <dd-mmm-yyyy>
    • <mmm-yyyy>
    • <yyyy>
  • Times must be provided inside the string 'Time(hh:mm:ss)'.
  • You can use partial times in the following formats:
    • <hh:mm>
    • <hh>

Return value

Number (>0) that represents the index of the instance where the matching value was found.
  • When searching across all instances for the two-section form (when formInstance = null), the function returns the form instance number of the match.
  • When searching a specific instance (for example, formInstance = 1), the function returns the table row instance number of the match.
  • If multiple instances are found, only the first index is returned.
  • Returns -1 if no matches are found.

Note:

In dates, UNK values are considered to match any other value. For example: 'Date(01-Feb-2022)' and 'Date(20-Feb-2022)' are both considered as a match of an entry with UNK-Feb-2022 date value.

Examples

Example 3-69 Raise a query if any instances exist where symptom = "headache" and pulse rate = "100"


// Given 5 two-sections form instances with items "itmSymptom" and "itmPulse" on flat part
// Fires query if any of the 5 instances contain both itmSymptom = "headache" AND itmPulse = 100.
if (findMatching2SForm(null, 'itmSymptom', "headache", 'itmPulse', 100) > 0) {
  return false;
} else {
  return true;
}
 
// Search table rows inside the 4th instance of the 2-section form
// Fires query if any rows inside the 4th form instance contain both itmSymptom = "headache" AND itmPulse = 100.
if (findMatching2SForm(4, itmSymptom, "headache", itmPulse, 100) > 0) {
  return false;
} else {
  return true;
}

Parent topic: Two-section form functions