Skip to main content

Message handling with CODESYS Scripting Scripting

Requirements: CODESYS V3.5 SP17 or newer with installed CODESYS Scripting Version 4.2.0.0

Preparations: Copy the desired code example to a file and save it as a Python script under any name.

To execute the saved Python script, follow these steps:

  1. Start CODESYS.

  2. Click the Tools → Scripting → Execute Script File menu command.

  3. In the Select Script File dialog, select the Python script which should be executed.

All outputs are displayed in the Messages view in the Scripting category.

. Terminology

  • Message Service: Functionality of the Automation Platform to display different prompts which can then be processed automatically if necessary

  • Message Key: Unique identifier for a prompt which has been generated via the message service. Not every prompt has a message key. Message keys of prompts are normally hidden, but they can be displayed using the property system.log_prompt_details (see below: Property: system.log_prompt_details).

Property: system.script_prompt_handling

You can use the property system.script_prompt_handling to specify if and how message service prompts are processed automatically.

Example 34. Example 1

The values ScriptPromptHandling.LogPrompts and ScriptPromptHandling.ForwardUnknownPrompts are assigned.

  • The value ScriptPromptHandling.ForwardUnknownPrompts specifies that all prompts without a matching entry in system.prompt_answers are forwarded to the underlying message service.

  • The value ScriptPromptHandling.LogPrompts specifies that, for all prompts with an entry in system.prompt_answers is displayed in the message view, with which values the prompt was confirmed.

system.script_prompt_handling = ScriptPromptHandling.LogPrompts | ScriptPromptHandling.ForwardUnknownPrompts


Example 35. Example 2

The values ScriptPromptHandling.LogPrompts and ScriptPromptHandling.AlwaysForwardPrompts are assigned.

  • The value ScriptPromptHandling.AlwaysForwardPrompts specifies that all prompts are forwarded to the underlying message service. Matching entries in "system.prompt_answers" are ignored.

  • ScriptPromptHandling.LogPrompts has no effect in this case because ScriptPromptHandling.AlwaysForwardPrompts has the highest priority and overrides all other options.

system.script_prompt_handling = ScriptPromptHandling.LogPrompts | ScriptPromptHandling.AlwaysForwardUnknown


Important

The following additional conditions apply to all prompts which require an additional user interaction (for example, selecting check boxes) when only ScriptPromptHandling.SuppressPrompts or ScriptPromptHandling.LogPrompt is set:

  • All prompts without a message key are forwarded to the underlying message service.

  • All prompts with a message key require an entry in system.prompt_answers.

Property: system.process_script_prompts

With the system.process_script_prompts property, you can specify whether prompts which are generated via system.ui should also be processed by the message handling of CODESYS Scripting.

Example 36. Example 1

In the following example, the processing of prompts, which are generated via CODESYS Scripting, is enabled.

When this script is executed, the generated info prompt is processed by the message handling of CODESYS Scripting and the result is displayed in the message view.

system.process_script_prompts = True
system.script_prompt_handling = ScriptPromptHandling.LogPrompts
system.ui.info("my info message", "message_key")


Example 37. Example 2

In the following example, the processing of prompts, which are generated via CODESYS Scripting, is disabled.

When this script is executed, an info prompt opens which is not processed by the message handling of CODESYS Scripting.

system.process_script_prompts = False
system.script_prompt_handling = ScriptPromptHandling.LogPrompts
system.ui.info("my info message", "message_key")


Property: system.log_prompt_details

With the system.log_prompt_details property, you can specify whether all details of a prompt should be displayed in the message view before processing. This is especially useful if the response for a more complex prompt should be stored in system.prompt_answers. Because the message key of a prompt is also output, the method can be used to determine the matching message key for use in system.prompt_answers, for example.

Example 38. Example 1

In the following example, logging for prompt details is enabled. After that, a prompt with additional options is generated.

When this script is executed, the prompt appears and all information about this prompt is displayed in the message view.

system.log_prompt_details = True
system.process_script_prompts = True
options = ["Option 1", "Option 2", "Option 3"]
system.ui.select_many("my info message", PromptChoice.OKCancel, PromptResult.Cancel, options, "message_key")


Example 39. Example 2

In the following example, logging for prompt details is disabled. After that, a prompt with additional options is generated.

When this script is executed, the prompt appears. No information about the prompt is displayed in the message view.

system.log_prompt_details = False
system.process_script_prompts = True
options = ["Option 1", "Option 2", "Option 3"]
system.ui.select_many("my info message", PromptChoice.OKCancel, PromptResult.Cancel, options, "message_key")


Property: system.prompt_answers

With the system.prompt_answers property, you can specify how responses should be made to specific prompts.

This is necessary

  • When prompts should not be answered with the set default values

  • For prompts which require additional user interaction (for example, selecting check boxes)

Important

Only responses for prompts with a message key can be stored.

Prompts without additional selection options

In the following example, the way in which the response to prompts with the message_key_1 message key should be done is stored in system.prompt_answers. In this example, all prompts with this message key are answered with OK answered.

When this script is executed, two prompts are generated one after the other.

  • The first prompt with the message_key_1 message key is processed automatically and the result is displayed in the message view.

  • The second prompt with the message_key_2 message key is displayed.

system.process_script_prompts = True
system.prompt_answers["message_key_1"] = PromptResult.OK
system.ui.prompt("automatically processed prompt", PromptChoice.OKCancel, PromptResult.Cancel, message_key="message_key_1")
system.ui.prompt("shown prompt", PromptChoice.OKCancel, PromptResult.Cancel, message_key="message_key_2")

Prompts with additional single selection

For prompts which expect the selection of one option from a list of possible options, the option which should be selected must be stored in system.prompt_answers for the corresponding message key.

There are two options for this:

  • Specify the zero-based index of the desired option

  • Store a delegate of type MultipleChoiceSelector

Example 40. Example 1

In the following example, index is stored in system.prompt_answers, which should be used for all prompts with the message_key_1 message key.

system.process_script_prompts = True
options = ["Option 1", "Option 2", "Option 3"]
system.prompt_answers["message_key_1"] = 1
system.ui.choose("single choice prompt", options, message_key="message_key_1")


Example 41. Example 2

In the following example, a delegate of type MultipleChoiceSelector is stored in system.prompt_answers which should be used for all prompts with the message_key_1 message key.

from System import Array

# filter function
def my_filter(choices):
    return Array.IndexOf(choices, "Option 2")

system.process_script_prompts = True
options = ["Option 1", "Option 2", "Option 3"]
system.prompt_answers["message_key_1"] = MultipleChoiceSelector(my_filter)
system.ui.choose("single choice prompt", options, message_key="message_key_1")


Prompts with additional multiselection

For prompts which expect the selection of multiple options from a list of possible options, the options which should be selected and the result that the prompt should respond with must be saved in system.prompt_answers for the corresponding message key.

There are two options for this:

  • Specify the zero-based index of the desired option

  • Store a delegate of type MultipleChoiceSelector

Example 42. Example

In the following example, a tuple is stored in system.prompt_answers which firstly contains the PromptResult to be used and secondly contains a delegate of type PromptChoiceFilter.

When the script is executed, the prompt is automatically answered and the result is displayed in the message view. For the individual options, Boolean is used to specify whether they have been selected.

# filter function
def my_filter(choice):
    return choice in ("Option 1", "Option 3")

system.process_script_prompts = True
options = ["Option 1", "Option 2", "Option 3"]
system.prompt_answers["message_key_1"] = (PromptResult.OK, PromptChoiceFilter(my_filter))
system.ui.select_many("select many prompt", PromptChoice.OKCancel, PromptResult.OK, options, message_key="message_key_1")


Prompts with additional, application-specific selection options

In the following example, a tuple is stored in system.prompt_answers which firstly contains the PromptResult to be used and secondly contains a delegate of type PromptCustomControlValueProvider.

Example 43. Example

The following example shows how such a delegate is implemented and stored in system.prompt_answers . The IDs of the individual sub-controls can be read via system.log_prompt_details .

# filter function
def my_filter(control_id):
    if control_id = id_1:
        return "value_for_id_1"
    if control_id = id_2:
        return "value_for_id_2" 
   return None

system.prompt_answers["message_key_1"] = (PromptResult.OK, PromptCustomControlValueProvider(my_filter))


: