xref: /third_party/icu/tools/currency/readme.txt

*******************************************************************************
* © 2016 and later: Unicode, Inc. and others.
* License & terms of use: http://www.unicode.org/copyright.html
*******************************************************************************
* Copyright (C) 2012-2013, International Business Machines Corporation and    *
* others. All Rights Reserved.                                                *
*******************************************************************************

[Overview]

This directory contains a tool used for maintaining ICU's ISO 4217 currency
code mapping data. ICU uses a resource generated by this tool for mapping
ISO 4217 currency alpha codes to numeric codes.


[Files]

package com.ibm.icu.dev.tool.currency

Main.java - The tool's entry point
NumericCodeData.java - The mapping data used by ICU
CurrencyDataParser.java - ISO 4217 XML data parser
CurrencyDataEntry.java - ISO 4217 XML data entry


[Details]

com.ibm.icu.dev.tool.NumericCodeData has String[][] CODE_MAP_DATA.
This array represents mappings between ISO 4217 alpha codes and
numeric codes. ICU's resource bundle currencyNumericCodes is generated
from the table.

ISO 4217 maintenance agency - SIX Interbank Clearing distributes
ISO 4217 code data in XML format. These files are found in
http://www.currency-iso.org/iso_index/iso_tables.htm. There are two
files that we're interested in.

 - https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/lists/list-one.xml
 - https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/lists/list-three.xml

Table A.1 contains current currencies and funds and Table A.3 contains
historic denominations.

The tool supports 2 commands - check / resource.

1) check

This command compares the hardcoded mapping data in NumericCodeData.java
with the ISO 4217 XML data files side by side and check differences.

2) resource

This command writes out the hardcoded mapping data in NumericCodeData.java
in ICU resource bundle source format - currencyNumericCodes.txt.


[Release Tasks]

For each ICU release, we should check if the mapping data is up to date.

Prerequisites: Java 6+, ant

First, run the ant target "check". This ant target download XML files from
the SIX Interbank Clearing site and invoke the tool command "check".

When the target successfully finished, you should see the log like below:
----------------------------------------------------------------------------
C:\devtools\trunk\currency>ant
Buildfile: C:\devtools\trunk\currency\build.xml

classes:

_checkLocalXml:

_localXml:

_downloadXml:
     [echo] Downloading ISO 4217 XML data files
      [get] Getting: http://www.currency-iso.org/dam/downloads/lists/list_one.xm
l
      [get] To: C:\devtools\trunk\currency\out\xml\list_one.xml
      [get] Getting: http://www.currency-iso.org/dam/downloads/lists/list_three.
xml
      [get] To: C:\devtools\trunk\currency\out\xml\list_three.xml

xmlData:

check:
     [java] [OK] ICU data is synchronized with the reference data

resource:
     [echo] ISO 4217 numeric code mapping data was successfully created in C:\de
vtools\trunk\currency/out/res

build:

BUILD SUCCESSFUL
Total time: 1 second
----------------------------------------------------------------------------
In this case, our data is synchronized with the latest XML data and you're done.


If the data is out of sync, you should see message like below:
----------------------------------------------------------------------------
check:
     [java] Missing alpha code in ICU map [ZWR]
     [java] Codes not found in the reference data: ZZZ

BUILD FAILED
C:\devtools\trunk\currency\build.xml:54: Java returned: 1
----------------------------------------------------------------------------
In this case, you have to update the hardcoded data in NumericCodeData.
You can either edit the table in NumericCodeData manually, or run the tool
command "print" and copy the output and paste it to the table.

Once you make sure "ant check" returns no errors, run "ant resource". This
target generate out/res/currencyNumericCodes.txt. The file should go to
<icu4c>/source/data/misc directory.

Note: The default ant target does both operation. Although it creates the
ICU resource file, you do not need to replace the one in ICU4C package with
the newly generated one if "check" successfully finished.