Calculation scales and calculation ranges

Many calculations in WebSphere Commerce involve looking up a value from a table. For example, a store has shipping charges based on the number of items shipped in an order. The table of shipping charges looks like this:

Example of a table for determining shipping charges
Number of items in order Shipping charge (local currency)
< 5 3.00
5 - 10 10.00
11 - 15 22.00
> 15 50.00

To calculate the shipping charge, a clerk counts the number of items in the order and uses the total number of items to find the shipping charge in the table.

WebSphere Commerce provides a similar function as part of the calculation framework, in the form of calculation scales. Think of calculation scales as two-column tables, where the values in the first column are compared with a known value to find a row in the table. The value in the second column is then applied to a calculation associated with the original known value.

The process of finding the value from the table is called a scale look-up. The calculation scale consists of a list of calculation ranges and associated look-up results. The known value that is compared to the calculation ranges is called a look-up number. For example, when calculating shipping charges using Example of a table used to determine shipping charges for an order that contains eight items, the look-up number is 8, the calculation range that the look-up number matches is 5 - 10, and the look-up result is 10.00.

A calculation scale can be used to calculate monetary amounts, one for each order item in a list. The default implementation of the CalculationRuleCalculate calculation method uses calculation scales. The amounts that are calculated are determined by the calculation ranges and range values of the calculation scale, and by the calculation methods they use. Calculation scales are associated with either a MonetaryCalculationScaleLookup or a QuantityCalculationScaleLookup calculation method. Calculation ranges are associated with a CalculationRange calculation method.

Calculation scale properties

Calculation scales have properties associated with them that affect when a calculation scale is applied and the monetary amounts calculated using a calculation scale. A calculation scale can have the following properties:

Currency

A calculation scale can be associated with a specific currency. Associating a calculation scale with a currency implies that all the calculation ranges in the scale are in that currency. A calculation scale that is associated with a currency applies to order items if the scale meets one of the following conditions:
  • The calculation scale and the order items have the same currency.
  • The currencies of the items can be converted to the calculation scale currency and no calculation scales with the same currency as the item exist. If multiple calculation scales for the same calculation usage with different currencies can be applied, the results of the scales are converted to the order item currency. The scale producing the lowest monetary amount in the order item currency is applied.

A calculation scale can be associated with a currency only, a unit of measurement only, or neither. A calculation scale cannot be associated with both a currency and a unit of measurement.

Unit of measurement

A calculation scale can be associated with a specific unit of measurement. Associating a calculation scale with a unit of measurement implies that all calculation ranges in the scale are in that unit of measurement.

An order item can have a unit of measurement associated with its quantity or weight. Various CalculationScaleLookup calculation methods use either the quantity or the weight of the item to determine look-up values. Look-up values are compared with calculation range start values to determine which CalculationRange calculation methods to call.

For CalculationScaleLookup calculation methods that use an item's quantity value, the unit of measurement of the quantity must be convertible to the unit of measurement for the calculation scale. For CalculationScaleLookup calculation methods that use an item's weight value, the unit of measurement of the weight must be convertible to the unit of measurement for the calculation scale. The units of measurement for quantity and weight of order items are specified in the CATENTSHIP database table, referenced by the CATENTRY_ID column of the OrderItem.

A unit of measurement is convertible to another unit of measurement if they are the same, or if there are conversions defined in the QTYCONVERT database table that would allow a conversion from the one to the other.

A calculation scale can be associated with a currency only, a unit of measurement only, or neither. A calculation scale cannot be associated with both a currency and a unit of measurement.

Calculation usage

A calculation usage defines the type of calculation to which the calculation scale applies. See Calculation usages.

WebSphere Commerce requires each calculation scale to have a calculation usage.

In addition to these properties, calculation scales are classified by the CalculationScaleLookup calculation method that is associated with the calculation scale:

Monetary calculation scale

A monetary calculation scale is a calculation scale that is associated with MonetaryCalculationScaleLookup.

Quantity calculation scale

A quantity calculation scale is a calculation scale that is associated with QuantityCalculationScaleLookup.

 

Calculation range properties

Calculation ranges have properties that affect how the values in calculation rules are used. A calculation range can have the following property:

Cumulative

If the calculation ranges for a calculation scale are cumulative, the resulting total monetary amount for the calculation scale is calculated using the look-up results for all calculation ranges that match or are less than the look-up number. The resulting monetary amount depends on the CalculationRange calculation method used by the calculation range.

Also, the look-up number used to calculate the monetary amount for each calculation range changes for each calculation range. This modified look-up number is called the applicable part of the look-up number.

For example, consider the following weight-based calculation scale:

Weight-based calculation scale
Shipping weight Charge
greater than or equal to 0kg 2.00 fixed charge
greater than or equal to 5kg 0.25 per kg
greater than or equal to 10kg 0.10 per kg
greater than or equal to 100kg 0.01 per kg

The total shipping charge for a 20kg package, assuming cumulative calculation ranges, will be determined using a number of calculation ranges. The look-up number is 20, but the applicable part of the look-up number will change as the total shipping cost is calculated. The applicable part of the look-up number is calculated using the following formula:

min(lookupNumber, rangeEnd) - rangeStart

The following table shows the applicable parts of the look-up number used:

Applicable parts of look-up numbers
Look-up number Range starting value Range ending value Applicable part of the look-up number
20 0 5 5
20 5 10 5
20 10 100 10

The applicable parts of the look-up number are used to determine the total shipping cost as follows:

  1. The look-up number (20) matches the first range. The monetary result is the look-up result applying to the applicable part of the look-up number (5). The total shipping charge is 2.00.
  2. The look-up number (20) matches the second range. The monetary result (0.25) is the look-up result applying to the applicable part of the look-up number (5). The resulting shipping charge is 1.25. Because the calculation range is cumulative, this amount is added to the existing shipping charges. The total shipping charge is now 3.25.
  3. The look-up number (20) matches the third range. The monetary result (0.10) is the look-up result applying to the applicable part of the look-up number (10). The resulting shipping charge is 1.00. Because the calculation range is cumulative, this amount is added to the existing shipping charges. The total shipping charge is now 4.25.
  4. The look-up number (20) does not match the fourth range. The calculation is complete. The total shipping charge is 4.25.

If the calculation ranges are non-cumulative, the applicable part of the look-up number and the look-up number are the same. The shipping charges would be determined as follows:

  1. The look-up number (20) matches the first range. The monetary result is the look-up result applying to the applicable part of the look-up number (20). The total shipping charge is 2.00.
  2. The look-up number (20) matches the second range. The monetary result (0.25) is the look-up result applying to the applicable part of the look-up number (20). The resulting shipping charge is 5.00. Because the calculation range is non-cumulative, this amount replaces the existing shipping charges. The total shipping charge is now 5.00.
  3. The look-up number (20) matches the third range. The monetary result (0.10) is the look-up result applying to the applicable part of the look-up number (20). The resulting shipping charge is 2.00. Because the calculation range is non-cumulative, this amount replaces the existing shipping charges. The total shipping charge is now 2.00.
  4. The look-up number (20) does not match the fourth range. The calculation is complete. The total shipping charge is 2.00.

 

Database tables for calculation scales and calculation ranges

Information about a calculation scale and the calculation ranges that make up the scale is separated into different tables. The following WebSphere Commerce database tables define calculation scales and calculation ranges:

CALSCALE

Defines calculation scales.

CALSCALEDS

Contains national language descriptions of a calculation scale. This allows one calculation scale to have descriptions in multiple languages.

CRULESCALE

Relates a calculation scale to a calculation rule. A calculation rule can have multiple calculation scales and a calculation scale can be used by multiple calculation rules.

CALRANGE

Defines the calculation ranges that make up a calculation scale.

CALRLOOKUP

Contains the look-up results for calculation ranges. The currencies of the look-up results, optional attributes, are also specified in this database table.

Calculation scale and calculation range data model diagram

The following data model diagram illustrates the relationships between the database tables for defining calculation scales and calculation ranges.

 

Calculation methods for calculation scales

Three subclasses of calculation methods are associated with calculation scales:

A QuantityCalculationScaleLookup applies to quantity calculation scales, while a MonetaryCalculationScaleLookup applies to monetary calculation scales.

CalculationScaleLookup calculation methods

The MonetaryCalculationScaleLookup and QuantityCalculationScaleLookup calculation methods determine a number of values required to perform a range look-up and calculate any monetary amounts using the look-up result. The calculation methods use a set of order items, a calculation rule, and a calculation scale passed to them by the CalculationRuleCalculate calculation method to determine the following items:

Base monetary value

An amount that the CalculationRange calculation method can use to calculate a monetary amount.

Look-up number

The value compared to the ranges in the calculation scale to find a look-up result.

Mathematical weights

The mathematical weights are values that are used to distribute the total calculated monetary amount using a calculation scale to each of the order items in the set that is passed to the CalculationScaleLookup calculation method. The CalculationScaleLookup calculation method returns one mathematical weight for each item in the set.

The total monetary amount is distributed according to the percentage of the total mathematical weight that one order item's mathematical weight represents. If an order item's mathematical weight represents 23% of the total mathematical weight of the items being processed, the item's monetary amount is 23% of the total monetary amount determined for the calculation scale.

For example, assume that monetary amounts for three OrderItems (ItemA, ItemB, and ItemC) are being determined and the total monetary amount determined for the calculation scale is $156. The following table shows how mathematical weights distribute the total monetary amount across the OrderItems:

Example of distributing total monetary amount using mathematical weights
OrderItem Mathematical weight Percentage of total mathematical weights Calculation OrderItem monetary amount
ItemA 9 18% $156*0.18 $28.08
ItemB 25 50% $156*0.50 $78.00
ItemC 16 32% $156*0.32 $49.92

Result multiplier

The result multiplier specifies the value by which the resulting monetary value should be multiplied to calculate a monetary amount for the set of OrderItems.

Note: Different implementations of the MonetaryCalculationScaleLookup or QuantityCalculationScaleLookup calculation methods will give different results for these items when using the same sets of OrderItems.

MonetaryCalculationScaleLookup and QuantityCalculationScaleLookup calculation methods return the base monetary value, the look-up number, the set of mathematical weights and the set of result multipliers to the CalculationRuleCalculate calculation method. CalculationRuleCalculate then finds the calculation range look-up result corresponding to the look-up value and passes the applicable part of the look-up result to CalculationRange. The applicable part of the look-up result depends on whether the calculation range is cumulative. CalculationRange returns a monetary amount. The returned monetary amount is then distributed among the set of OrderItems according to the mathematical weights calculated for each order item.

For more information, see CalculationRange calculation method.

The following section discusses the CalculationScaleLookup and CalculationRange calculation methods and the default implementations provided with WebSphere Commerce. Additional information about the interfaces and commands that implement the subclasses of the calculation methods can be found in the API documentation of the online information.

MonetaryCalculationScaleLookup calculation methods

For MonetaryCalculationScaleLookup calculation methods, the look-up number and base monetary values that are determined by the method are both monetary amounts. The amounts for determining the look-up number and base monetary values are different depending on the implementation of the look-up method for the monetary calculation scale. Here are some values that are commonly used in the calculation framework:

Net price

The value for net price is the unit price of the order item (ORDERITEMS.PRICE) multiplied by the quantity (ORDERITEMS.QUANTITY) plus the sum of all adjustments associated with the item.

Non-discounted price

The value for non-discounted price is the unit price of the order item (ORDERITEMS.PRICE) multiplied by the quantity (ORDERITEMS.QUANTITY).

Taxable net price

The value for taxable net price that is used for a particular tax category is the non-discounted price plus the sum of all order item adjustments subject to taxation for the category. The value of taxable net price might be different for each tax category since different items and adjustments might be subject to different categories.

Taxable unit price

The value for taxable unit price that is used for a particular tax category is the taxable net price of the order item divided by the quantity (ORDERITEMS.QUANTITY). The per-unit taxable adjustment is the total of all order item adjustments subject to taxation for the tax category and divided by the quantity (ORDERITEMS.QUANTITY).

Unit price

The value for unit price is the per-unit price of an OrderItem (ORDERITEMS.PRICE) plus the per-unit adjustment for the OrderItem. The per unit adjustment is the total of all order item adjustments divided by the quantity (ORDERITEMS.QUANTITY).

MonetaryCalculationScaleLookup calculation methods must extend the CalculationScaleLookupCmd interface. For more information see the CalculationScaleLookupCmd interface.

The following MonetaryCalculationScaleLookup calculation methods are provided with WebSphere Commerce:

NetPriceCalculationScaleLookupCmdImpl

This command is suitable for calculating discounts or shipping scales based on a discounted price.

The values calculated by this command are as follows:

Base monetary value

The sum of net prices of the OrderItems

Look-up number

The sum of net prices of the OrderItems

Mathematical weights

The net price of each OrderItem

Result multiplier

One

The look-up number is converted to the currency of the calculation scale. If no conversion is possible, this calculation method returns null.

For the look-up number to be converted to the currency of the calculation scale, the conversion from the calculation scale currency to the order currency must be defined in WebSphere Commerce.

NetShippingCalculationScaleLookupCmdImpl

This command is suitable for calculating tax scales on shipping charges.

The values calculated by this command are as follows:

Base monetary value

The sum of all the shipping charges for the OrderItems (ORDERITEMS.SHIPCHARGE)

Look-up number

The sum of all the shipping charges for the OrderItems (ORDERITEMS.SHIPCHARGE)

Mathematical weights

The shipping charge for each OrderItem

Result multiplier

One

The look-up number is converted to the currency of the calculation scale. If no conversion is possible, this calculation method returns null.

For the look-up number to be converted to the currency of the calculation scale, the conversion from the calculation scale currency to the order currency must be defined in WebSphere Commerce.

NonDiscountedPriceCalculationScaleLookupCmdImpl

This command is suitable for shipping scales and some kinds of discounts. For example, if a percentage discount is based on the non-discounted price of an item, two successive 10% discounts would give the customer a total 20% discount. If the discount is based on the net price of an item, two successive 10% discounts would give the customer a total 19% discount, because the second discount is based on the price of the item minus the first discount (or 90% of the original non-discounted price).

The values calculated by this command are as follows:

Base monetary value

The sum of the non-discounted prices of OrderItems

Look-up number

The sum of the non-discounted prices of OrderItems

Mathematical weights

The non-discounted price of each OrderItem

Result multiplier

One

The look-up number is converted to the currency of the calculation scale. If no conversion is possible, this calculation method returns null.

For the look-up number to be converted to the currency of the calculation scale, the conversion from the calculation scale currency to the order currency must be defined in WebSphere Commerce.

TaxableNetPriceCalculationScaleLookupCmdImpl

This command is suitable for sales tax scales.

The values calculated by this command are as follows:

Base monetary value

The sum of the taxable net prices of OrderItems

Look-up number

The sum of the taxable net prices of OrderItems

Mathematical weights

The taxable net price of each OrderItem

Result multiplier

One

The look-up number is converted to the currency of the calculation scale. If no conversion is possible, this calculation method returns null.

For the look-up number to be converted to the currency of the calculation scale, the conversion from the calculation scale currency to the order currency must be defined in WebSphere Commerce.

TaxableNetPriceTaxOnTaxCalculationScaleLookupCmdImpl

This command is suitable for sales tax scales.

The values calculated by this command are as follows:

Base monetary value

The sum of the taxable net prices of OrderItems, plus the tax amounts already applied to the OrderItems.

Look-up number

The sum of the taxable net prices of OrderItems.

Mathematical weights

The taxable net price of each OrderItem.

Result multiplier

One

The look-up number is converted to the currency of the calculation scale. If no conversion is possible, this calculation method returns null.

For the look-up number to be converted to the currency of the calculation scale, the conversion from the calculation scale currency to the order currency must be defined in WebSphere Commerce.

TaxableNetPricePlusNetShippingCalculationScaleLookupCmdImpl

This command is suitable for combined sales and shipping tax scales.

The values calculated by this command are as follows:

Base monetary value

The sum of the taxable net prices plus the sum of all the shipping charges for the OrderItems (ORDERITEMS.SHIPCHARGE)

Look-up number

The sum of the taxable net prices plus the sum of all the shipping charges for the OrderItems (ORDERITEMS.SHIPCHARGE)

Mathematical weights

The taxable net price for each OrderItem plus the shipping charge for each OrderItem divided by the OrderItem quantity (ORDERITEMS.QUANTITY)

Result multiplier

One

The look-up number is converted to the currency of the calculation scale. If no conversion is possible, this calculation method returns null.

For the look-up number to be converted to the currency of the calculation scale, the conversion from the calculation scale currency to the order currency must be defined in WebSphere Commerce.

TaxableUnitPriceCalculationScaleLookupCmdImpl

This command is suitable for per-item sales tax scales, especially where a maximum tax per item is specified. You should use this command only when order items are grouped by offer. Grouping is determined by the grouping method attribute of the calculation code.

The values calculated by this command are as follows:

Base monetary value

The sum of taxable net prices divided by the sum of OrderItem quantities

Look-up number

The sum of taxable net prices divided by the sum of OrderItem quantities

Mathematical weights

The taxable unit price for each OrderItem

Result multiplier

The sum of the OrderItem quantities

The look-up number is converted to the currency of the calculation scale. If no conversion is possible, this calculation method returns null.

For the look-up number to be converted to the currency of the calculation scale, the conversion from the calculation scale currency to the order currency must be defined in WebSphere Commerce.

TaxableUnitPricePlusUnitShippingCalculationScaleLookupCmdImpl

This command is suitable for per-item combined sales and shipping tax scales, especially where a maximum tax per item is specified. You should use this command only when order items are grouped by offer. Grouping is determined by the grouping method attribute of the calculation code.

The values calculated by this command are as follows:

Base monetary value

The sum of taxable net prices plus the sum of all the shipping charges for the OrderItems, divided by the sum of the OrderItem quantities

Look-up number

The sum of taxable net prices for the OrderItems, divided by the sum of the OrderItem quantities

Mathematical weights

The taxable net prices plus the charges, divided by the OrderItem quantity (ORDERITEMS.QUANTITY), for each OrderItem

Result multiplier

The sum of the OrderItem quantities

The look-up number is converted to the currency of the calculation scale. If no conversion is possible, this calculation method returns null.

For the look-up number to be converted to the currency of the calculation scale, the conversion from the calculation scale currency to the order currency must be defined in WebSphere Commerce.

UnitPriceCalculationScaleLookupCmdImpl

This command is appropriate for discount or shipping scales that specify a fixed or maximum charge per item based on the unit price of each item. Use this command only when items are grouped by offer. Grouping is determined by the grouping method attribute of the calculation code.

The values calculated by this command are as follows:

Base monetary value

The sum of net prices divided by the sum of OrderItem quantities

Look-up number

The sum of net prices divided by the sum of OrderItem quantities

Mathematical weights

The net price divided by the OrderItem quantity (ORDERITEMS.QUANTITY), for each OrderItem

Result multiplier

The sum of the OrderItem quantities

The look-up number is converted to the currency of the calculation scale. If no conversion is possible, this calculation method returns null.

For the look-up number to be converted to the currency of the calculation scale, the conversion from the calculation scale currency to the order currency must be defined in WebSphere Commerce.

UnitShippingCalculationScaleLookupCmdImpl

This command is appropriate for per item shipping tax scales, especially where a maximum tax per item may be specified.

The values calculated by this command are as follows:

Base monetary value

The sum of shipping charges for the OrderItems divided by sum of the OrderItem quantities

Look-up number

The sum of shipping charges for the OrderItems divided by sum of the OrderItem quantities

Mathematical weights

The shipping charges divided by the OrderItem quantity (ORDERITEMS.QUANTITY), for each OrderItem

Result multiplier

The sum of the OrderItem quantities

The look-up number is converted to the currency of the calculation scale. If no conversion is possible, this calculation method returns null.

For the look-up number to be converted to the currency of the calculation scale, the conversion from the calculation scale currency to the order currency must be defined in WebSphere Commerce.

QuantityCalculationScaleLookup calculation methods

For QuantityCalculationScaleLookup calculation methods, the look-up number is a value that may or may not have an associated unit of measurement. Here are some common values that are used in the calculation framework:

Actual quantity

The actual quantity of an OrderItem is the OrderItem quantity (ORDERITEMS.QUANTITY) multiplied by the nominal quantity of the item (CATENTSHIP.NOMINALQUANTITY).

Net price

The value for net price is the unit price of the OrderItem (ORDERITEMS.PRICE) multiplied by the quantity of the OrderItem (ORDERITEMS.QUANTITY) plus the sum of all adjustments associated with the OrderItem.

The QuantityCalculationScaleLookup calculation methods are provided with WebSphere Commerce

QuantityCalculationScaleLookupCmdImpl

This command is suitable for shipping scales.

If the calculation scale has a unit of measurement associated with it, the values calculated are as follows:

Base monetary value

The sum of the net prices of the OrderItems

Look-up number

The sum of the actual quantities of the OrderItems, converted to the unit of measurement of the calculation scale

If no conversion is possible, the calculation scale is not used by the calling calculation rule.

Mathematical weights

The actual quantity of each OrderItem

Result multiplier

One

If the calculation scale is not associated with a unit of measurement, the values calculated are as follows:

Base monetary value

The sum of the net prices of the OrderItems

Look-up number

The sum of the OrderItem quantities (ORDERITEMS.QUANTITY)

Mathematical weights

The OrderItem quantity (ORDERITEMS.QUANTITY) of each OrderItem

Result multiplier

One

QuantitySpreadByNetPriceCalculationScaleLookupCmdImpl

This command is suitable for discount and shipping scales.

If the calculation scale has a unit of measurement associated with it, the values calculated are as follows:

Base monetary value

The sum of the net prices of the OrderItems

Look-up number

The sum of actual quantities of the OrderItems, converted to the unit of measurement of the calculation scale.

If no conversion is possible, the calculation scale is not used by the calling calculation rule.

Mathematical weights

The net price of each OrderItem

Result multiplier

One

If the calculation scale is not associated with a unit of measurement, the values calculated are as follows:

Base monetary value

The sum of the net prices of the OrderItems

Look-up number

The sum of OrderItem quantities (ORDERITEMS.QUANTITY)

Mathematical weights

The net price of each OrderItem

Result multiplier

One

WeightCalculationScaleLookupCmdImpl

This command is suitable for discount and shipping scales.

The values calculated by this command are as follows:

Base monetary value

The sum of net prices of the OrderItems

Look-up number

The sum of the shipping weights (CATENTSHIP.WEIGHT) multiplied by quantity (ORDERITEMS.QUANTITY) of the OrderItems. The total is converted to the unit of measure of the calculation scale.

Mathematical weights

The shipping weight (CATENTSHIP.WEIGHT) multiplied by the quantity (ORDERITEMS.QUANTITY) of each OrderItem

Result multiplier

One

WeightSpreadByNetPriceCalculationScaleLookupCmdImpl

The values calculated by this command are as follows:

Base monetary value

The sum of net prices of the OrderItems

Look-up number

The sum of the shipping weight (CATENTSHIP.WEIGHT) multiplied by quantity (ORDERITEMS.QUANTITY) of the OrderItems

Mathematical weights

The net price of each of item

Result multiplier

One

CalculationRange calculation method

The CalculationRange calculation method calculates a monetary amount for a particular calculation range. The CalculationRuleCalculate calculation method calls the CalculationRange calculation method and passes it the following parameters:

Currency

This is the order currency. The returned monetary amount will be in this currency.

Calculation range look-up result

This is the value obtained from the CALRLOOKUP database table using the look-up number.

Applicable part of the look-up number

This number is based on the look-up number determined by the CalculationScaleLookup calculation method. The applicable part of the look-up number can be determined as follows:

Non-cumulative calculation ranges:

The applicable part of the look-up number is the same as the look-up number.

Cumulative calculation ranges:

The applicable part of the look-up number is determined by the following formula: 
min(lookupNumber, rangeEnd) - rangeStart
Where:

lookupNumber

The look-up number determined by CalculationScaleLookup calculation method.

rangeEnd

The rangeStart attribute (CALRANGE.RANGESTART) of the next calculation range in the list of calculation ranges to be processed. If there are no more calculation ranges to be processed, rangeEnd is infinity.

rangeStart

The rangeStart attribute (CALRANGE.RANGESTART) of the calculation range currently being processed.

Applicable base monetary value

This number is based on the base monetary value determined by the CalculationScaleLookup calculation method. The applicable base monetary value is determined as follows:

Non-cumulative calculation ranges:

The applicable base monetary value is the same as the base monetary value.

Cumulative calculation ranges:

The applicable base monetary value is determined by the following formula: 
min(baseMonetaryValue, rangeEnd*unitValue) - rangeStart*unitValue
Where:

baseMonetaryValue

The base monetary value determined by the CalculationScaleLookup calculation method.

rangeEnd

The rangeStart attribute (CALRANGE.RANGESTART) of the next calculation range in the list of calculation ranges to be processed. If there are no more calculation ranges to be processed, rangeEnd is infinity.

rangeStart

The rangeStart attribute (CALRANGE.RANGESTART) of the calculation range currently being processed.

unitValue

The base monetary value divided by look-up number. The base monetary value and look-up number are determined by the CalculationScaleLookup calculation method.

PercentageCalculationRangeCmdImpl

This command expects the calculation range look-up result that is not a monetary amount. If the calculation range look-up result has a currency, the currency is ignored. This CalculationRange calculation method calculates a monetary amount by dividing the calculation range look-up result by 100 and multiplying the result by the applicable base monetary value.

PerUnitAmountCalculationRangeCmdImpl

This command expects the calculation range look-up result to be a monetary amount. If the monetary amount is not in the specified currency, this command converts the look-up result to the specified currency (if the currency conversion is defined). Otherwise, this calculation range method calculates a monetary amount by multiplying the range look-up result by the applicable part of the look-up number.

FixedAmountCalculationRangeCmdImpl

This command expects the calculation range look-up result to be a monetary amount. If the monetary amount is not in the specified currency, this command converts the look-up result to the specified currency (if the currency conversion is defined). The range look-up result is returned as the monetary amount and no other calculations are performed by this command.

How calculation scales and calculation ranges are used

Calculation scales and calculation ranges are used by CalculationRuleCalculate calculation methods to determine a monetary amount for each order item in a list. The default implementation of CalculationRuleCalculate performs the following steps to obtain monetary amounts using calculation scales and calculation rules:

  1. Sets the calculated monetary amounts for each OrderItem to zero.
  2. Sets the total monetary amount for the calculation scale to zero.
  3. Passes the CalculationScaleLookup calculation method a list of OrderItems. The CalculationScaleLookup calculation method returns the following values:
    • A look-up number
    • A base monetary value
    • A result multiplier
    • A set of mathematical weights, one for each OrderItem
    These values depend on the CalculationScaleLookup method being called.
  4. Finds calculation ranges that match the look-up number. The CalculationRuleCalculate calculation method determines which calculation scales are used to determine the calculation ranges.

    A calculation range matches a look-up number that is greater than or equal to the starting value of the range (CALRANGE.RANGESTART). If the starting value of a calculation range is not defined, the calculation range always matches the look-up number.

    Calculation ranges are found by using the look-up number to locate ranges in the CALRANGE database table. The IDs of the calculation ranges are used later to find look-up results.

  5. Sorts the calculation ranges in ascending sequence, by the starting value of the ranges.
  6. Processes each calculation range by performing the following steps:
    1. Obtains calculation range look-up results for the calculation range if the look-up number is greater than or equal to the starting value of the calculation range being processed and one of the following conditions is met:
      • This is the last calculation range being processed.
      • The look-up number is less than the starting value of the next calculation range to be processed.
      • The calculation range is cumulative.
      Multiple calculation range look-up results are permitted only when the calculation range look-up results are associated with currencies. The behavior when multiple calculation range look-up results are found and they are not associated with currencies is undefined. Such configurations are discouraged.

      Calculation range look-up results are obtained by using the calculation range ID to locate look-up results in the CALRLOOKUP database table.

      All calculation range look-up results should be either associated or not associated with a currency. The behavior when some calculation range look-up results are associated with a currency and some are not is undefined. Such configurations are discouraged.

    2. Obtains one monetary amount for look-up results for calculation ranges by doing one of the following things:
    3. Multiplies the monetary amount obtained by the result multiplier and does one of the following things with the resulting value:

      Non-cumulative calculation ranges:

      Replaces the current total monetary amount for the calculation scale with the resulting value.

      Cumulative calculation ranges:

      Adds the resulting value to the total monetary amount for the calculation scale.
  7. Spreads the total monetary amount for the calculation scale over the order items in proportion to the mathematical weight assigned to each item.

Processing look-up results associated with currencies

When a calculation range has multiple look-up results in multiple currencies, there are two possible situations:

  1. The list of currencies in the result contains the order currency.
  2. The list of currencies in the result does not contain the order currency

Look-up result currencies contain the order currency

There should be only one calculation range look-up result with a currency that matches the order currency. If multiple calculation range look-up results share the order currency, an exception is thrown.

The calculation range look-up result is processed by calling a CalculationRange calculation method to obtain a monetary amount. For more information, see Calling a CalculationRange calculation method.

Look-up result currencies do not contain the order currency

If none of the currencies of the look-up results matches the order currency, the monetary amounts for the look-up results are obtained by performing the following steps:

  1. Convert the look-up results to the order currency. If no conversion from the look-up result currency to the order currency is defined in WebSphere Commerce, the look-up result is dropped from the list of look-up results to be processed.
  2. For each of the converted look-up results, a CalculationRange calculation method is called to obtain a monetary amount for each of the converted look-up results. For more information, see Calling a CalculationRange calculation method.
  3. Compare the monetary amounts for each of the look-up results. The lowest value is considered the valid monetary amount.

Processing look-up results not associated with currencies

If the calculation range look-up results are not associated with a currency, only one look-up result should be found. If multiple look-up results are found that are not associated with currencies, an exception is thrown.

The calculation range look-up result is processed by calling a CalculationRange calculation method to obtain a monetary amount. For more information, see Calling a CalculationRange calculation method.

Calling a CalculationRange calculation method

To obtain a monetary amount from a CalculationRange calculation method, call a CalculationRange calculation method, passing it the following parameters:

The value of the monetary amount depends on the CalculationRange calculation method called. For information about the different CalculationRange calculation methods provided with WebSphere Commerce and definitions of the parameters required by CalculationRange calculation methods, see CalculationRange calculation method.

Related concepts

(C) Copyright IBM Corporation 1996, 2006. All Rights Reserved.