Multicurrency¶
Sculptor version 5 supports the use of automatic currency conversion. All currency and money data in an application is stored in the application’s main currency. However, a different currency may be selected at run time to be the active currency. Monetary values are dynamically converted to the active currency for input, display, calculation, or print operations. The stored data remains entirely unaffected.
A monetary field is any field that has been assigned the logical type cy (currency) or my (Sculptor 2 money). See Logical field types.
The Sculptor system variable sys.Currency stores the current active currency. If a new value is assigned to sys.Currency the change is effected instantly.
Exchange rates file¶
The multicurrency feature requires all currencies used by the application to be stored in an exchange rates file - a standard Sculptor data dictionary (.d), keyed on a unique currency code (an integer value). Each record in the file stores information about a single currency and its relationship to the main currency used by the application.
The name and path of the exchange rates file are chosen by the programmer, and must be stored in the environment variable SCEXRATES. It is not necessary to declare the file within a Sculptor program; Sculptor refers to SCEXRATES and declares and opens the file automatically as required.
The structure of the file is also defined by the programmer, with the exception of the key field and first three data fields, which must conform to the specifications laid out below. After these, further fields can be freely added, to store any data required.
The key field and first three data fields of the exchange rates file have pre-defined types and purposes, though the programmer can choose their names.
Key field |
Currency code. The file must have a single key field of u2 or i2 type. This stores the currency code. A currency code is an integer value. A record with the currency code 1 must exist. This is the main currency used by the application. Other than this, currencies may be assigned any code number, and the numbers need not be consecutive. It is recommended that once currencies have been assigned a code number and entered in the file, a set of representative !defines be created, e.g.: !define US_DOLLARS 1
!define EUROS 2
!define YEN 3
These definitions may usefully be maintained in the include file local.h, which is included automatically in Sculptor programs. |
Data field 1 |
Exchange rate. This field must be of an r8 type. It stores the exchange rate between this currency and currency number 1, the main currency. The exchange rate can be altered at any time, and the change takes effect immediately. |
Data field 2 |
Rounding unit. The second data field must also be an r8 type. It stores the rounding precision for that currency. For example, the Italian lira and Spanish peseta are rounded to the unit, while the pound is rounded to the penny, so the rounding precision should be 1.0 for the peseta and 0.01 for the pound. Users are free to create currencies of their own, based on the main currency. For instance, if the main currency were the pound, a currency called “thousands of pounds”, which displayed accounts in thousands of pounds, could be created. It would be assigned the exchange rate 1000, and rounding precision 1. |
Data field 3 |
Currency name. An alphanumeric field of at least 30 characters, to store the currency name. |
When a value is assigned to sys.Currency, selecting a new active currency, the exchange rate record for this currency is read automatically, and values from it are stored in the following Sculptor system variables:
The exchange rate |
|
The rounding unit |
|
The currency name |