How to Work with Background Procedures

Overview

MCL-Designer's typical workflow (using programs, global/local procedures, routines, screens, etc.) is executed in the foreground, meaning, it uses a main thread.

A Background Procedure is similar to a standard program except it, specifically, runs in the background, parallel to the foreground workflow, with the use of a secondary thread.

Background procedures are suited for:

•potentially time consuming operations (asynchronous execution) that do NOT require operator interaction - interface elements such as screens and controls or processes that call interface elements (ex: the processes of the Display Controls group) are NOT available for background procedures.

•operations executed as "application services", meaning, operations that handle specific/recurring tasks related to application management such as the automatic archiving/deleting of old files or querying the host on a regular basis.

•operations that manage the application/device's interaction with external hardware, meaning, the background procedure acts as a "device driver". Ex: A background procedure in charge of the printing of a label by an external printer.

Background procedures are always called by a program in the foreground with the use of the Branch process "Call Background Proc.".

Check the examples of Background Procedures provided at the end of the topic.

Custom Actions

This type of action can be used by background procedures to share data with the foreground. You can create as many custom actions as necessary in your project and use them in the required background procedure(s). You can also have multiple background procedures feed data to the same custom action. See Custom Actions.

This type of action includes its own parameters.

Operationally speaking, the use of a custom action within a background procedure requires the following:

At Background Level

1. Define the necessary custom action(s). You can access the available custom action list by clicking , whenever available (ex: in the properties window of the "Trigger Action" process).

See Custom Actions.

2. Create the required background procedure(s).

3. Within the intended background procedure, use a "Trigger Action" Branch process to associate the custom action to its execution and inform the foreground that the declared custom action is available with data. (At the same time, this process can also be used to set values for the custom action's parameters.)

At Foreground Level

4. Use the "Call Background Proc" process in the intended program to initiate the required background procedure/assign input values to it.

5. Add the required custom action to a screen (click in a screen's "Actions" tab and, in the resulting window, select the intended custom action from the drop-down).

Once the "Trigger Action" process is executed in the background, the foreground program with the added custom action in one of its screens will retrieve the custom action's data and trigger its own business logic (with the use of processes that will handle the data received from the background execution).

If required by the nature/purpose of the custom actions, it is possible to queue them so a custom action is NOT replaced by a newly generated custom action and you lose its data.

Exchanging Data via Custom Actions

A custom action is a way for background procedures to interact with the foreground - it shares information with the running foreground program. Meaning, a custom action can be associated to/started by a background procedure via a "Trigger Action" process which also notifies the foreground that there is information to share. In turn, the foreground retrieves that information with the use of a screen that references that custom action. See To Add a Custom Action to a Screen

Exchanging Data via Background Variables

Background procedures use Background variables to exchange data between the background procedure and the program running in the foreground. See Background Variables.

They have Global ("G_"), Program ("P_"), App Params ("A_)" and System ("X_") variables at their disposal.

Background procedures work with input values provided by the calling program via the "Call Background Proc." process. Input values are stored/assigned to a specific type of Background variable - an Input Background variable.

This type of Background variable is created within the background procedure's properties window, specifically, the "Input" tab. See Adding a Background Procedure.

The output values of a background procedure are stored into Output Background variables and they are retrieved by the program running in the foreground with the use of any process that can access the content of a variable.

Output Background variables are created in the "Output" tab of a background procedure's properties window. See Adding a Background Procedure.

Background variables encompass Input and Output variables but it is also possible to create generic Background variables to store other types of values - if you access a "Variable Select" window outside the "Input" and "Output" tabs, the defined variable will not have a specific type. See To Select/Create a Variable.

Each background procedure uses its own Program variables and they cannot be shared with other background procedures or other foreground running programs.

Background Procedure Processes

There are specific processes that deal with background procedures. Some are integrated in the Branch group of processes, others in the Variable group of processes.

•The "Call Background Proc" process - is used to call the intended background procedure and assign input values to it. It is a Branch process. SeeWorking with Call Background Process. It is ONLY available outside the "Background Procedures" module - it can only be used in the foreground.

•The "Check Procedure Status" process - is used by a foreground program to verify if the background procedure is running or not. It is a Branch process that is NOT available in the "Background Procedures" module. See Working with Check Procedure Status Process.

•The "Wait for Variable Update" process - is a Branch process that is used by the background procedure to check if its variables have been updated by the foreground program(s) and set its own workflow accordingly. This process is ONLY available within the "Background Procedures" module. See Working with Wait for Variable Update Process.

•The "Set Background Var" process - this is a Variable process that assigns output values and/or sets other types of value into generic Background variables. It can be used within the "Background Procedures" module but also in the foreground, meaning, the main thread can also assign values to the Background variables. See Working with Set Background Var Process.

•The "Trigger Action" process - is a Branch process that is used to start the defined custom action within the intended background procedure's context and, if necessary, to assign values to its parameters.

It is ONLY available in the "Background Procedures" module. See Working with Trigger Action Process.

Background procedures can be reused in other MCL-Designer projects. The background procedure is exported into the Library (an MCL-Designer folder that stores exportable elements such as data files, programs, global events, screens, etc.) and, when required, it is imported (from Library) into another project or projects.

See To Export a Background Procedure to Library and To Import a Background Procedure from Library).

Background Procedure Usage/Recommendations

When developing a project with background procedures, consider the following:

•An application can run multiple background procedures - each one uses its own secondary thread.

•The use of several background procedures (secondary threads) affects the target device's performance. The developer must analyze/balance the quantity of background procedures and the target device's capabilities (ex: memory, processing) so as to maintain maximum performance.

•A background procedure CANNOT call other background procedures.

•A specific background procedure has to be stopped prior to being called again.

•All background procedures must be explicitly finished before exiting/quitting the application (we recommend the programming of a "graceful exit"). See Examples of Background Procedures.

•A background procedure uses its own variables (Background variables identified with a "B_") but it can also use global ("G_"), program ("P_"), system ("X_") variables and app params ("A_").

•Background variables are mainly used to communicate with the foreground application but global, system variables and app params can be shared with other background procedures/programs.

In the case of global variables, we recommend the use of background variables instead, to avoid potential conflicts after the export/import of a background procedure onto another project that uses a global variable with the same name but with a different purpose.

•It is possible to retrieve the background variable values of a background procedure that has been stopped. However, if a background procedure is restarted, the background variables are reset, meaning, the values stored during the previous execution are lost and the variables have their initial values restored.

•Profiles created within a background procedure (ex: Host, Aux, Web Service) are also available for the programs running in the foreground and vice versa.

•Besides the Background variables, background procedures can also include custom actions to notify/share data with the foreground application. You can associate specific custom actions to a background procedure that, when called by a program, can trigger the execution of something in the foreground. Ex: Associate/start a custom action in a background procedure (via the "Trigger Action" process) to notify when the device is located on a specific GPS coordinate. Add this custom action to a screen of the required foreground program to retrieve the custom action's notification and trigger the workflow (processes) defined for that screen.

Some process groups/processes are NOT available for background procedures because:

▪they are used by the foreground to call/check the intended background procedure (the "Call Background Proc" and "Check Procedure Status" Branch processes).

▪ they represent operator interface. Ex: The "Display Controls" and "Control Operations" process groups affect controls which cannot be applied onto background procedures and the device's camera related processes are also grayed out.

▪they call/reference elements that only run in the foreground such as global events (ex: the "Start/Resume", "Reset" and "Suspend" processes related to global events).

The "Background Procedures" Right-Click Menus

Background procedures are managed in the "Procedures" module - this module includes the project's Global/Background Procedures and its Global Events. Right-clicking the background procedures section/elements provides the options to manage them:

•Right-clicking an empty area within the "Procedures" module provides a menu with general options:

	Add Global Procedure	Use it to add a global procedure. See Global Procedures.
	Add Background Procedure	Adds a background procedure. See Adding a Background Procedure.
	Add Global Event	Adds a global event. See How to Work with Global Events.
	Library Import	Click "Library Import" to open the "Library Manager" window so you can import the intended element into your current project. If you intend to import a background procedure, see To Import a Background Procedure from Library.

•Right-clicking "Background Procedures" (the name of the section that displays the existing background procedures) provides the following related options:

	Add Background Procedure	Adds a background procedure. See Adding a Background Procedure.
	Library Import	Click "Library Import" to open the "Library Manager" window so you can import a background procedure into your current project. See To Import a Background Procedure from Library.

•If you right-click an existing background procedure, you access the following options:

	Edit	Opens the selected background procedure's properties window so you can edit it. See Editing a Background Procedure.
	Copy	Copies the selected background procedure. Use the "Paste" option in the right-click menu of the destination to complete the operation.
	Paste	Pastes the previously copied background procedure. This option is only available after a "copy" operation takes place.
	Duplicate Background Procedure	Duplicates the selected background procedure with all its features and processes. The duplicate has the same name as the original background procedure, plus an incremented number. See Duplicating a Background Procedure.
	Delete	Deletes the selected background procedure. See Deleting a Background Procedure.
	Add Local Procedure	Adds a local procedure to the selected background procedure. See Local Procedures.
	Add Routine	Adds a routine to the selected background procedure. See Working with Routines.
	Input	Opens the selected background procedure's "Input" tab directly.
	Output	Opens the selected background procedure's "Output" tab directly.
	Library Export	Use this option to export the selected background procedure. See To Export a Background Procedure. If the selected background procedure is a "locked" background procedure (identified with a ), the "Library Export" option is NOT applicable. "Locked" elements CANNOT be exported - any export attempt leads to an error message.
	Library Import	Import a background procedure from "Library". See To Import a Background Procedure.
	Search in ...	Opens the "Search" window. See Detail of Search. The "Search in..." option in this right-click menu enables an automatic to search in the selected global procedure.
	Search 'xxx'	Opens the "Search" window. See Detail of Search. The "Search 'xxx'" option in this right-click menu enables an automatic search of the selected text string in the current project and returns all the occurrences.

Examples of Background Procedures

, at a specific moment)

Purpose: To collect GPS coordinates.

This background procedure is started by the foreground application when it needs to mark the current GPS coordinates.

The background procedure runs once and stops when the task is completed.

Step-by-step

1. In the "Procedures" module, add a background procedure and fill in its tabs as follows:

a. In the "General" tab, enter a name for the background procedure ("Collect_Position_GPS_Coordinates").

This background procedure does not require the definition of input values - skip the "Input" tab.

b. In the "Output" tab, define the variables that will store the output values related to the required GPS values ("B_Latitute"; "B_Longitude"; "B_Satellites").

As an option, create a Background variable ("B_State") to represent the background procedure's current state ("Started", "Finished").

c. Build the background procedure's business logic in the "Procedure" tab as follows:

•Use the "Set Background Variable" to assign a state to the background procedure ("B_State" - Background variable's value = "Started").

•Use the "Start/Stop GPS" process to initiate the device's GPS system.

•The label "CHECK_VALID_GPS" is in charge of testing the GPS validity (via a "Test & Branch" process), retrieving the necessary GPS data (with a "Get GPS Value" process) and storing them in Program variables. This label also includes a "Set Background Variable" process to assign the Program variable values to the corresponding Background variable before it directs the background procedure's flow to the "DONE" label.

•The "DONE" label informs that, if the GPS data collection was successful, the background procedure is complete (the "B_State" Background variable is assigned a "Finished" value via the "Set Background Variable" process).

•The "CHECK_VALID_GPS_WAIT" label allows the background procedure to wait 1 second before returning to the "CHECK_VALID_GPS" label.

2. The background procedure "Collect_Position_GPS_Coordinates" will be called in the foreground with a "Call Background Procedure". This process can be added to a screen, a control, a routine, a "routine in", a "routine out" or a global event.

•In this case, the "Call a Background Procedure" process is preceded by a "Check Procedure Status" process to verify if the intended background procedure is currently running or not. If it is running, the foreground will NOT retrieve the values of the Background variables. If, however, the background procedure has stopped, the foreground element that calls the background procedure will read the intended Background variables.

The GPS values will be available for retrieval by the program running in the foreground as long as it does NOT restart this background procedure (with a "Call Background Procedure" process). Restarting the "Collect_Position_GPS_Coordinates" means that the previous values stored in the Background variables will be replaced - the "B_State" variable will be set with a "Started" value and the Program/Background variables will receive new GPS information.

Purpose: To continuously collect GPS coordinates while the operator is working with the application.

This background procedure is started when the application starts and it stores the valid GPS coordinates it collects every 2 seconds (or more) in a data file. It runs in a loop and is stopped when the operator exits the application.

1. In the "Background Procedures" module, add a background procedure and fill in its tabs as follows:

a. In the "General" tab, enter a name for the background procedure ("Collect_GPS_Coordinates").

b. In the "Input" tab, define the input variable that will store the time period the background procedure will wait to get the GPS coordinates - "B_Wait_Time".

The value for this variable is provided by the foreground, specifically, by the "Call a Background Procedure" process that will be used to call the "Collect_GPS_Coordinates" background procedure - value = "2".

c. As an option, in the "Output" tab, create an Output Background variable ("B_State") to store the background procedure's current state ("Started"; "Finished").

d. Add the following processes in the "Procedure" tab to fulfill the background procedure's purpose:

•Use the "Set Background Variable" to assign a "Started" state to the background variable "B_State".

•Use the "Start/Stop GPS" process to start the device's GPS system.

•The label "CHECK_VALID_GPS" is in charge of testing GPS coordinates validity (via a "Test & Branch" process), retrieving the necessary GPS data and storing them in Program variables (with a "Get GPS Value" process). Once the "Write Record" process writes the value of the defined Program variables into the specified records of the "<GPS_Coordinates>" data file, the flow proceeds to the "GPS_WAIT" label.

•This label includes a "Wait for Variable Update" process - the objective is to wait for the update (by the foreground) of the "B_Command" Background variable to stop the background procedure or, if the time out defined by the "B_Wait_Time" Input Background variable expires, to return to the "CHECK_VALID_GPS" label. The "B_Wait_Time" Input Background variable was created in the current background procedure (in its "Input" tab) and its value was assigned by the foreground in the "Call Background Procedure" process that started the current background procedure.

The "Test & Branch" process verifies the value contained in the "B_Command" Background variable and redirects the flow accordingly (value = "STOP" >> label "DONE" / value = XXX >> label "CHECK_VALID_GPS").

▪Before the application is closed, the foreground writes the value "STOP" in the Background variable "B_command" to ensure the background procedure closes before the application exit is executed.

•The "DONE" label is part of a "graceful exit":

▪the "Set Background Variable" process assigns a "Finished" value to the "B_State" Output Background variable to share the state of the background procedure.

▪In the foreground (the calling element), the "Check Procedure Status" process, along with the "Message Box" process, is used to ensure that the running foreground application is only exited automatically if the background procedure is no longer running. If, however, the background procedure is still running, the operator is made aware of that fact and must decide if he wants to exit the application immediately or wait a bit longer.

The GPS values will be available in the "<GPS_Coordinates>" data file. The foreground can use this information whenever necessary or even delete the content of the data file. Restarting the "Collect_GPS_Coordinates" background procedure (via a "Call Background Procedure" process) means that the "B_State" variable will be set with a "Started" value again but the data file content will still be present (if not deleted by the foreground, in the meantime).

Purpose: To communicate with a web service and notify the foreground if there are new tasks.

This background procedure is started at the same time as the foreground application. The background procedure runs in a loop, constantly checking with the web service if there are new tasks and, if there are, the foreground application is notified. The foreground application can, however, pause/resume or stop the background procedure, whenever necessary.

1. Define a custom action to be used by the background procedure to notify the foreground whenever there is a new task available.

See To Define a "Custom Action" in a Project.

The "New_Task_Notification" custom action has 2 parameters:

▪"Task_Number" - the identification number of the provided task.

▪"Time_Stamp" - a time stamp to identify when the new task is provided.

2. In the "Procedures" module, add a background procedure. Fill in the "General", "Input" and "Output" tabs as described below:

a. In the "General" tab, name the background procedure as "New_Tasks_Monitor".

b. In the "Input" tab, create an Input Background variable to store how long the background procedure will wait to get a response from the contacted URL - "B_Wait_Time".

The value for this variable is provided by the foreground, specifically, by the "Call a Background Procedure" process that will be used to call the "New_Tasks_Monitor" background procedure - value = "2".

c. As an option, you can create an Output Background variable ("B_State") in the "Output" tab to store the background procedure's current state ("Started, "Paused" or "Finished").

3. Use the necessary processes in the background procedure's "Procedure" tab and foreground application to construct the background procedure's business logic:

In the "Procedure" Tab (Background Procedure)

•The "Set Background Variable" assigns a "Started" value to the Background variable that represents the background procedure's current state - "B_State".

•The label "CONTACT_WEB_SERVICE contains the actual request to a URL (via an "HTTP Request" process) and the "Trigger Action" process which notifies the foreground that there is a custom action to be retrieved by the foreground.

•The label "WAITING_POINT" includes a "Waiting for Variable Update" process:

	If the "B_Command" Background variable is updated with a command received from the foreground, the flow proceeds to the "EVALUATE_COMMAND" label.
	If there is no update during the time period defined in the "B_Wait_Time" Background variable (value provided by the foreground with the "Call a Background Procedure" process), the flow returns to the "CONTACT_WEB_SERVICE" label to perform another HTTP request.

•The "EVALUATE_COMMAND" label uses a "Case & Branch" process to determine the flow of the background procedure depending on the value received in the "B_Command":

	The "PAUSE"/"RESUME" values send the flow to the respective label.
	If none of those values is included in the "B_Command" variable, it means the variable contains the value "STOP" and the flow proceeds to the "ON_STOP_DO" label.

▪When the foreground decides to pause the background procedure's execution, it writes the value "PAUSE" in the Background variable "B_Command".

▪When the foreground decides to resume the background procedure's execution, it writes the value "RESUME" in the Background variable "B_Command".

▪Before the application is closed, the foreground writes the value "STOP" in the Background variable "B_command" to ensure the background procedure closes before the application exit is executed.

•The "ON_RESUME_DO", "ON_PAUSE_DO" and "ON_STOP_DO" labels use the value, assigned by the "Set Background Variable" process, of the "B_State" variable to define the background procedure's current state.

•In the label "ON_RESUME_DO", the background procedure retrieves the initial HTTP request’s waiting time ("B_Wait_Time") and, immediately, forces a new HTTP Request - "CONTACT_WEB SERVICE".

•In the label "ON_PAUSE_DO", "the background procedure stores the initial HTTP request’s waiting time ("B_Wait_Time") in a Program variable (“P_Wait_Time_Store"), sets the current waiting time to infinite ("B_Wait_Time" = "0") and moves to the label “WAITING_POINT”, waiting for the foreground application to signal the background procedure should resume its execution.

•The "SKIP_STORE_PREV_VALUE" label returns the flow to "WAITING_POINT".

•The "ON_STOP_DO" stops the background procedure.

In the Foreground

•Add a "Check Procedure Status" and a "Call Background Procedure" to a routine or the initial screen's routine in.

•Define a control (a single Button to serve both purposes, for instance) to pause/resume the background procedure's execution and add the following processes.

▪The value of the Local variable "L_Control_value" (text of the Button can be "Pause" or "Resume") is used by the "Test & Branch" process to direct the foreground flow to the intended label.

▪Each label is in charge of assigning a specific value to the "B_Command" Background variable via a "Set Background Variable" - "SEND_PAUSE" assigns a "PAUSE" value, "SEND_ RESUME" assigns a "RESUME" value and also changes the Button control's text with the use of the "Set Value" process.

"B_Command" is read within the background procedure to determine its flow.

•Use the "Set Background Variable" process to assign a "STOP" value to "B_Command" to ensure that the background procedure is stopped before exiting the application.

•In the intended screen, add the custom action ("New_Task_Notification") that was declared in the selected background procedure to retrieve the data from the custom action's parameters.

▪The values retrieved from the "New_Task_Notification" custom action (specifically, from its "Task_Number" and "Time_Stamp" parameters) are, automatically, stored into predefined Local variables named after the custom action's parameters - "L_Task_Number" and "L_Time_Stamp".

Topics

This chapter covers the following topics:

Topic
Adding a Background Procedure
Duplicating a Background Procedure
Exporting/Importing a Background Procedure
Editing a Background Procedure
Deleting a Background Procedure