MOD_CHECK_TASK task descriptor

The MOD_CHECK_TASK task does one or more modulus checks on incoming table data to determine whether it is valid. For example, it can be used as a part of account number validation.

The task returns either SUCCESS or FAILURE in a results variable when it finishes its table lookup and modulus checks. It returns SUCCESS when the record was located during the table lookup and the modulus check passed. It returns FAILURE when the record was not located or the modulus check did not pass. For a failure, the ibmErrorResults field might also have a reason why the check did not pass.

The following table shows the incoming data fields for this task.

Table 1. MOD_CHECK_TASK incoming data fields
Field name	Required or optional	Description	Examples
intSourceData	Required	The value to run the modulus check against. This field is not part of the table data.	123-454 5483-88 88756413
intInstitutionNum	Required	The institution number of the account to be validated. For Canadian accounts, this number is a 3-digit number.	002 039 815
intModCheckId	Required	Key value to determine which modulus checks to use.	1
ibmOrderBy	Required	Multiple modulus checks can be done for one modulus check ID. The order of the modulus checks is determined by the values that are specified in this field. This field is in the table data only.	1 2 3
ibmIntRequired	Optional	When this field is set to Y, the modulus check is active. When it is set to N, the modulus check is not active and passes automatically.	Y N
ibmSetModFormat	Required	The format of the incoming data. This field is used to parse which characters are used for the modulus check, which character (if any) is the check digit, and which characters can be ignored. See Table 2 for a description of the valid format characters.	999-99C SS9-99 9X99 99SS99
ibmSetModAddToCheckDigit	Required	A value to add to the check digit (if applicable) before all the values are summed. For example, adding 1 to the value 9 becomes 0.	0 1
ibmSetModWeights	Required	A list of comma-separated modulus weight values that are used to multiply the extracted digits by when the account number is summed. The number of values in this list must match the number of digits that are extracted from the account. Ranges are also supported and are in the format `low`-`high`. Ranges are applied to the digits from right to left.	1, 2, 1, 2, 1, 2 1, 5, 8, 3, 9, 1, 0, 8 2-7
ibmSetModOption	Required	Indicates how all of the digits are summed. Valid values for this field are shown in the following list. Products Multiply each extracted digit by its modulus weight. Sum the resulting products. Digits Multiply each extracted digit by its modulus weight. Sum all of the digits that are in the resulting products. For example, if the product of the multiplication is 15, 1 and 5 are added to the sum. Ones Multiply each extracted digit by its modulus weight. Sum all of the digits that are in the ones, or units, position of the resulting products. The modulus weights to use for the extracted digits are set in the ibmSetModWeights field.	Products Digits Ones
ibmSetModulus	Required	The value to use for the modulus value.	10 11
ibmSetCheckDigitAlgorithm	Required	The algorithm to use to validate against the check digit. The digits must be extracted and summed before the check digit can be used for validation. The algorithms are shown in the following list. Blank There is no check digit. The remainder from dividing the sum by the modulus must be 0. Remainder The remainder from dividing the sum by the modulus must equal the check digit. Remainder_Minus The remainder from dividing the sum by the modulus is then subtracted from the modulus. If the result of the subtraction is 10 or greater, the result becomes 0. This result value must equal the check digit. Roundup_10_Minus_Sum The sum is subtracted from the sum that is rounded up to the tens position. The resulting value must equal the check digit. Greater_Than_9_Adjust The remainder from dividing the sum by the modulus is then subtracted from the modulus. If the result of the subtraction is greater than nine, subtract three from the result. This final result value must equal the check digit.	Blank Remainder Remainder_Minus Roundup_10_Minus_Sum Greater_Than_9_Adjust

The valid ibmSetModFormat characters are shown in the following table.

Table 2. Valid ibmSetModFormat characters
Character	Used in modulus check	Character set	Multiplied with weights	Description
9	Yes	[0-9]	Yes	The character is used for the modulus check. The value of the character must be 0 - 9.
S	Yes	[0-9], space, empty	Yes	The character is used for the modulus check. The value can be 0 - 9, a space, or an empty cell. Spaces and empty cells are converted to a 0 for the modulus check.
C	Yes, when ibmSetCheckDigitAlgorithm is not blank. Otherwise, no.	[0-9]	No	The character to use as the check digit. The check digit must be 0 - 9.
-	No	[-]	No	Indicates the potential position of a dash. If no dash is at this position, the check continues with the next character in the pattern.
X	No	Any	No	The character is skipped, no matter what its value is.

Task descriptor

The task descriptor for this task is shown in the following example. The task contains a data descriptor, which defines the layout of the corresponding .tbl data file. You can also configure assignment statements to run before and after the table lookup is done.

<taskDescriptor name="ModCheck" type="MOD_CHECK_TASK">
   <assignment field="intSourceData"             type="string"  value="123-454"/>
   <assignment field="intInstitutionNum"         type="string"  value="002"/>
   <assignment field="intModCheckId"             type="string"  value="1"/>
   <assignment field="ibmIntRequired"            type="string"  value="Y"/>
   <assignment field="ibmSetModFormat"           type="string"  value="999-99C"/>
   <assignment field="ibmSetModAddToCheckDigit"  type="string"  value="0"/>
   <assignment field="ibmSetModWeights"          type="string"  value="2, 1, 2, 1, 3"/>
   <assignment field="ibmSetModOption"           type="string"  value="Products"/>
   <assignment field="ibmSetModulus"             type="decimal" value="11"/>
   <assignment field="ibmSetCheckDigitAlgorithm" type="string"  value="Remainder_Minus"/>
   <dataName>ModCheckTable</dataName>
   <useExitClass>modcheckuserexit</userExitClass>
</taskDescriptor>

Modulus check workflow example

In this example XML, the value to run the modulus check against is in the intSourceData field. The value is 123-454. The MOD_CHECK_TASK task first tries to find a record that matches the passed in intInstitutionNum and has an intModCheckId value of 1.

If a record is found, the value in intSourceData is checked against the ibmSetModFormat value. Then, the format is used to extract the digits and the optional check digit from the source. For this example, the extracted digits and check digit are shown as follows.

ibmSetModFormat      : 999-99C
intSourceData        : 123-454
Extracted digits     : 12345
Extract check digit  : 4

Do not use this check as the only validation that is done against an account number because it validates the account number only enough to extract the required digits.

After the digits are extracted, the task weights them and sums them as specified in the example XML. First, the digits are multiplied by their corresponding modulus weight value from the ibmSetModWeights field. Then, the results are summed according to the method specified in the ibmSetModOption value. The following example shows the results for all of the methods that can be used to sum the digits.

Extracted digits            : 1   2   3   4    5
ibmSetModWeights            : 2   1   2   1    3
Products                    : 2   2   6   4   15

ibmSetModOption (Products)  : 2 + 2 + 6 + 4 + 15     = 29
ibmSetModOption (Digits)    : 2 + 2 + 6 + 4 +  1 + 5 = 20
ibmSetModOption (Ones)      : 2 + 2 + 6 + 4 +  5     = 19

After the digits are summed, the set modulus value is applied to the result of the sum method that was specified the ibmSetModOption.

ibmSetModulus               : 11
ibmSetModOption (Products)  : 29
Modulus result              : 29 % 11 = 7

Finally, the ibmSetCheckDigitAlgorithm field is checked. If a check digit algorithm is not provided, the modulus check passes if the modulus result is 0. Otherwise, the check digit algorithm is applied. The following example and table shows how the check digit is used to determine whether the modulus check passes or fails.

Modulus result      : 29 % 11 = 7
ibmSetModulus       : 11
Check digit         : 4
Sum to the next 10  : 30

Table 3. Modulus check example for the check digit algorithms
Value of ibmSetCheckDigitAlgorithm	Calculation	Result of the modulus check
Blank	`7 != 0`	Fail
Remainder	`7 != 4`	Fail
Remainder_Minus	`11 – 7 = 4` `4 = 4`	Pass
Roundup_10_Minus_Sum	`30 - 29 = 1` `1 != 4`	Fail
Greater_Than_9_Adjust	`11 – 7 = 4` `4 < 9`, so no adjustment is done `4 = 4`	Pass

In this example, the sample account number 123-454 passes the modulus check when the ibmSetCheckDigitAlorithm is set to the following values.

Remainder_Minus
Greater_Than_9_Adjust

After a modulus check passes, the task searches for the next modulus check to do. This search is done by incrementing the ibmOrderBy field by 1 and then doing another table lookup. If no record is found, the MOD_CHECK_TASK task returns with SUCCESS because there are no more checks. If another record is found, that record must also pass the modulus check or this task returns FAILURE.