The rule command object can be used to establish validation constraints that facilitate the verification of message structure and content. Rule objects require a kind descriptor consisting of alphanumeric characters and must conclude with an ends closure directive.
In the example shown below, a local rule named "myrule" is defined. This rule contains a single item named "total" with the expected data type of decimal. The once occurance constraint decorator means that there must be only one occurance of the item "total" within the immediate body of the message.
rule myrule item total decimal once ends
To apply the rule against an info object, the uses header directive is specified. In the example shown below, the info object would successfully pass validation because the value given for “total” is decimal, and the item appears only once.
info mymessage uses rule myrule item total as 12.62 ends
Local rules persist within the memory of the active instance of the CXIO Engine. To remove the rule from memory, use the following command:
drop rule myrule
Rules can be fetched and applied from the internet using http or https protocols using the following syntax, as shown below.
info mymessage uses rule https://rules.centrifax.com/example/myrule.cxio item total as 12.62 ends
Validating Lines and Items
Individual message lines and items can be validated using rules. In the example shown below, a line named “orderline” is defined with a rule called “myorderrule”. The line has a many decorator, meaning that there should be at least one occurrence of “orderline”.
Within the order line, items “sku”, “qty” and “price” must appear only once with the appropriate data type. The “note” does not need to be provided, but if specified should be of type string.
rule myorderrule line orderline many item sku string once item qty int once item price decimal once item comment string none ends ends info myorder uses rule myorderrule line orderline sku: "000001" qty: 12 price: 34.52 ends line orderline sku: "000002" qty: 12 price: 7.15 comment: "Only current season." ends ends drop rule myorderrule
Applying Multiple Rules
It is possible to apply more than one rule to the same message, as shown in the example below. When applying multiple rules, the message will only pass validation if all rules are successfully tested.
/* Define the first rule */ rule my_rule1 item total decimal once ends /* Define the second rule */ rule my_rule2 item currency char(3) once ends /* The message */ info my_message uses rule my_rule1 uses rule my_rule2 total: 12.62 currency: “GBP” ends /* Drop the rules */ drop rule my_rule1 drop rule my_rule2
There are three types of occurrence constraints which are none, once and many.
|None||The item does not need to be specified, but if provided it must agree with any specified data type.
Where no occurrence constraint decorator is given within a rule, this is the default.
|Once||The item can only be occur once.|
|Many||The item must occur at least once. There is no upper limit on number of occurances.|
|Many (max)||The item must occur at least once, however cannot occur more than the specified maximum times.
Items must agree with any specified data type.
|Many (min, max)||The item must occur at least the minimum number times specified, and cannot occur more than the maximum times specified.|
In the example below, the rule "my_occurance_rule", defines an item named "test" with a min and max occurance count of 2. The below will pass validation because there are exactly two occurances of test and no explicit data type was specified within the rule.
rule my_occurance_rule item test many(2,2) ends info my_occurance_info uses rule my_occurance_rule test: "hello" test: 123 ends
Enumerations define sets of available values and can be used within rules to restrict the value given.
In the example below, the rule "my_enum_rule" has an enum named "my_vals" containing three possible values: "R1", "X3", "P7". An item named "test" with an occurance constraint of once, references the "my_vals" enum with the in decorator.
The case directive with strict means that both item names and values are sensitive.
rule my_enum_rule case strict enum my_vals "R1", "X3", "P7" ends item test once in my_vals ends info my_enum_info uses rule my_enum_rule test: "X3" ends