Table of Contents
A script belongs to an object or a service and is used to execute a set of instructions in order to complete a specific task.
A script is composed of
- input arguments
- output arguments
- instructions
- an optionally appended test script for unit testing
A script can have 0, 1 or more input arguments. Input arguments are objects that are transferred from the script caller to the script. They are created by the script caller and then used within the script. Each input argument is a reference to an object of a defined type, and is accessed through its unique identifier.
A script can also have 0, 1 or more output arguments. Output arguments are objects that are transferred from the script back to the script caller. They are created by the script and then used by the script caller. Each output argument is a reference to an object of a defined type, and is accessed through its unique identifier.
Each script contains 1 or more script instructions that are executed in order to complete the script's task. For more information see Chapter 8, Script instructions
A script can optionally contain a test script used to test the correct execution of the script by checking the results for different input values. Test scripts are Obix's means to unit testing. For more information see Chapter 21, Testing
The following figure shows a schematic representation of a script:
There are different categories of scripts, subdivided into different kinds of scripts, and each kind of script is used for a specific purpose, as shown in the following table:
Table 7.1. Categories and kinds of scripts
| Script category | Script kind | Used to | Arguments implicitly defined |
|---|---|---|---|
| command | command script | execute a command | no |
| attribute getter/setter | attribute get script | get (read) an attribute's value | yes |
| attribute set script | set (write) an attribute's value | yes | |
| check | command in_check script | check several input arguments before executing a command | yes |
| input argument check script | check one input argument before executing a command | yes | |
| command out_check script | check several output arguments after executing a command | yes | |
| output argument check script | check one output argument after executing a command | yes | |
| attribute list check script | check several attributes of an object or service | yes | |
| attribute check script | check one attribute | yes | |
| default value | input argument default script | define the default value of a command's input argument | yes |
| attribute default script | define the default value of an attribute | yes | |
| test | test script | test anyone of the above scripts | yes |
As we can see from the last column in the above table, a script's input and output arguments are always implicitly defined, except in case of the command script, whose arguments must be explicitly defined in the source code.
Each kind of script will more thoroughly be explained in subsequent sections.
A script is executed through a script caller, which is a source code instruction or part of a source code expression that calls the script.
All kinds of scripts, except the command script, are called implicitly. For example, all input check scripts are automatically called before executing a command, and all output check scripts are automatically called after executing a command. However, all scripts can also be explicitly called at any time. For example, a command input argument check script can manually be called from any script to check if a given value would be accepted as input argument.
When a script is called explicitly, it is accessed through its script selector. A script selector is an identifier path (i.e. several identifiers separated by a dot) which is unique within the object or service. The syntax of a script selector depends on the script kind and is explained in the following sections.
The general syntax to call a script is the following:
Table 7.2. Script execution syntax
example of calling a script with 2 input and 3 output arguments (from the section called “Examples”):
var string result; file_error var file_handle log_file se_logger_7.co_log_message ( & i_message = "The sun is shining!!!" & i_message_id = "sunshine" ) & ( v_result = o_result & v_log_file = o_log_file & v_file_error = o_file_error ) if v_file_error =r void then // everything ok else // we have a problem end if
Each script has an implicitly defined variable whose id is v_program_error_ and whose type is ty_error_program. This variable holds the last error that occurred in the script. It is used infrequently in case of special error handling. Please refer to Chapter 13, Runtime error handling for more information.