Engine Fields
Engine Fields
All data fields the NCC SDK allows access to are exposed via this API for the N2 Logic Node. All fields are available for reading or writing.
There are two classes of engine fields: ‘normal’ and ‘network’. ‘Normal’ engine fields have a single value, whereas ‘network’ engine fields are a data structure composed of the field digits, NOA, and screening indicator (see below).
Each function for reading/writing engine fields is very similar, so is grouped in aggregate for documentation.
For more information on the information each field provides, refer to the OCNCC Number Manager technical guide.
Normal Fields
Normal engine fields take or return a single value: either a string, numeric string, or an integer. All functions will attempt to cast values given to the desired type. Each method has two forms, differentiated by the number of parameters:
ncc.engine.<field name> () -- no parameters: get the field value
ncc.engine.<field name> (<value>) -- one parameter: set the field value
Methods List
Reading Values
Read Method Parameters
None.
Read Method Returns
- The field value as the field’s type (string, numeric string, or integer)
- Nil if the field has no value in the engine
Read Method Errors
If the value returned by the engine is not parseable:
Retrieved engine field is not readable
Read Method Usage
Use the shorthand read methods to get a particular field’s value, providing no parameters.
For example, to get the time the call started:
t = ncc.engine.call_time ()
os.date ("%Y-%m-%d %H:%M:%S", t) -- date formatted nicely
To check the called party timezone:
t = ncc.engine.called_tz ()
if (t == 'NZ') then
-- etc.
To find out if a PIN was entered:
t = ncc.engine.last_entered_pin ()
if (t) then
-- etc.
Writing Values
Write Method Parameters
- value - new value for field (mandatory)
Write Method Returns
Nothing.
Write Method Errors
If the value returned by the engine is not parseable as the appropriate type (string, numeric string, or integer):
<field type> must be a <number | numeric string | string>
Write Method Usage
Use the shorthand write methods to set a particular field’s value, providing a single parameter of the new value.
Increase the last call duration by one minute:
t = ncc.engine.last_call_duration ()
ncc.engine.last_call_duration (t + 60)
Change the called party’s timezone:
ncc.engine.called_tz ('AU')
Write the BCSM code to extension digits 3:
ncc.engine.extension_digits_3 (ncc.engine.bcsm_code ())
Network Fields
When dealing with network engine fields, the following data structure is used:
{
DIGITS = <field digits (numeric string, 1-32 characters) >
NOA = < field NOA, (integer, 1-5)>
SCREEN = <field screening indicator, (integer, 0-1)>
}
As for normal fields, all functions will attempt to cast values to the required type in the structure.
This structure is used for return values, and can also be used when setting the field.
Each method has three forms, differentiated by the number of parameters:
ncc.engine.<field name> ()
-- no parameters: get the field value
ncc.engine.<field name> (<structure>)
-- one parameter (structure): set the field values as per the structure
ncc.engine.<field name> (<digits>, <noa>, <screen>)
-- three parameters (individual fields): set the field values as per the individual parameters
When specifing parameters individually, digits and noa are required, but screen is optional and defaults to 0.
Methods List
ncc.engine.called_party_id (structure) ncc.engine.called_party_id (digits, noa, screen)
ncc.engine.last_redir_party (structure) ncc.engine.last_redir_party (digits, noa, screen)
ncc.engine.loc_info_loc_num (structure) ncc.engine.loc_info_loc_num (digits, noa, screen)
ncc.engine.msc_address (structure) ncc.engine.msc_address (digits, noa, screen)
ncc.engine.vlr_number (structure) ncc.engine.vlr_number (digits, noa, screen)
Methods
Type
Field Information
ncc.engine.called_party_id ()
Network Digits
Called party ID.
ncc.engine.last_redir_party ()
Network Digits
Last redirecting party ID.
ncc.engine.loc_info_loc_num ()
Network Digits
Location information location number.
ncc.engine.msc_address ()
Network Digits
Serving MSC address.
ncc.engine.vlr_number ()
Network Digits
VLR number.
Reading Values
Read Method Parameters
None.
Read Method Returns
- Network digits table containing the field information if the field digits are populated in the ACS engine
- nil otherwise
Read Method Errors
If the value returned is not parseable into the table structure:
Retrieved engine network field is not readable
Read Method Usage
Use the shorthand read methods to get a particular network field’s value, providing no parameters.
For example, to get the called party ID:
t = ncc.engine.called_party_id ()
if (t) then
print t.DIGITS
print t.SCREEN
print t.NOA
end
Writing Values
Write Method Parameters
- digits - new digits for the field (mandatory)
- noa - new NOA value for the field (mandatory, 1-5)
- screen - new screening indicator value for the field (optional, 0-1, default: 0)
OR
- Network digits table containing the new field information
Write Method Returns
Nothing.
Write Method Errors
If the provided digits is not parseable as a numeric string:
<field type> digits must be a numeric string
If the provided noa is not parseable as a number:
<field type> NOA must be a number
Write Method Usage
Use the shorthand write methods to set a particular field’s value, providing either a single parameter as a structure with the new values, or 2-3 parameters with the values individually specified.
ncc.engine.vlr_number ("123A", 5)
ncc.debug (ncc.engine.vlr_number ()) -- digits: "123A", noa: 5, screening: 0
ncc.engine.vlr_number ("BB123456", 2, 1)
ncc.debug (ncc.engine.vlr_number ()) -- digits: "BB123456", noa: 2, screening: 1
t = {}
t.DIGITS = "ABC123"
t.NOA = 1
t.SCREEN = 0
ncc.engine.field.msc_address (t)
Other Functions
If num and value supplied: nothing.
If value is supplied but not parseable to a string:
▲ ncc.engine.extension_digits (num, value)
Parameters
num
The extension digits buffer number (0-9, mandatory).
value
The new value to write to the buffer (string, optional).
Returns
If only num supplied: the value of the given extension digits buffer, or nil if no value.
Errors
If num is not in the valid range or is not parseable as a number:
Extension digits buffer number must be 0-9 inclusive.
EXTENSION_DIGITS must be a string.
Usage
This is an alternate form of the previously-defined read and write methods for accessing the extension digits buffers.
b = 1
ncc.debug (ncc.engine.extension_digits (b)) -- prints the value of extension digits 1
for (i = 0, 9, 1 do)
ncc.engine.extension_digits (i, ncc.engine.extension_digits (i) + 1) -- increments each buffer
end
▲ ncc.engine.field.is_network_digits_field (field)
Parameters
field
The value to check as being a valid engine field identifier (mandatory).
Returns
Iff the field provided indicates a valid reference to an engine network digits field: true, otherwise false.
Errors
None.
Usage
This function allows you to know whether or not the provided field - presumably taken from the ncc.engine.field data structure - is considered to be a network digits field or not; network digits fields require a specialised data format when reading or writing to the ACS engine.
f = ncc.engine.field.VLR_NUMBER
ncc.engine.field.is_network_digits_field (f) -- returns 'true'
f = ncc.engine.field.CALLING_LOGICAL_NUM
ncc.engine.field.is_network_digits_field (f) -- returns 'false'