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

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

• ncc.engine.extension_digits
• ncc.engine.field.is_network_digits_field

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

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'