check script instruction

`check script` instruction
Prev	Error handling	Next

`check script` instruction

Description

The check script instruction is used to check (ensure) that a specified condition is fulfilled at runtime.

If the checked condition is fulfilled then the script execution continues normally. If it is not fulfilled, the script execution stops immediately, and an error is raised.

The check script instruction is used whenever the programmer wants to verify (or assert) an assumption at a specific location in a script. For example, after executing a complex algorithm, the programmer wants to verify that a given variable will never be void at runtime.

The check script instruction can also make source code more understandable, because the programmer's assumptions are documented.

Note

Although the check instruction and the check script instruction both check conditions, their usage is different. While the check instruction is only used to check attributes, as well as command input and output conditions, the check script instruction is used to verify any assumption at any location in any script. Therefore the check script instruction can be used in any script, while the check instruction can only be used in check scripts.

	Note
	The `check script` instruction in Obix is similar to the `assert` statement in Java and other programming languages.

Syntax

Table 8.24. check script syntax

Production	Syntax	Links
`check_script_instruction`	`"check" "script" condition error_info ?`	the section called “`check script` instruction”
`condition`	`-> expression -> expression "compare" comparison_operator expression`	the section called “`condition`”
`error_info`	`( "error_message" ":" expression ) ? ( "error_id" ":" identifier ) ? ( "error_data" ":" expression ) ?`	the section called “`error info`”

condition is an expression of type yes_no that evaluates to yes if the condition is fulfilled. For more information see the section called “condition”
error_info is an optional clause used to return more specific error data if the condition is not fulfilled (e.g. a localized error message). For more information see the section called “error info”

Example

Example 8.25. check script example

service instruction_examples

   command check_script_example
      script
      
         var positive32 i
         
         // do some complex computation to determine i
         // ...

         // now make certain that i is between 3 and 7
         // if the check succeeds, script execution continues,
         // else script is immediately stopped and an error is raised.
         check script i >= 3 and i <= 7
         
         // alternative code:
         // - distinct between i too small and i too big
         // - show both, 'wrong value of i' and 'limit', in error message
         // - assign identifier to error
         check script i compare >= 3 &
            error_message: "i must be greater or equal to 3" &
            error_id: i_too_small
         check script i compare <= 7 &
            error_message: "i must be less or equal to 7" &
            error_id: i_too_big

      end script
   end command

end service

Suppose that the check fails because the value of i is 2. Then the first check script instruction in the above code would generate an error message like:

    feature: se_instruction_examples.co_check_script_example
    library: li_explore.li_doc_examples.li_instructions
       line: 12
instruction: check script i >= 3 and i <= 7
    message: A script condition has been violated. [script_condition_violation]

And the message produced by the second check script instruction would be:

    feature: se_instruction_examples.co_check_script_example
    library: li_explore.li_doc_examples.li_instructions
       line: 18
instruction: check script i compare >= 3 &
                error_message: "i must be greater or equal to 3" &
                error_id: i_to_small
    message: i must be greater or equal to 3 [i_to_small]
 left value: 2
right value: 3