Navigation:  How to Work with Processes > Working with the Variable Processes Group

 

Process Purpose

 

The Variable group of processes allows for multiple operations that involve variables.

The results of these operations ("Insert"; "Extract"; "Assign"; etc.) are stored in variables.

 

 

A variable is a memory area in the device where data is stored temporarily. The content of a variable is an UNICODE character string that can be displayed on the device's screen, at any moment.

 

 

Variable Types

 

There are three different main groups of variables that can be used in a project:

 

User Defined Variables

The User Defined Variables are used to store data. They are created by the programmer to suit the needs of the application being developed. They include:

 

•Global Variables

A Global Variable is defined in one program and can be used in any of the other programs or new projects. The contents can be retrieved, updated or modified by the other programs. (examples of variable codes: A0, A1, A2, A3, A4, A5, A6, A7, A8, A9, B0, B1, B2…)

 

•Program Variables

A Program Variable is defined in one program and cannot be used in any of the other programs. The contents can be retrieved, updated or modified only in the current program. (examples of variable codes: 0A, 1A, 2A, 3A, 4A, 5A, 6A, 7A, 8A, 9A, 0B, 1B, 2B…)

 

•Local Variables

Local Variables are used in actions associated to controls (ex: a "Change" action). There are specific local variables associated to specific control actions. The only exception is the "RFID" action. Even though this is a screen action, you can use local variables. These local variables provide information regarding the execution of the action.

Ex: Consider a "Variable Assign" process that you have added to a "Change" action within a File Browse control. When assigning the appropriate variables, you will have access to specific pre-existing local variables such as "L_Record_Number" (which provides you with the number of the selected record).

 

•Background Variables

Background Variables are ONLY used in a Background Procedure context. They are used for communication between the background procedure and other programs in the foreground.

They can be used to exchange data or for the foreground application to send commands to be executed by the background procedure.

These variables are used to store input and output values but also any other value required by the Background Procedure's execution.

All background variables are represented by an initial "B_", but there is added information in the window that includes the variable list:

 

▪Background variables that represent input values for the execution of the background procedure (created in its "Input" tab) are identified with an "I";

▪Background variables that represent output values/the result of the background procedure's execution (defined in the "Output" tab) are identified with an "O";

▪You can also create background variables that have nothing to do with input and/or output values. You can create them by accessing a "Variable Select" window outside the background procedure's context (ex: via the / buttons in a process's properties window) and adding them to the "Background" side tab - they have no particular identification besides the "B_".

 

Detail of a "Variable Select" window listing all types of background variables:

 

Ex: The variables "B_Status_EX1" and "B_Counter_EX1" store output values; "B_Loops" stores input values and "B_Command" is meant for another value.

 

The "Set Background Var" process is available for background procedures and programs running in the foreground to assign specific values to background variables (see Working with Set Background Var Process).

The programs in the foreground can only update the background variables if the background procedure that uses them is running.

If needed, the value of a background variable can be retrieved even after the background procedure has stopped. If, however, you restart that background procedure, the values of its background variables are also reset to their initial value.

 

Background variables that handle input values can also be set when called via the "Call Background Proc" process. See Working with "Call Background Proc Process".

 

 

System Variables

 

•System Variable

The System Variables are not defined by the user. They contain system information that can be used by the programs in the application. System variables contain information such as current date & time, selected record number in a file browse control, battery level, program name and version. System variables are grouped in “Audio”; “Camera”, “Date”, “Device”, “GPS”, “Imager”, "RFID"; “Network”; "App_Info", “System”, "Timer", "Operator", "Navigation", "Voice", "Special" and "NFC" variables.

 

Some of the system variables that concern the "Operator" (X_USR_CUST1/X_USR_CUST2/X_USR_CUST3/X_USR_CUST4/X_USR_CUST5) are mapped with values that are defined/customized within the MCL-Mobility Platform (in the operator's profile).

Refer to the MCL-Mobility Platform User Guide for more information on the "Info" options in the "Properties" Tab of the "Operator Details" page.

 

 

The “Device” related system variables can only return valid information if it is provided by the target device.

Ex: If a target device does NOT provide information on battery life, the corresponding system variable will NOT return battery life info to the application.

 

 

Application Parameters

 

•App Params Variables

The App Param Variables are read only variables that reference application parameters included in a parameters file.

These variables are used to contain parameter values that are relevant to the current project.

They are created/available in the "Variable Select", specifically, the "App Params" tab.

The variable name starts automatically with an "A_" to identify its scope, followed by the name of the parameter you require.

Once an "app params" variable is created, a parameters file is generated with that information.

 

•Parameters File

This specific file is generated/refreshed when content is added to the "App Params" tab.

By default, the file is named "project.par" and it is located in the current project's "Data" folder. If necessary, you can rename the file.

The params file will be used to feed the MCL application with the intended values, meaning, it will be possible to retrieve this file from the project directory (after project completion), work it outside the MCL environment (edit the file with external applications such as Wordpad or Notepad, for instance) and deploy it to the device to provide different app parameter values to the MCL application through the App Param Variables - whenever the MCL application requires an application parameter, it will check the current parameters file (located in the device - <APPS>App name\res) and use the values it finds.

 

Parameters File Structure

This file MUST contain 3 sections - INFO; PARAMETERS and DESCRIPTION.

If you want to, you can also add a PERSONAL section.

The name of the parameters file currently in use is stored into the system variable "X_APP_PARAM_FILE".

 

Mandatory Sections

 

Section: INFO

This section contains general information about the project.

MCL-Designer automatically generates the following information: "Type", "Format", "Name", "Version", "Date", "Author", "Company", "Contact_Info", "ProjectName" and "GeneratedBy".

 

Section: PARAMETERS

This section contains all the parameters and their values.

In case of an external edition (the editing of this section after file export), you can update parameter values but NOT add/remove parameters or edit parameter names.

 

Section: DESCRIPTION

This section contains each parameter's description.

 

 

 

•Typical Application Parameters Use

 

During Project Development

1. Add the intended app parameter variables in the "App Params" tab (located in every variable select window - use the / buttons, whenever available, to call it).

The "Name" field is mandatory. The "Value" and "Description" fields can be filled in at this point or later on (in the parameters file, after export).

2. A parameters file named "project.par" is generated and stored in the project's "Data" folder.

 

We recommend you save the project every time you add/edit the "App Params" tab to ensure that the params file is up-to-date.

 

 

Roll Out/Production Environment

3. The parameters file is retrieved from the project's "Data" folder and edited accordingly, meaning, the default/initial values are set for each parameter as necessary.

 

The name of a parameter CANNOT be edited, ONLY its corresponding value.

 

 

It is NOT possible to add new parameters to the file after the project is developed/published - the MCL application will NOT recognize the new parameters because there are NO corresponding app param variables to be fed that information within the application.

 

4. The parameters file is deployed to the device ("<Apps>App name\res") - this can be done manually or via MCL-Mobility Platform (create a configuration and add the parameters file as an application resource in the "Applications" tab - refer to the MCL-Mobility Platform User Guide). The file will feed the app param variables being used within the MCL application.

 

5. This file can be deployed whenever the values of the existing parameters need changing, for instance, if you need to change contact information. Simply edit the parameters file and deploy it (manually or via a configuration created/managed within MCL-Mobility Platform).

 

If required after export, you can use more than one parameters file - for instance, have several versions with different values, divide the original parameters file into two or more, etc.

Make sure the original structure (sections) is maintained, only use the original parameters and rename the several param files as required.

In order to ensure the use of a particular parameters file during MCL application workflow, use the "Set App Param File" process - this process will define which parameters file will feed the app param variables in the application.

 

 

 

 

 

 

 

 

Variable Usage

 

A program can contain Global, Local, Program or System variables.

A Global Procedure only allows for Local, Program or System variables.

Local Procedures use Global, Local or Program variables.

Regarding Routines (Routine, Routine In and Routine Out), they only allow for Global or Program variables.

 

 

All variables can, at any given time, be manipulated by the program to:

 

• Modify their content.

 

• Store data in a data file record.

 

• Send data to the host computer.

 

• Display data on the screen.

 

 

The and icons appear throughout the project. Clicking them provides access to a variables window with a list of variables (distributed over the "Global"; "Program"; "Local", "Background", "App Param" and "System" tabs). The availability of the tabs scope depends on the context. As mentioned above, not all variables are available for all programming contexts. In this window you can create new variables, and select the required one for the current process.

When clicking the icon, in a properties window, you are selecting the variable that will feed data to the process (the process will read data from this variable).

When clicking the icon, in a properties window, you are selecting the variable that will receive data after the process is run (the process will write data on this variable).

 

 

Detail of Variable Select windows

 

 

A variable select window displays the available variables within a project (default local/system variables and the ones you create). The variables are grouped according to type ("Global"; "Program"; "Local", "Background", "App Param" and "System"), each type with the corresponding scope tab.

 

There are two available variable select window types:

•Standard Variable Select window - This window is called with the use of the and/or icons (see To Select/Create a Variable) or if selecting the "Variable Select" and "Variable Insert" options of an input field's right-click menu. The content of this window depends on the active field associated to the clicked icon and the icon itself. It is a blocking window, meaning, it does NOT allow you to proceed until you close it.

Ex: The Standard Variable Select window, which is called with the icon, will never include the "System" scope tab. This icon refers to variables that receive data and system variables only provide system information, they do not receive data.

 

•Floating Variable Select window - This window is called when you press <F3> in your PC and when you open the "Project" menu (in the "Menu Bar") and select "Variables".

This window does NOT block the use of other open windows in the work area. Its content is dynamic, meaning, it displays the variables/scope tabs that relate to the currently active context (ex: a program, a screen, a process, etc.).

Ex: If you press <F3> when a screen is selected, the Floating Variable Select window displays the "Global" and "Program" scope tabs with the available variables for that screen. If the focus is on the "Actions" tab of a control, the window displays four scope tabs - "Global", "Program", "Local" and "System".)

This window allows you to drag a variable into the intended option (that is variable compatible) within a control, a process, etc.

 

Click each scope tab to open a table and view the corresponding variables and/or create more variables of that type.

Each scope tab table includes the following columns:

 

 

If the variable select window is open in the "System" tab, there is one more column in display - the column "Simulation".

It is possible to attribute values to certain system variables for simulation purposes, meaning, the entered values will only be used within MCL-Simulator. The "Simulation" column's rows that are editable have a yellow background and are in edit mode. Simply enter the intended value in the corresponding row.

 

 

If required, you can control the viewed information.

 

•Use the search box to search for values in the "Name", "Category" and "Description" columns:

a. Enter the information in . The results are automatically displayed below.

b. To resume an unfiltered view, delete the information from the search box.

 

•Use the drop-down (below the search box) to filter the variables by category. A category created in the "Program" scope tab will only be available in the drop-down of that "Program" scope tab.

 

 

"App Param" tab

 

 

This tab is used for the app param variables - they store application parameters. See Application Parameters.

It includes the following columns:

 

 

As an alternative, use the right-click menu available in this tab. See Right-click Menu of the "App Param" Tab below.

 

We recommend you save the project after each "App Param" tab edition to ensure that the corresponding parameters file is up-to-date.

 

 

Right-click Menu of the "App Param" tab

 

If you right-click a row in the "App Param" tab, you access the following options.

 

 

 

To Select/Create a Variable

 

After calling a standard variable select or a floating variable select window, proceed as follows:

 

 

To select a variable, for whatever purpose:

a. Click the appropriate scope tab ("Global", "Program", "Local","Background", "App Param" or "System") to display its content.

You can use the "Filter" drop-down to limit the variable display. The drop-down content is affected by the current context.

b. Select a variable among the list available by clicking it and, then, click OR  double-click the intended variable to apply it to the current option.

 

To create a new variable:

a. Click the appropriate scope tab  ("Global", "Program", "Local","Background", "App Param" or "System") and open it.

b. Select a row and, then, click the "Name" field to set it to edit mode.

c. Enter the variable name and any other information in the related fields ("Init Value", "Template Value", etc.).

d. Click outside that field to set it to view mode.

 

As an alternative, you can use the "Add Variable" option available in the right-click menu. To access it, right-click any row in the variable select window.

 

 

To edit a variable:

a. Click the appropriate scope tab ("Global", "Program", "Local","Background", "App Param" or "System") and open it.

b. Click the field you want to edit to set it to edit mode.

c. Enter the necessary changes.

d. Click outside the edited field to set it back to view mode.

 

Click to close the standard variable select or floating variable select window.

 

 

When creating/entering the name of a variable, take its purpose into consideration. It will help to identify its content, especially if there are a lot of variables. For instance, if the variable is designed to store the names of operators, define it as "P_User_Name".

 

The name of a variable obeys a specific syntax that immediately defines the scope. It, automatically, starts with a "P_" (if it is a "Program" variable), an "L_"(if it is a "Local" variable) or a "G_"(if it relates to a "Global" variable"). Spaces are replaced by an underscore.

 

Right-click Menu on Variables

 

•If you right-click a row in the "Global", "Program" or "Local" tabs, you access the following options:

 

 

•If you right-click a row in the "Background" tab, you access the following options:

 

 

•If you right-click a row in the "System" tab, you access the following options:

 

 

 

To Apply a Variable

 

Use one of the following methods to apply the intended variable.

 

Variable availability will depend on the opened variable select window:

•A standard variable select window only displays the tabs/variables that are compatible with the active field that will receive the selected variable. Ex: If you click a field's , this window will NOT include the "System" tab because the active field must define a variable to write in and the variables of the "System" scope are READ ONLY.

The window has an button to apply the variable that was selected. It is a blocking window, meaning, it does NOT allow you to proceed until you close it.

 

•A floating variable select window displays the variables that are compatible with the current context, the variables can be written in or read.

The window has an button to apply the variable that was selected.

 

 

• / Buttons (standard variable select window)

 

a. Click the or button (depending on what is available) of the intended field to open a standard variable select window;

b. Double-click the intended variable OR  select it and, then, click .

 

•Right-click "Variable Select" Option (standard variable select window)

 

a. Right-click the intended field to access a menu;

b. Select the "Variable Select" option which opens the standard variable select window;

c. Click the intended variable to select it and click OR  double-click the variable you want.

The previously selected field is filled in with the selected variable.

 

•Double Click (floating variable select window)

 

a. Click <F3> to open a floating variable select window;

b. Select the target field (making it an active field);

c. Back in the floating variable select window, open the required scope tab;

d. Double-click the intended variable.

The variable is applied to the previously selected field.

 

•Drag-and-Drop (floating variable select window)

 

a. Open the floating variable select window with <F3>;

b. Open the required scope tab.

c. Drag the intended variable into the target field.

 

For the Drag-and-Drop to work, always drop the selected variable into a field that accepts variables (a field with a yellow background or associated to a or icon).

 

 

•The Button (floating variable select window)

 

a. Open a floating variable select window.

b. Select the target field (making it an active field).

c. In the floating variable select window, open the required scope tab.

d. Click the intended variable to select it and click .

The variable is applied to the previously selected field.

 

 

Bear in mind that the previously described methods replace whatever data/value that was already filled in in the target/active field.

If you want to add a variable/variables to a field's existing data/value, you MUST use the "Variable Insert" option available in the field's right-click menu. This option is ONLY available for specific fields, namely, fields that allow text and variables).

See Right-click "Variable Insert" Option (standard variable select window) below.

 

 

•Right-click "Variable Insert" Option (standard variable select window)

 

When available, this option is used to add a variable to data already inserted in the target field. Ex: Text + Variable - "Welcome P_User_Name".

See To Combine Text and Variables into a Control's Text Input Fields.

 

a. Right-click the intended compatible field to access a menu;

b. Select the "Variable Insert" option which opens the standard variable select window;

c. Click the required variable to select it and click OR  double-click the variable you want.

The selected variable has been added to the existing data/value of the target field.

 

 

If the active target field does NOT accept variables, the field's background color will be red and you will NOT be able to drop the selected variable into the field.

If the active field allows variables, the field's background color will be yellow.

 

A floating variable select window cannot be called during the adding of a process because the corresponding properties window is a blocking window. To overcome this, open the floating variable select window before adding a new process. If the floating variable select window is already open, you will be able to use it to view/create or add variables to the process properties window.

 

If a floating variable select window is open, in the background, and you click or (in a process or control's properties window,for instance) the floating variable select window is selected/comes into focus.

 

 

To Delete a Variable

 

If required, you can delete variables from the standard/floating variable select window.

It is possible to delete one or more variables at the same time.

ONLY System type variables CANNOT be deleted.

 

Before you delete a variable, make sure it is NOT being used throughout the project.

 

 

1. Access a select variable window (see Detail of Variable Select windows).

 

2. Open the tab that includes the variable you want to delete.

 

3. Select the row(s) with the intended variable(s).

 

4. Click <DELETE> in your PC keyboard.

 

5. In the resulting window, confirm you want to delete the referenced variable(s).

 

The selected variable or variables are removed from the variable select window and deleted from the project.

 

As an alternative, you can use the right-click menu:

 

a. Select the variable(s) you want to delete,

b. Right-click over the selection and choose "Delete" in the resulting menu.

c. Confirm the variable deleting in the subsequent pop-up.

 

 

The Variable group is divided into: