Multi-Line Control

EZ Load Multi-Line

An EZ Load Multi-Line is a Multi-Line that self-loads based on the value of another control or variable associated with its panel. When the value of the other control changes, the EZ Load Multi-Line is re-populated with the associated value. The EZ Load Multi-Line can be used as a display-only lookup field to display additional information. For example, if the meaning of a Sales Code is not obvious on its own, you can add an EZ Load Multi-Line to your panel to automatically display the description for the Sales Code. When the Sales Code is changed, the description is automatically updated -- no coding is needed.

The EZ Load Multi-Line is automatically loaded when a panel is initially drawn if the control or variable that it is associated with is populated. The associated control or variable is referred to as the trigger. Whenever the value of the trigger control changes, the EZ Load Multi-Line is automatically updated.

To accomplish this, you only need to define the parameters required for an EZ Load Multi-Line:

See Defining an EZ Load Multi-Line.

Note:
EZ Load logic is not compatible with Smart Load logic.

(EZ Load Multi-Line was added in PxPlus 2018.)

Defining an EZ Load Multi-Line

The EZ Load Multi-Line Definition window is used to turn on the EZ Load logic for the target Multi-Line and supply the file and key information required to retrieve the information to be displayed. It also allows you to define load-triggering criteria for the control.

To create an EZ Load Multi-Line Definition:

 

1.

In the NOMADS Panel Designer, access the Properties window for the target Multi-Line.

 

2.

Select the Attributes tab (using the Folder Style version of the NOMADS designer).

 

3.

Click the EZ Load button to bring up the EZ Load Multi-Line Definition window.

This window consists of the following:

Use EZ Load logic

Select this check box to enable EZ Load logic for the Multi-Line.

File Information

(Available when Use EZ Load logic check box is selected)

Identify the information about the file to be read to look up the targeted data to be displayed in the Multi-Line:

Lookup Table

Specify the logical file name of the Data Dictionary defined table to be read to look up the data to be displayed. Use the Query buttons to locate the logical file name by Group or by Name.

Table Key

Select the key to use to read the specified Lookup Table. Hover the mouse pointer over the Information button to display a more detailed key definition.

Key Expression

Enter a PxPlus expression consisting of any combination of variables from the panel, fields from accessible files, global variables, and/or literal values that may be concatenated to create the key value to read the record to retrieve the required data. A key expression may be string or numeric.

Examples:

     TRN_CUSTID$

     CustomerNum

     "D"+FLD#2$(1,3)

     %COMPANY_CODE$+CLIENT_CODE$

     PAD(Company$,5,$00$)+PAD(Department$,10,$00$)+STR(EmployeeNum)

     KEY(__fileFN,KNO=0,KEY=Company$:Department$:EmployeeNum)

Multi-Segment Keys

When dealing with multi-segmented keys (i.e. keys made up of more than one field), you can use a + (plus sign) to concatenate multiple string segments of a key when entering a free-form expression. Be sure to add the correct padding logic to the initial key segments. By default, the initial segments of native PxPlus keys are padded with $00$ characters, and the final segment is not padded. Such a key definition might look like this:

     PAD(Company$,5,$00$)+PAD(Department$,10,$00$)+STR(EmployeeNum)

Individual applications can pad key segments with other characters, such as spaces; therefore, knowledge of the key architecture of individual files is a must. Knowledge of segment characteristics is not necessary; however, if the key expression uses the KEY(__linkFN,KNO=n,KEY=FLD1$:FLD2$) format where __linkFN is a special channel variable used by the system when evaluating the key, n is the key number used by the file, and FLD1$:FLD2$ are the key segment variables. The latter format is also more flexible as it can handle changes in key segment length if keys are updated for a file. In addition, this format allows a mixture of string and numeric segments.

Key Expression Builder

An easy way to build a key expression is to use the Key Expression utility, which is invoked by clicking the Tool button next to the Key Expression.

     ezkey

The key expression is built by specifying key segments to match the target key definition. These segments can consist of fields from the parent file, literal values and variables. Partial items can be defined, and segments can be padded, have characters stripped, or be converted to upper/lower case.

In the case of multi-segment keys, a Generate a KEY=F1$:F2$ expression check box option is available:

•

If it is not selected, the key segments will be concatenated, and individual key segments would have to be padded or manipulated appropriately.

•

If it is selected, then a key expression in the format KEY(__linkFN,KNO=n,KEY=FLD1$:FLD2$) will be generated where the segments need not be manipulated. (For an explanation of the contents of the generated key, see Multi-Segment Keys.)

Simple numeric keys can be built using a numeric field. Multi-segment numeric keys should be built using the Generate a KEY=F1$:F2$ expression option.

(The Generate a KEY=F1$:F2$ expression check box was added in PxPlus 2023.)
(The ability to define numeric keys and multi-segment keys for an EZLoad Multi-Line was added in PxPlus 2023 Update 1.)

Display Field

Select the field whose value will be displayed in the Multi-Line using the drop-down list of fields in the specified Lookup Table.

Additional Fields

(Available when Display Field is selected)

Button that invokes the EZ Load Additional Fields Definition dialog.

     

This dialog is used to specify additional Multi-Line controls on the same NOMADS panel that will be populated with data read from the selected Lookup Table using the same Key Expression.

For example, a Multi-Line for entering Product Codes is defined on a NOMADS panel. To display the Product Description when a Product Code is entered, a second Multi-Line can be defined with EZ Load functionality to read the Product table and retrieve that data. To display other fields, such as Price, Standard Cost and Quantity on Hand, from the same Product table record, additional Multi-Lines are created. Instead of defining these Multi-Lines with their own EZ Load definitions, they can be defined as EZ Load Additional Fields by associating them with the EZ Load definition on the Product Description Multi-Line. This allows other Multi-Lines on the same panel to use data from the same Lookup Table record, eliminating the need for multiple EZ Load definitions.

This dialog consists of the following:

File Information

Displays the selected Lookup Table and Display Field.

Screen Controls

Click the drop-down arrow for a list of existing Multi-Line controls on the current NOMADS panel. This list does not include the actual EZ Load Multi-Line since it has already been defined on the main EZ Load Multi-line Definition dialog.

Multi-Line controls that are not yet defined on the NOMADS panel may also be manually entered.

Field Expression

(Available when a Screen Control is entered)

Click the drop-down arrow for a list of fields from the selected Lookup Table. The Field Expression is usually the name of the field; however, it may also be any expression derived from constants and/or variables known at run time.

Delete Row(s)

Grid-side button used to delete any row(s) no longer required.

Auto Allocate

If the Multi-Lines on the NOMADS panel have been named to match the field names from the Lookup Table, use the Auto Allocate button to auto populate the grid.

Note:
Only controls and fields of the same type (numeric/string) will be matched by the Auto Allocate button.

OK

Saves the additional fields entered in the grid and returns to the EZ Load Multi-line Definition dialog. The Additional Fields button will display a check mark to indicate that additional fields have been defined. Any rows that do not have a Field Expression entered will not be saved.

Cancel

Exits the EZ Load Additional Fields Definition dialog without saving any changes.

(The Additional Fields button and EZ Load Additional Fields Definition dialog were added in PxPlus 2020.)

Trigger Variables and Controls

Trigger variables initiate the load logic. Any change in the value of a trigger variable will cause the EZ Load Multi-Line to be reloaded after the trigger control's On Change logic has been executed. (EZ Load-enabled controls are also loaded whenever a panel is drawn if the trigger variable has been populated.)

Variables

Enter the name of a variable from your PxPlus application. Click the Add Variable button to add the variable to the Selected Triggers list.

Controls

Lists all available controls in the current panel. Click the Add Control button to move a selected control to the Selected Triggers list.

Selected Triggers

Lists variables and controls currently selected to be used in the trigger criteria. To remove a selected item from this list, click the Remove button.

Note:
If no triggers have been selected, defining the Key Expression will automatically populate the Selected Triggers list with its associated variables.

Text to Display if Read Fails

Text to load into the Multi-Line when the load logic fails to retrieve data. Can be a Fixed value, string Expression or Message Library entry (see Message Library Maintenance).

If left blank, the default message Not on File (i.e. MSG("NOTONFILE")) will be displayed.

 

Note:
EZ Load Multi-Lines are intended for information as display only. Typically, this type of field might be used to look up and display a client name beside the input field where the client code is entered.

As display-only fields, it is common practice to turn Off the Tab Stop option and turn On the Locked and Borderless attributes for the Multi-Line.