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

Methods Type Field Information
ncc.engine.account_code ()

ncc.engine.account_code (value)

Numeric String Subscriber account code.
ncc.engine.account_id ()

ncc.engine.account_id (value)

Numeric String CCS account ID.
ncc.engine.account_number ()

ncc.engine.account_number (value)

Numeric String Subscriber account number.
ncc.engine.acr_max_call_dur ()

ncc.engine.acr_max_call_dur (value)

Integer Maximum allowed Apply Charging duration.
ncc.engine.acs_customer () 

ncc.engine.acs_customer (value)

Integer ACS customer number for subscriber.
ncc.engine.addl_calling_party_num ()

ncc.engine.addl_calling_party_num (value)

Numeric String Additional calling party number.
ncc.engine.bcsm_code ()

ncc.engine.bcsm_code (value)

Integer BCSM code.
ncc.engine.be_id ()

ncc.engine.be_id (value)

Integer VWS subscriber ID.
ncc.engine.called_imsi ()

ncc.engine.called_imsi (value)

Numeric String Called IMSI.
ncc.engine.call_answer_time ()

ncc.engine.call_answer_time (value)

Integer Epoch time call was answered.
ncc.engine.called_location_num ()

ncc.engine.called_location_num (value)

Numeric String Called location number.
ncc.engine.called_sgsn_num ()

ncc.engine.called_sgsn_num (value)

Numeric String Called SGSN.
ncc.engine.called_tz ()

ncc.engine.called_tz (value)

String Called party time zone.
ncc.engine.caller_logical_tz ()

ncc.engine.caller_logical_tz (value)

String Calling party logical time zone.
ncc.engine.caller_network_tz ()

ncc.engine.caller_network_tz (value)

String Calling party network time zone.
ncc.engine.call_forwarded ()

ncc.engine.call_forwarded (value)

Integer Whether call was forwarded.
ncc.engine.call_id ()

ncc.engine.call_id (value)

Integer SLC call ID.
ncc.engine.calling_imsi ()

ncc.engine.calling_imsi (value)

Numeric String Calling IMSI.
ncc.engine.calling_logical_num ()

ncc.engine.calling_logical_num (value)

Numeric String Logical subscriber number.
ncc.engine.calling_network_num ()

ncc.engine.calling_network_num (value)

Numeric String Calling network number.
ncc.engine.calling_party_category ()

ncc.engine.calling_party_category (value)

Integer Calling party category.
ncc.engine.calling_party_id ()

ncc.engine.calling_party_id (value)

Numeric String Calling party ID.
ncc.engine.calling_pri_net_addr ()

ncc.engine.calling_pri_net_addr (value)

Numeric String Calling private network address.
ncc.engine.calling_pri_net_id ()

ncc.engine.calling_pri_net_id (value)

Integer Calling party private network ID.
ncc.engine.calling_sgsn_num ()

ncc.engine.calling_sgsn_num (value)

Numeric String Calling SGSN.
ncc.engine.call_time ()

ncc.engine.call_time (value)

Integer Epoch time call started.
ncc.engine.carrier_code ()

ncc.engine.carrier_code (value)

Integer Carrier code.
ncc.engine.extension_digits_0 ()

ncc.engine.extension_digits_0 (value)

String Extension digits 0.
ncc.engine.extension_digits_1 ()

ncc.engine.extension_digits_1 (value)

String Extension digits 1.
ncc.engine.extension_digits_2 ()

ncc.engine.extension_digits_2 (value)

String Extension digits 2.
ncc.engine.extension_digits_3 ()

ncc.engine.extension_digits_3 (value)

String Extension digits 3.
ncc.engine.extension_digits_4 ()

ncc.engine.extension_digits_4 (value)

String Extension digits 4.
ncc.engine.extension_digits_5 ()

ncc.engine.extension_digits_5 (value)

String Extension digits 5.
ncc.engine.extension_digits_6 ()

ncc.engine.extension_digits_6 (value)

String Extension digits 6.
ncc.engine.extension_digits_7 ()

ncc.engine.extension_digits_7 (value)

String Extension digits 7.
ncc.engine.extension_digits_8 ()

ncc.engine.extension_digits_8 (value)

String Extension digits 8.
ncc.engine.extension_digits_9 ()

ncc.engine.extension_digits_9 (value)

String Extension digits 9.
ncc.engine.language_id ()

ncc.engine.language_id (value)

Integer ACS language ID.
ncc.engine.last_call_duration ()

ncc.engine.last_call_duration (value)

Integer Duration of last (monitored) call.
ncc.engine.last_entered_pin ()

ncc.engine.last_entered_pin (value)

Numeric String Last PIN entered by the caller.
ncc.engine.last_terminating_num ()

ncc.engine.last_terminating_num (value)

Numeric String Last number terminated to.
ncc.engine.location_num ()

ncc.engine.location_num (value)

Numeric String Location number.
ncc.engine.message_type ()

ncc.engine.message_type (value)

Integer Message type.
ncc.engine.normalised_service_num ()

ncc.engine.normalised_service_num (value)

Numeric String Normalised SN (dialled number).
ncc.engine.original_called_num ()

ncc.engine.original_called_num (value)

Numeric String Original called number.
ncc.engine.pending_tn_no_answer_t ()

ncc.engine.pending_tn_no_answer_t (value)

Integer Attempt terminate no answer timer .
ncc.engine.pending_tn_num ()

ncc.engine.pending_tn_num (value)

Numeric String Pending termination number.
ncc.engine.pending_tn_type ()

ncc.engine.pending_tn_type (value)

Integer Pending termination number type.
ncc.engine.private_network_id ()

ncc.engine.private_network_id (value)

Integer Private network ID.
ncc.engine.request_cir ()

ncc.engine.request_cir (value)

Integer Whether CIR is armed.
ncc.engine.stored_sn_or_cli ()

ncc.engine.stored_sn_or_cli (value)

Numeric String SN or CLI for scheduled control plan.
ncc.engine.stored_sn_or_cli_type ()

ncc.engine.stored_sn_or_cli_type (value)

Integer SN or CLI type for scheduled control plan.
ncc.engine.term_pri_net_addr ()

ncc.engine.term_pri_net_addr (value)

Numeric String Called private network address.
ncc.engine.term_pri_net_id ()

ncc.engine.term_pri_net_id (value)

Integer Called party private network ID.
ncc.engine.use_rc_from_cir ()

ncc.engine.use_rc_from_cir (value)

Integer Whether to use the release cause from a CIR.

Reading Values

Read Method Parameters

None.

Read Method Returns

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

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

Methods Type Field Information
ncc.engine.called_party_id ()

ncc.engine.called_party_id (structure)

ncc.engine.called_party_id (digits, noa, screen)

Network Digits Called party ID.
ncc.engine.last_redir_party ()

ncc.engine.last_redir_party (structure)

ncc.engine.last_redir_party (digits, noa, screen)

Network Digits Last redirecting party ID.
ncc.engine.loc_info_loc_num ()

ncc.engine.loc_info_loc_num (structure)

ncc.engine.loc_info_loc_num (digits, noa, screen)

Network Digits Location information location number.
ncc.engine.msc_address ()

ncc.engine.msc_address (structure)

ncc.engine.msc_address (digits, noa, screen)

Network Digits Serving MSC address.
ncc.engine.vlr_number ()

ncc.engine.vlr_number (structure)

ncc.engine.vlr_number (digits, noa, screen)

Network Digits VLR number.

Reading Values

Read Method Parameters

None.

Read Method Returns

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

OR

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 (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.

If num and value supplied: nothing.

  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.

If value is supplied but not parseable to a string:

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'