Currency Functions

Overview

The NCC Charging API can retrieve currency information from the NCC database for use within your scripts.

Currency information is cached (among all calls) for 300 seconds within the Lua runtime.


Functions


ccs.currencies ()
  Parameters None.  
  Returns A (possibly empty) table of CCS currencies, formatted as:

{
    <CCS_CURRENCY.ID> = {
        NAME = <CCS_CURRENCY.NAME>
        ID = <CCS_CURRENCY.ID>
        BASE = <CCS_CURRENCY.BASE>
        BIG_SYMBOL = <CCS_CURRENCY.BIG_SYMBOL>
        LITTLE_SYMBOL = <CCS_CURRENCY.LITTLE_SYMBOL>
        CODE = <CCS_CURRENCY.CODE>
        SEPARATOR = <CCS_CURRENCY.SEPARATOR>
    },
    <CCS_CURRENCY.ID> = {...}
}

  Errors If the retrieved currencies are not able to be turned into a table, the following error will be raised:

Retrieved currencies are not readable.

Usage This function queries the Lua runtime and extracts all currency details, returning it in a table of values.

local currencies = ccs.currencies ()
for k, v in pairs (currencies) do
    ncc.debug ("CCS_CURRENCY.CODE " .. v.CODE .. " has CCS_CURRENCY.ID " .. k)
end

This data may come from the Lua runtime cache if it is available and fresh. Otherwise, it is retrieved from the local SLC database.


ccs.get_currency_by_name (currency_name)
  Parameters currency_name The name of the currency to retrieve.
  Returns Either nil if no match is found, or a table for a single CCS currency, formatted as:

{
    NAME = <CCS_CURRENCY.NAME>
    ID = <CCS_CURRENCY.ID>
    BASE = <CCS_CURRENCY.BASE>
    BIG_SYMBOL = <CCS_CURRENCY.BIG_SYMBOL>
    LITTLE_SYMBOL = <CCS_CURRENCY.LITTLE_SYMBOL>
    CODE = <CCS_CURRENCY.CODE>
    SEPARATOR = <CCS_CURRENCY.SEPARATOR>
}

  Errors None.
Usage This function offers a helper lookup on the currency data on the NCC system. It calls the ccs.currencies function and then searches for the currency name provided, returning the currency details if found. If the currency is not found, nil is returned.

local nzd = ccs.get_currency_by_name ("New Zealand, Dollar (NZD)")
if (nzd and type (nzd) == 'table') then
    for k, v in pairs (nzd) do
        ncc.debug (k .. ": " .. v)
    end
end


ccs.get_currency_by_id (currency_id)
  Parameters currency_id The ID of the currency to retrieve.
  Returns Either nil if no match is found, or a table for a single CCS currency, formatted as:

{
    NAME = <CCS_CURRENCY.NAME>
    ID = <CCS_CURRENCY.ID>
    BASE = <CCS_CURRENCY.BASE>
    BIG_SYMBOL = <CCS_CURRENCY.BIG_SYMBOL>
    LITTLE_SYMBOL = <CCS_CURRENCY.LITTLE_SYMBOL>
    CODE = <CCS_CURRENCY.CODE>
    SEPARATOR = <CCS_CURRENCY.SEPARATOR>
}

  Errors None.
Usage This function offers a helper lookup on the currency data on the NCC system. It calls the ccs.currencies function and then searches for the currency ID provided, returning the currency details if found. If the currency is not found, nil is returned.

local first = ccs.get_currency_by_id (1)
if (first and type (first) == 'table') then
    ncc.debug ("The name of the first currency in the system is " .. first.NAME)
end


ccs.get_currency_by_code (currency_code)
  Parameters currency_code The code of the currency to retrieve.
  Returns Either nil if no match is found, or a table for a single CCS currency, formatted as:

{
    NAME = <CCS_CURRENCY.NAME>
    ID = <CCS_CURRENCY.ID>
    BASE = <CCS_CURRENCY.BASE>
    BIG_SYMBOL = <CCS_CURRENCY.BIG_SYMBOL>
    LITTLE_SYMBOL = <CCS_CURRENCY.LITTLE_SYMBOL>
    CODE = <CCS_CURRENCY.CODE>
    SEPARATOR = <CCS_CURRENCY.SEPARATOR>
}

  Errors None.
Usage This function offers a helper lookup on the currency data on the NCC system. It calls the ccs.currencies function and then searches for the currency code provided, returning the currency details if found. If the currency is not found, nil is returned.

local nzd = ccs.get_currency_by_code ("NZD")


ccs.currency_id_for_name (currency_name)
  Parameters currency_name The name of the currency to retrieve the ID for.
  Returns The ID of the currency that has the name provided, or nil if no match was found.
  Errors None.
Usage This is a specialised shortcut version of ccs.get_currency_by_name that returns only the ID of the currency name provided. If the currency is not found, nil is returned.

local nzd = "New Zealand, Dollar (NZD)"
ncc.debug ("The ID of the '" .. nzd .. "' currency is "
    .. ccs.currency_id_for_name (nzd) .. ".")


ccs.currency_name_for_id (currency_id)
  Parameters currency_id The ID of the currency to retrieve the name for.
  Returns The name of the currency that has the ID provided, or nil if no match was found.
  Errors None.
Usage This is a specialised shortcut version of ccs.get_currency_by_id that returns only the name of the currency ID provided. If the currency is not found, nil is returned.

ncc.debug ("The first currency in the system is " .. ccs.currency_name_for_id (1))