Using parameters

Parameters are an essential part of any new link, report, or custom grid. Parameters determine how your item behaves and what data it includes.

Parameters have two uses:

  • Configuration
    Configuration parameters are pre-defined entries in the parameter list used to set up the item you are adding. Configuration parameters have a read-only Name field describing their purpose.

    Sample configuration parameter:

    image22

    The configuration parameters available vary based on the item type.

  • Pass data
    Data parameters send data to the item you are adding. That data can come from the host window or a custom expression. Custom expressions process and combine multiple values, including host window data and custom SQL queries. You can also assign the parameter a static value. Data parameters have a user-definable Name field.

    This illustration shows a sample data parameter.

    image38

Parameters in the Add New Item window

You set up both data and configuration parameters using the Parameters list.

image39

Each row in the parameter list contains these fields:

ID

A number identifying the parameter

Name

The parameter name

Note: The system automatically adds each parameter in your report with the correct parameter name when you select the report in the Command section.

Type

The source and data type of the parameter

Value

The value of the parameter

Configuring a new parameter

The steps you follow to create a new parameter vary based on the source of the parameter value. To set up a new parameter, see one of these sections:

Deleting a parameter

To delete a parameter:

  1. Select the parameter row in the Parameter list.

  2. Click Delete.
    The Delete Confirmation message opens.

  3. Click Yes to delete the parameter.

Passing a static value

When you set up a parameter with a static value, the system always passes the contents of the Value field. The value never changes unless you manually change the entry. Parameters with static values have the Type Text(String), Text(Number), or Text(Date). In the example below, the system will always pass the number value 1234.

image40

To set up a parameter with a static value:

  1. Do one of the following:

    • If you are adding a report:

      The system automatically adds any parameters in your report to the parameter list. Do not change the parameter ID or Name.

    • If you are adding a hyperlink, embedded webpage, or custom grid:

      1. Click Add or Insert beneath the Parameters list to add a new parameter row.

      2. Select a parameter ID.

      3. Enter a parameter Name. Parameter names should be one word. They should not have special characters.

  2. In the Type drop-down list, select one of these options:

    • Text(String) to pass either text or numbers

    • Text(Number) to pass a number

    • Text(Date) to pass a date

  3. Enter the value to pass in the Value field.

Passing the contents of a field from the host window

You can set up a parameter to pass the contents of a field from the host window, the window where you are adding the item. For example, imagine you are adding a report to the Trip Folder, and you want the report to show only information for the destination state for the open order.

image17

You need to bind the parameter value to that database field.

image41

When you open the report in LTL Operations, the system replaces Leg.EndState with the value of that field in the Trip Folder and passes that value to the report.

To configure a parameter to pass the contents of a field from the host window:

  1. Do one of the following:

    • If you are adding a report:

      The system automatically adds any parameters in your report to the parameter list. Do not change the parameter ID or Name.

    • If you are adding a hyperlink, embedded webpage, or custom grid:

      1. Click Add to add a new parameter row.

        Note: If you need to add a new parameter before an existing one, select the existing parameter and click Insert.

      2. Select a parameter ID.

      3. Enter a parameter Name. Parameter names should be one word and should not have special characters.

  2. In the Type drop-down list, select one of these options:

    • Bind(String) to pass either text or numbers

    • Bind(Number) to pass a number

    • Bind(Date) to pass a date

  3. Double-click the Value field.
    The Input Field Selector dialog box opens. The field groups and fields available in this dialog box depend on the host window.

    image42

  4. Select a field group and field. The field Type must match the parameter type selected in step 2.

  5. Click OK.
    The Value field now contains the database field name you chose.

Passing the results of an expression

If the information you want to pass using a parameter is not a single database field or requires some type of data processing, you can use an expression. Expressions allow you to write simple mathematical or logic operations. They also allow you to use variables to combine multiple data sources or query database data not located in the host window.

To set up a parameter to pass the results of an expression:

  1. Do one of the following:

    • If you are adding a report:

      The system automatically adds any parameters in your report to the parameter list. Do not change the parameter ID or Name.

    • If you are adding a hyperlink, embedded webpage, or custom grid:

      1. Click Add to add a new parameter row.

        Note: If you need to add a new parameter before an existing one, select the existing parameter and click Insert.

      2. Select a parameter ID.

      3. Enter a parameter Name. Parameter names should be one word. They should not have special characters.

  2. In the Type drop-down list, select one of these options:

    • Expression(String) to pass either text or numbers

    • Expression(Number) to pass a number

    • Expression(Date) to pass a date

  3. Enter an expression in the Value field.

    Note: For more information on expressions and variables, see Using variables.

Using variables

When you set up a parameter to pass the results of an expression, you can use variables to run SQL queries or perform additional processing on data. For example, you can use variables to combine values from multiple host window fields, or retrieve information directly from your database.

For more information on setting up a parameter to pass the results of an expression, see Passing the results of an expression.

Creating a variable is similar to creating a parameter. Like parameters, variables can pass static values, field values from the host window, and the results of expressions. Unlike parameters, variables can also pass the results of a SQL query. You can also use variables to process or combine values from multiple sources.

A variable’s value is passed using that variable’s name. Whenever you use the name of a variable in the Value field of another variable or parameter, the system replaces that name with the variable’s value. A simple example is shown below.

image43

The variable StaticNum has a value of 1234. Any time the system sees StaticNum in a value field, it will replace that value with 1234. Therefore, the value of the parameter RefNumber will become 1234.

Variables in the Add New Item window

You create and configure variables using the Variable section of the Add New Item window.

image44

Each row in the variable list has these fields:

ID

A number identifying the variable

Name

The variable name

Type

The source and data type of the variable.

Value

The value of the variable

In addition to the fields in the variable row, the Add New Item window has the Variable Value Expression field. This field mirrors the contents of the Value field for the currently selected variable. This larger field gives you more space to type your expression.

Creating and configuring a new variable

You create and configure a variable in the same way you configure a parameter:

  1. Click Add or Insert beneath the Variables list to add a new variable row.

  2. Select a variable ID.

  3. Enter a variable Name. Variable names must be one word and should not have special characters.

  4. Choose a variable type from the Type drop-down list.

  5. Depending on your choice in step 4, make one of these entries in the Value field or the Variable Value Expression field above the Variables list:

    Variable Type Required Entry

    Text(String)
    Text(Number)
    Text(Date)

    Enter a value matching the proper data type.

    SQL(String),
    SQL(Number)
    SQL(Date)

    Enter a SQL query that returns a single value matching the proper data type.

    Bind(String)
    Bind(Number)
    Bind(Date)

    Double-click the Value field and select the desired database field.

    Note: Variable binds work identically to parameter binds. For more information on binds, see Passing the contents of a field from the host window.

    Expression(String)
    Expression(Number)
    Expression(Date)

    Enter an expression.

This illustration shows a sample variable with a SQL(String) query.

image45