RETRIEVE command

Retrieve a value stored in the Control Totals Database using the RETRIEVE command.

To retrieve a value from the Control Totals Database, you must know the name of the Control Totals Field (for example, CDB_SALESTOT) where the value was stored, the value’s identifying key, all other identifying information (such as task for which Control Total Variable was stored and the cycle), and you must assign the retrieved value to a variable within the rule procedure.

You can also specify certain options such as how to determine the cycle for which you want to retrieve the data and how A&AS should behave if no value is found. Refer to the OPTIONS (GENLEVEL and NO_VALUE) topic for more information.

If you have stored a variable without specifying the Control Totals Field, then you should specify the same variable name to retrieve the value from the Control Totals Database.

For example, assume that your cycles (defined at the application level) increment monthly, and you want to retrieve last month’s sales totals and assign them to the PREV_MO_SALESTOT variable in your rule procedure. These sales totals were stored in the SALESTOT variable when the Task MonthlyTotals was executed last month with the fields shown in the STORE command topic.

The definition of your RETRIEVE command in the rule procedure would contain the following information:

Screen Label

Value

Comment

Retrieves last month’s sales total from the Control Total Database field, CDB_SALESTOT for the region and office referenced by the REG_OFF key. Assigns this value to PREV_MO_SALESTOT.

Task

/ApplicationName/MonthlyTotals
Variable PREV_MO_SALESTOT
Control Totals Field CDB_SALESTOT
Advanced Options

With the following options selected, and values specified as indicated:

  • Cycle Relative: -1
  • NO_VALUE: ZERO
  • GENLEVEL: Application
Key Fields REG_OFF
RETRIEVE Command

To define a RETRIEVE command that retrieves a previously stored Control Total from the Control Totals Database

  1. In the Rule Procedure page, drag and drop the RETRIEVE command to the Working Canvas.
  2. Optionally, in the Comment text box, enter any descriptive comments you want to include for the rule procedure you are defining.
  3. In the Task drop-down, choose any one of the following:
    1. Select the name of the Task under which the Control Total was originally stored.
    2. Enter a new Task if you are defining a RETRIEVE command to retrieve data from a Task that has not yet been created but which will be created before the current rule procedure is run.
  4. From the Control Totals Field drop-down, perform any one of the following steps:
    1. Select the Control Total Database variable name that was assigned for this value when it was originally stored.
    2. Enter a new value if you are defining a RETRIEVE command to retrieve a Control Totals Database value that has not yet been stored, but which will be stored before the current rule procedure is run.
  5. From the Variable drop-down, select the name of the variable to which you want to assign the value you retrieve.
  6. Click Show Advanced Options and in the Cycle section, select one of the following options to specify the cycle or run from which you want to retrieve data. See the Managing Cycles section for more information on absolute and relative behavior.

    • Select the Absolute radio button, if you want to specify a particular cycle value. Enter the absolute cycle value in the associated field.

    • Select the Relative radio button, if you want to specify a cycle before the current cycle. Then, from the drop-down, select the appropriate relative cycle value, where -1 is one cycle before, -2 is two cycles before, and so on.

    • Select the Retrieve From This Run Only radio button, if you want to restrict retrieval to data stored by the current run. If the current run did not store a value in a given variable, but previous runs did. This setting prevents the rule procedure from substituting a value stored in a previous run.

  7. If you selected the Relative option, you could use the GENLEVEL option to specify the level at which the rule procedure searches for the cycle value as follows. If you do not use the GENLEVEL option, A&AS resolves the cycle number at the application level by default.
    1. In the Use Options section, select GENLEVEL .
    2. From the associated drop-down list, select FIELD, SOURCE, APPLICATION, LASTRUN to specify the level at which the rule procedure should search for a value for the cycle.
  8. Regardless of how it locates the cycle (Relative, Absolute, or Retrieve From This Run Only), the RETRIEVE command may find no value stored where it expects to find one. When this happens, the RETRIEVE command returns the text string ERROR by default, but you can change it to a numeric 0 as follows:
    1. In the Use Options area, select the NO_VALUE option.
    2. In the NO_VALUE drop-down list, select ZERO.
  9. In the Key Fields drop-down, for each key field listed under the Name column for which more than one variable appears under the Value column, select the variable whose value you need to retrieve the correct Control Total.

    If the key fields are known, A&AS automatically displays them in the Key Field stable. If no field name values are listed because you are defining a RETRIEVE command to retrieve a Control Total that has not yet been stored, and if this Control Total will be stored before the current rule procedure is run, then you should add the key fields that will be defined for this Control Total, and enter their appropriate values.

  10. Click OK.

The RETRIEVE command appears with the definition you specified in the list of rule procedure commands in the Working Canvas of the Rule Editor.