Processing Currency Data

How to:

Reference:

After you have created your currency data source, identified the currency-denominated fields in your data sources, and activated your currency data source, you can perform currency conversions.

Each currency ID in your currency data source generates a virtual conversion function whose name is the same as its currency ID. For example, if you added BEF to your currency data source, a virtual BEF currency conversion function will be generated.

The euro function, EUR, is supplied automatically with your application. You do not need to add the EUR currency ID to your currency data source.

The result of a conversion is calculated with very high precision, 31 to 36 significant digits, depending on platform. The precision of the final result is always rounded to two decimal places. In order to display the result to the proper precision, its format must allow at least two decimal places.

Syntax: How to Process Currency Data

In a procedure

DEFINE FILE filename
result/format [CURR curr_id] = curr_id(infield, rate1 [,rate2]);
END

or

COMPUTE result/format [CURR curr_id] = curr_id(infield, rate1 [,rate2]);

In a Master File

DEFINE result/format [CURR curr_id] = curr_id(infield, rate1 [,rate2]);$

where:

filename

Is the name of the file for which this field is defined.

result

Is the converted currency value.

format

Is a numeric format. Depending on the currency denomination involved, the recommended number of decimal places is either two or zero. The result will always be rounded to two decimal places, which will display if the format allows at least two decimal places. Do not use an Integer or Floating Point format.

curr_id
Is the currency ID of the result field. This ID must be the value EUR or match a currency ID in your currency data source. Any other value generates the following message:
(FOC263)  EXTERNAL FUNCTION OR LOAD MODULE NOT FOUND: curr_id

Note: The CURR attribute on the left side of the DEFINE or COMPUTE identifies the result field as a currency-denominated value which can be passed as an argument to a currency function in subsequent currency calculations. Adding this attribute to the left side of the DEFINE or COMPUTE does not invoke any format or value conversion on the calculated result.

infield

Is a currency-denominated value. This input value will be converted from its original currency to the curr_id denomination. If the infield and result currencies are the same, no calculation is performed and the result value is the same as the infield value.

rate1

Is the name of a rate field from the currency data source. The infield value is divided by the rate1 value of the currency to produce the equivalent number of euros.

If rate2 is not specified in the currency calculation and triangulation is required, this intermediate result is then multiplied by the result currency rate1 value to complete the conversion.

In certain cases, you may need to provide different rates for special purposes. In these situations you can specify any field or numeric constant for rate1 as long as it indicates the number of units of the infield currency denomination that equals one euro.

rate2

Is the name of a rate field from the currency data source. This argument is only used for those cases of triangulation in which you need to specify different rate fields for the infield and result currencies. It is ignored if the euro is one of the currencies involved in the calculation.

The number of euros that was derived using rate1 is multiplied by the result currency rate2 value to complete the conversion.

In certain cases, you may need to provide different rates for special purposes. In these situations you can specify any field or numeric constant for rate2 as long as it indicates the number of units of the result currency denomination that equals one euro.

Reference: Currency Calculation Error Messages

Issuing a report request against a Master File that specifies a currency code not listed in the active currency data source generates the following message:

(FOC1911) CURRENCY IN FILE DESCRIPTION NOT FOUND IN DATA

A syntax error or undefined field name in a currency conversion expression generates the following message:

(FOC1912)  ERROR IN PARSING CURRENCY STATEMENT

Example: Using the Currency Conversion Function

Assume that the currency data source contains the currency IDs USD and BEF, and that PRICE is denominated in Belgian francs as follows:

FIELD = PRICE, ALIAS=, FORMAT = P17.2, CURR=BEF,$
  • The following example converts PRICE to euros and stores the result in PRICE2 using the BUDGET conversion rate for the BEF currency ID:
    COMPUTE PRICE2/P17.2 CURR EUR = EUR(PRICE, BUDGET);
  • This example converts PRICE from Belgian francs to US dollars using the triangulation rule:
    DEFINE PRICE3/P17.2 CURR USD = USD(PRICE, ACTUAL);$

    First PRICE is divided by the ACTUAL rate for Belgian francs to derive the number of euros rounded to three decimal places. Then this intermediate value is multiplied by the ACTUAL rate for US dollars and rounded to two decimal places.

  • The following example uses a numeric constant for the conversion rate:
    DEFINE PRICE4/P17.2 CURR EUR = EUR(PRICE,5);$
  • The next example uses the ACTUAL rate for Belgian francs in the division and the BUDGET rate for US dollars in the multiplication:
    DEFINE PRICE5/P17.2 CURR USD = USD(PRICE, ACTUAL, BUDGET);$

Example: Converting U.S. Dollars to Euros, French Francs, and Belgian Francs

The following is an example of converting U.S. dollars to Euros, French Francs, and Belgian Francs.

  1. Create a currency data source that identifies the currency and one or more exchange rates. (See Creating the Currency Data Source for details.) The following sample data source is named CURRCODE:
    FILE = CURRCODE, SUFFIX = COM,$
    FIELD = CURRENCY_ID,,    FORMAT = A3,    ACTUAL = A3 ,$
    FIELD = ACTUAL, ALIAS =, FORMAT = D12.6, ACTUAL = A12 ,$
    FIELD = BUDGET, ALIAS =, FORMAT = D12.6, ACTUAL = A12 ,$
  2. Create a data source that contains the values to be converted. (See Identifying Fields That Contain Currency Data for details.) The following sample data source is named CURRDATA:
    FILE=CURRDATA,SUFFIX=COM,$
    FIELD=PRICE, FORMAT=P17.2 , ACTUAL=A5, CURR=USD,$
  3. Create a request that uses the currency data source to convert the currency values contained in the data source containing these values. The following procedure converts PRICE to euros, French francs, and Belgian francs. The numbers on the left correspond to the notes explaining the code.
   -* THE FOLLOWING ALLOCATIONS ARE FOR RUNNING UNDER z/OS 
1. -* DYNAM ALLOC FILE CURRCODE DA USER1.FOCEXEC.DATA(CURRCODE) SHR REU 
2. -* DYNAM ALLOC FILE CURRDATA DA USER1.FOCEXEC.DATA(CURRDATA) SHR REU
    -* THE FOLLOWING ALLOCATIONS ARE FOR RUNNING UNDER WINDOWS NT 
1.     FILEDEF CURRCODE DISK GGDEMO/CURRCODE.COM 
2.    FILEDEF CURRCODE DISK GGDEMO/CURRDATA.COM 
3. SET EUROFILE = CURRCODE 
   DEFINE FILE CURRDATA 
4. PRICEEUR/P17.2 CURR EUR = EUR(PRICE, ACTUAL);
    END
    TABLE FILE CURRDATA
    PRINT PRICE PRICEEUR AND COMPUTE 
5. PRICEFRF/P17.2 CURR FRF = FRF(PRICE, ACTUAL);
    PRICEBEF/P17.2 CURR BEF = BEF(PRICE, ACTUAL);
    END

The report request executes as follows:

  1. The FILEDEF or DYNAM command informs the operating system of the location of the CURRCODE data source.
  2. The FILEDEF command informs the operating system of the location of the CURRDATA data source.
  3. The SET command specifies the currency data source as CURRCODE.
  4. This line calls the EUR function, which converts U.S. dollars to euros.
  5. The next two lines are the conversion functions that convert euros into the equivalent in French and Belgian Francs.

The output is:

PRICE          PRICEEUR           PRICEFRF           PRICEBEF 
-----          --------           --------           -------- 
 5.00              4.26              27.97             172.01 
 6.00              5.12              33.57             206.42 
40.00             34.12             223.78            1376.20 
10.00              8.53              55.95             344.06

You cannot use the derived euro value PRICEEUR in a conversion from USD to BEF. PRICEEUR has two decimal places (P17.2), not three, as the triangulation rules require.