4.1 WFS_CMD_CDM_DENOMINATE

Description This command, which is designed to support denomination dialogues, will provide a denomination, i.e., a mix of bills and/or coins, capable of being paid out according to the amount (in terms of the minimum dispense unit) and currency specified, the mix algorithm selected and the desired denomination. In addition to that, it provides a facility for checking any given denomination for its capability of being paid out.

For the denomination of a specified amount the money can be retrieved from three different sources:

the cash dispenser
the coin dispenser (see WFS_INF_CDM_CAPABILITIES)
the teller's cash box (see WFS_INF_CDM_CAPABILITIES)

The configuration specifies which of these three sources are allowed to be used in the denomination. For a ATS all three can be used. If the device used is an ATM, only the cash dispenser and, optionally, the coin dispenser can be available.

For the cash dispenser module there is a parameter (wMaxBills in the WFS_INF_CDM_CAPABILITIES command) controlling the maximum number of bills or documents that can be paid out within a single dispensing command. The coin dispenser has a parameter (wMaxCoins in the WFS_INF_CDM_CAPABILITIES command) specifying the maximum number of coins that can be paid out.

Existing variants for dispensing of bills or documents are:

House mix tables (denomination tables), defined in the configuration
Denomination algorithms, such as balanced use of the different cash units, use of bills with highest possible values, etc.

There are four distinct combinations of the inputs to this command:

Input parameters are currency and denomination, with mix number WFS_CDM_INDIVIDUAL and amount equal to zero. In this case the service checks only whether the denomination is valid according to the counters and the states of the cash units.
Input parameters are currency, amount and denomination, with mix number WFS_CDM_INDIVIDUAL. The service checks amount and denomination and returns amount, currency and denomination, if the denomination specified is OK.
Input parameters are currency, amount and mix number. The denomination is performed depending on the specified amount and mix number, and the configuration (coin dispenser and/or cash box; see WFS_INF_CDM_CAPABILITIES). The service returns the values for amount, currency and denomination (given the general capability to pay out the amount specified; see above).

If, for example, the amount of Ł34.00 has been chosen, the CDM service will try to separate the required coins (up to the configured maximum value) using a coin dispenser. If no coin dispenser is available, the separated amount is assigned to sources other than the CDM (such as the teller's cash box). An ATM (having no cash box) raises an error indicating that this amount cannot be denominated.

If, for example, there are no more Ł10.00 bills in the CDM (cash unit minimum has been reached), it performs payments using bills denominating Ł20.00 while the remaining Ł10.00 will have to be paid out from the cash box, if present.

Input parameters are currency, amount and mix number, where the desired denomination is partly defined or a minimum amount for the cashbox is specified. In these cases the partly specified denomination is completed; the cashbox amount may be updated and returned together with the amount and the desired currency.

The following errors can occur:

If the denomination specified requires the selection of a locked cash unit, the CDM service returns the error WFS_ERR_CDM_CASHUNITERROR.
If the sum total of the denomination is greater than the amount specified (exception: amount is zero), the CDM service returns the error WFS_ERR_CDM_INVALIDDENOMINATION.
If the amount specified cannot be dispensed, either because a bill value or coin type is not in the machine, the difference is requested from the teller's cash box. If the device is an ATM, there is no cash box and the error WFS_ERR_CDM_NOTDISPENSABLE is returned.
If no coin dispenser is in the unit and a coin amount is specified, a WFS_ERR_CDM_CASHUNITERROR error is returned.
If the desired denomination refers to cash units containing different currencies, the CDM-service returns the error WFS_ERR_CDM_NOCURRENCYMIX. A cash unit with a currency type indicating a coupon or non-cash item can be mixed with other currencies.
If the currency specified is not configured for the service, a WFS_ERR_CDM_INVALIDCURRENCY error is returned.

Input Param LPWFSCDMDENOMINATE lpDenominate;

typedef struct _wfs_cdm_denominate
 {
 USHORT      usTellerID;
 USHORT      usMixNumber;
 LPWFSCDMDENOMINATION lpDenomination;
 } WFSCDMDENOMINATE, * LPWFSCDMDENOMINATE;

usTellerID
Identification of teller.

usMixNumber
Mix algorithm or house mix table to be used. If the value is WFS_CDM_INDIVIDUAL, the service does not calculate an alternative denomination.

lpDenomination
Pointer to a WFSCDMDENOMINATION structure, describing the contents of the denomination operation.

typedef struct _wfs_cdm_denomination
 {
 CHAR   cCurrencyID[3];
 ULONG   ulAmount;
 USHORT   usCount;
 LPULONG  lpulValues;
 ULONG   ulCashBox;
 } WFSCDMDENOMINATION, * LPWFSCDMDENOMINATION;

cCurrencyID
Identification of currency (ISO format).

ulAmount
The total amount of money to be dispensed. (Amount expressed in minimum dispense units; see WFS_INF_CDM_CURRENCY_EXP.)

usCount
Number of cash units used. Size of the array lpulValues.

lpulValues
Pointer to a list of ULONGs, specifying the number of coins/bills to take from the cash unit. The position in the list defines the logical number of the logical cash unit to be used, the first value in the array is related to the cash unit with the logical number 1. When more than one physical cash unit exists for a logical cash unit, the device selects the actual physical cash unit to use.

ulCashBox
Amount of money that could not be denominated and has to be paid from the tellers cash box. (Amount expressed in minimum dispense units; see WFS_INF_CDM_CURRENCY_EXP.)

Output Param LPWFSCDMDENOMINATION lpDenomination;For a description see the input structure.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_CASHUNITERROR The specified cash unit caused a problem. A WFS_EXECUTE_EVENT with an id of WFS_EXEE_CDM_CASHUNITERROR is posted with the details.

WFS_ERR_CDM_EXCHANGEACTIVE The CDM service is in an exchange state (see WFS_CMD_CDM_START_EXCHANGE).

WFS_ERR_CDM_INVALIDCURRENCY Currency type is not configured.

WFS_ERR_CDM_INVALIDDENOMINATION The sum of the values for cashbox, cash unit and coin were greater than the amount specified. Or, usMixNumber was WFS_CDM_INDIVIDUAL and the calculated denomination is smaller than the given amount.

WFS_ERR_CDM_INVALIDMIXNUMBER Mix algorithm is not known.

WFS_ERR_CDM_INVALIDTELLERID Teller ID not present in service provider’s teller ID list

WFS_ERR_CDM_NOCURRENCYMIX More than one currency was selected when the cash units were specified. The exception to this is when the cash unit selected contains a non-currency value such as a coupon.

WFS_ERR_CDM_NOTDISPENSABLE The amount is not dispensable by the cash dispenser.

WFS_ERR_CDM_TOOMANYBILLS The request would require too many bills to be dispensed.

WFS_ERR_CDM_TOOMANYCOINS The request would require too many coins to be dispensed.

Events The following additional events can be generated by this command:

Value Meaning

WFS_EXEE_CDM_CASHUNITERROR An error occurred while attempting to denominate from the cash unit specified by the event.

Comments None.