AITIA	AAR Logic (via HTTP/MLP)	Sga-AAR-Logic

The AAR Logic module
`("Sga-AAR-Logic")`

Program features
Program requirements
User interface
CDR generation
Application Parameters
Configuration (INI) file
Mobile Location Protocol errors
Built-in limitations
Program termination
SNMP trap list
Version history

Features

Implements MLP 3.0.0 over HTTP
Client request can be sent over HTTP or HTTPS
Different parameters for each application
Uses MAP sendRoutingInfoForLCS and provideSubscriberLocation operations to determine user location on 2G/3G network
Uses Diameter Provide-Location operations to determine user location on 4G network
- If vmscno contains at least one dot character then it is considered as an MME Id (interrogation of 4G network)
- Otherwise it is considered as a VLR GT (interrogation of 2G/3G network)
SNMP trap generation
CDR generation

Minimum operational requirements

1 GB RAM
MS Windows XP or newer operating system

User interface

The main menu

Menu	Menuitem	Shortcut(s)	Meaning
File
	Reload application parameters		Reload application parameters file (`INI/[Advanced]/sApplParamFile` and `sApplActiveFile`)
	Reload MSC GTs / MME hosts		Reload MSC GT Addresses and MME host names (INI/[MSCs to be queried] and [MMEs to be queried])
	Save request info to file	F2	Save detailed information about each triggered location reporting request to a CSV file in the directory `INI/[Advanced]/sReqInfoFilesPath`
Log
	Find line containing...	Ctrl-F	Find text in log window
	Find next matching line	F3	Find next occurrence of text in log window
	Details		Detail level of logging (Off, Normal, Detailed, or Debug)
Options
	Accept new MLP requests		Enable new MLP requests
	Enable TCP watchdog server		Enable TCP watchdog server
	Enable TCP watchdog debug log		Enable the TCP watchdog debug log, which indicates that a client has connected to the server successfully. Warning and error lines are still written to the log.
	Hide sensitive info		Hide most of the IMSI and MSISDN digits in the log and in the CDR. The HTTP logging is also disabled when the hiding is enabled.
	Auto scroll	ScrollLock, or	Allow automatic scrolling of the log screen
	Flush counters		Dump status line counter into log
	Flush and reset counters		Dump status line counter into log and clear them
	Show log	Ctrl-Tab, Ctrl-Shift-Tab	Show log screen
	Show MLP request queue	Ctrl-Tab, Ctrl-Shift-Tab	Show MLP waiting queue and processing status
	Show MAP request status	Ctrl-Tab, Ctrl-Shift-Tab	Show MAP (SRI, PSL) requests' status
	Save settings		Save actual settings into the configuration (INI) file

The status windows

Upper line

PSLquery: Status of the connection to the PSLquery module
(gray text color indicates that the connection is up, red indicates connection error)
Server state, requests being processed / request queue length
MLP request counters
Watchdog counters (if active) or watchdog state (if inactive)
Lower line
DiamPL: Status of the connection to the Diameter PLquery module
(gray text color indicates that the connection is up, red indicates connection error)
Uptime; time elapsed since module has been started up
MAP/SRI request counters
MAP/PSL request counters
Diam/PL request counters

Details of MLP request queue window

ID: Identifier of the MLP request
State: Current MLP and HTTP state of the request.
MLP state values:
- 0: There is no ongoing MLP request
- 1: Waiting for next trigger (tlrr only)
- 2: An MLP request is in progress
- 3: The MLP answer is being sent
HTTP state values:
- 0: There is no ongoing HTTP request
- 1: Connecting to client
- 2: Receiving data from peer
- 3: Data received from peer
- 4: Waiting to send the response
- 5: Sending data to peer
- 6: Shuting down connection
- 7: Ready
- 8: Error
Type: Request type. Possible values: slir, eme_lir, tlrr and tlrsr.
Ready: Number of MSID's processed / Total number of MSID's
User: Client id
Requester IP: IP address of the client
Req ID: Unique request ID for triggered requests
Stop time (GMT): stop_time of the tlrr

Details of MAP request queue window

ID: Identifier of the MAP request
State: Current state of the request
- not used: There is no ongoing request
- SRI wait4 rep: A MAP/SRI request is in progress
- PSL wait4 rep: A MAP/PSL request is in progress
- PL wait4 rep: A Diam/PL request is in progress
Time-out [s]: Remaining time for the current request
MLP req: MLP request ID which started this MAP request
MSID: MSISDN/IMSI being requested

CDR generation

The module creates a CDR entry when an MLP request is answered. A separate line is generated for each <msid> tag in the MLP request. One CDR file is opened for each calendar day. The name of the CDR is "Sga-AAR-Logic_CDR_YYYYMMDD.csv" reflecting the day when it is created.

Request arrival DateTime (GMT): MLP request arrival date and time in GMT
Record type: MLP answer type. Possible values: { slia | eme_lia | tlra | tlrsa | tlrep }
Record num items: Number of <msid> tags in the MLP request
Record item: Ordinal of the <msid> tag whose result is detailed in this row
Client id: Value of the <id> tag in the MLP request
Subclient: Value of the <subclient> tag in the MLP request
Requestor: Value of the <requestor> tag in the MLP request
MSISDN: Value of the <msid> tag in the MLP request if its type was MSISDN
Service id: Value of the <serviceid> tag in the MLP request
SRI DateTime (GMT): SRI request sending date and time in GMT
SRI duration [ms]: SRI request duration in ms; not filled if the response did not arrive in the preset time interval
SRI result: result of the SRI request
IMSI:
- Value of the <msid> tag in the MLP request if msid type was IMSI
- IMSI from the SRI response otherwise
VMSC number:
- Value of the 'vmscno' attribute in the <msid> tag in the MLP request if msid type was IMSI
- MSC number from the SRI response otherwise
PSL DateTime (GMT): PSL request sending date and time in GMT
PSL duration [ms]: PSL request duration in ms; not filled if the response did not arrive in the preset time interval
PSL result: result of the PSL request
MME Id: Value of the 'vmscno' attribute in the <msid> tag in the MLP request if msid type was IMSI and 'vmscno' is an MME Id
Diam/PL DateTime (GMT): Diam/PL request sending date and time in GMT
Diam/PL duration [ms]: Diam/PL request duration in ms; not filled if the response did not arrive in the preset time interval
Diam/PL result: result of the Diam/PL request
MLP error id: MLP status code

Application Parameters

Tag Name	Data Type	Valid Range	Description
<pwd>	`char string`	`string length: 0 - 18`	Password
<expiry_time>	`YYYYMMDDhhmmss`	`local time`	The location server will not accept new requests from the application after the specified time
<client_ips>	`<ip>`	`0 - 100`	If empty (or first is 0.0.0.0) then any peer IP address is accepted
<ip>	`x.y.z.w`		Internet protocol address in dot notation
<is_emergency>	`Boolean`	`0 - 1`	0: standard 1: emergency
<allow_reporting_services>	`Boolean`	`0 - 1`	0: do not allow 1: allow
<max_msids_per_minute>	`integer`	`0 - 10000`	Maximum number of <msid> location requests per minute on one server
<max_msids_per_request>	`integer`	`1 - 100`	Maximum number of <msid> location requests per <svc_init> request
<priority_class>	`integer`	`0 - 2`	0: low 1: medium 2: high
<report_url>	`http://x.y.z.w:port/dir`	`dir length: 0 - 255`	Internet protocol address in dot notation with TCP port number and URL directory. The `port` number is obligatory.

When an application is suspended, is deleted or expires, all its requests are canceled immediately.

When the parameter max_msids_per_minute is changed, the current MAP requests are processed further on and the new limit will apply on new MAP requests only.

Other parameter changes have no effect on the currently processed requests. For triggered location reports, the parameter changes take effect when the processing of a new report is started.

Configuration (INI) file settings

Section	Entry	Example	Meaning
[Position]
	iLeft	140	Position of the program module on the display screen
	iTop	72	Position of the program module on the display screen
	iWidth	995	Position of the program module on the display screen
	iHeight	694	Position of the program module on the display screen
[Options]
	bAutoScroll	True	(Refer to the `[Options]/Auto scroll` menu item!)
[HTTPs]
	bEnable	False	If True then switches on HTTPS
	sCertFilePath	CertFiles\server.crt	Path and filename for the server side certificate file
	sPrivateKeyPath	CertFiles\server.key	Path and filename for the private key
	bUsePrivateKeyPassword	True	Enables of using private key password
	sPrivateKeyPassword	12345	Defined private key password
[Advanced]
	wLogDetailLevel	3	(Equals to the listed order; refer to the corresponding menuitem!)
	dwMaxLinesInLogWindow	1000	Number of lines in the log window on screen
	sLogFilesPath	C:\Sga-AAR-Logic\LogFiles	Path for the log files
	sHTTPLogFilesPath	C:\Sga-AAR-Logic\LogFiles	Path for the HTTP log files
	sTrapFilesPath	C:\Sga-AAR-Logic\TrapFiles	Path for the SNMP Trap files to be sent
	sCDRFilesPath	C:\Sga-AAR-Logic\CDRFiles	Path for the Call Data Record files. This entry is optional: CDR is not generated when the entry is not present.
	sCDRColumnDelimiter	;	Delimiter character between values in the CDR and the request info files
	sApplParamFile	C:\Sga-AAR-Logic\appl_param.xml	Path and filename for the Application Parameters file.
	sApplActiveFile	C:\Sga-AAR-Logic\appl_active.lst	Path and filename for the Active Applications file
	sTempFilesPath	C:\Sga-AAR-Logic\TempFiles	Path for temporary files
	sReqInfoFilesPath	C:\Sga-AAR-Logic\ReqInfoFiles	Path for the request info files that are written on user command
	bAlternateTrapUID	False	Allows using fixed UIDs in SNMP traps (See SNMP trap list below for details)
[TCP_Watchdog]
	wLocalTCPPort	7777	TCP listen port. If 0 then the watchdog service is not started.
[PSLquery]
	sRemoteIPAddress	127.0.0.1	IP address of `Sga-PSLquery` module
	wRemoteTCPPort	9069	TCP port where the query module listens
	wSRIqueryTimeOutMsec	3000	Time out value for SRI requests
	wPSLqueryTimeOutMsec	5000	Time out value for PSL requests
[DiameterPL]
	sRemoteIPAddress	127.0.0.1	IP address of `SGA-Diameter_ProvideLocation` module
	wRemoteTCPPort	9070	TCP port where the query module listens
	wPLqueryTimeOutMsec	3000	Time out value for Diam/PL requests
[MSCs to be queried]	At most 20 GTs can be defined.
	sGT01	36709123451	First VLR address to be interrogated
	sGT02	36709123452	Second VLR address to be interrogated
[MMEs to be queried]	At most 20 Ids can be defined.
	sHost01	tbepcusn01.mme.epc.mnc070.mcc216.3gppnetwork.org	First MME Id to be interrogated
	sHost02	tbepcusn02.mme.epc.mnc070.mcc216.3gppnetwork.org	Second MME Id to be interrogated
[MLP]
	wDefaultRespTimer	60	MLP response time-out in seconds
	wHTTPServerPort	9210	HTTP server TCP port for MLP requests
	sExpectedUrlPath	/LBS	Expected URL path for incoming MLP requests; URL path is not checked if this entry is empty
	wRequestTimeOutMsec	2000	Maximum time for receiving a location request
	wAnswerTimeOutMsec	4000	Maximum time for sending a location answer
	wReportTimeOutMsec	3000	Maximum time for sending a location report
	wLCSClientType_Std	2	MAP PSL/LCSClientType for standard MLP requests
	wLCSClientType_Eme	0	MAP PSL/LCSClientType for emergency MLP requests
	bUseLegacyXML	False	When it is False the MLP answer will always contain the <servingcell></servingcell> tags, as well as <shape></shape> tags. When it is True the MLP answer will only contain the <shape></shape> tags. Default is False.
	bTryFirstMSCGTs	True	When 'vmscno="all"' and it is True the program will interrogate MSCs first (if defined any), then MMEs. If it is False, then MMEs will be interrogated first. Default is True.
[SRI_result to MLP_resid]
	SRI result	MLP resid	SRI result (MAP error) to MLP resid mapping; For example the entry "21=5" means "map the facilityNotSupported MAP error to the ABSENT SUBSCRIBER MLP error"

The entries of sections [Position], [Options] and some of [Advanced] are optional, the rest are required.

Mobile Location Protocol errors

Res_Id	Slogan	Possible Causes
`1`	`SYSTEM FAILURE`	connection between 'Sga-AAR-Logic' and 'Sga-PSLquery' modules is down; connection between 'Sga-PSLquery' and 'GyX_SCTP' modules is down; the MAP error `"systemFailure"` has occurred; the Diameter Result Code `"DIAMETER_UNABLE_TO_COMPLY" (5012)` has occured; a MAP or Diameter operation timed out
`2`	`UNSPECIFIED ERROR`	a MAP error other than `"unknownSubscriber", "absentSubscriber", "systemFailure" and "positionMethodFailure"` has occurred; the Diameter Result Code `"DIAMETER_UNABLE_TO_COMPLY" (5012)` or other has occured; the Diameter Experimental Result Code `"DIAMETER_ERROR_UNAUTHORIZED_REQUESTING_NETWORK" (5490)`, `"DIAMETER_ERROR_USER_UNKNOWN"` (5001), `"DIAMETER_ERROR_POSITIONING_DENIED" (4224)` or `"DIAMETER_ERROR_POSITIONING_FAILED" (4225)` or other has occured
`3`	`UNAUTHORIZED APPLICATION`	unknown application id; bad application password; illegal client IP address; the application is suspended or has expired; the Diameter Experimental Result Code `"DIAMETER_ERROR_UNAUTHORIZED_REQUESTING_NETWORK" (5490)` has occured
`4`	`UNKNOWN SUBSCRIBER`	the MAP error `"unknownSubscriber"` has occurred; the Diameter Experimental Result Code `"DIAMETER_ERROR_USER_UNKNOWN" (5001)` has occured
`5`	`ABSENT SUBSCRIBER`	the MAP error `"absentSubscriber"` has occurred
`6`	`POSITION METHOD FAILURE`	the MAP error `"positionMethodFailure"` has occurred; the Diameter Experimental Result Code `"DIAMETER_ERROR_POSITIONING_DENIED" (4224)` or `"DIAMETER_ERROR_POSITIONING_FAILED" (4225)` has occured
`101`	`CONGESTION IN LOCATION SERVER`	too many requests of the application; no room for new requests; msid location is not determined because the MLP request has timed out
`104`	`TOO MANY POSITION ITEMS`	the number of <msid> tags in <msids> is above the limit
`106`	`SYNTAX ERROR`	XML or MLP syntax or format error
`108`	`SERVICE NOT SUPPORTED`	emergency request is not allowed if the application is not of emergency type (`is_emergency = 0`); triggered service is not allowed for the application (`allow_reporting_services = 0`)
`110`	`INVALID PROTOCOL ELEMENT VALUE`	invalid `req_id` in `tlrsr`; invalid value of `interval`, `start_time` or `stop_time`

For SRI requests, the MAP error to MLP resid mapping can be overridden by entries in the [SRI_result to MLP_resid] section of the INI file.

Built-in limitations

max. length of application id and pwd: 18, charset: ANSI
max. length of service id: 32
max. length of msid: 18
max. length of vmscno: 256
max. number of applications: 100
max. number of active applications: 30
max. number of concurrent connections per application: 10
max. number of concurrent slir or eme_lir per application: 10
max. number of concurrent tlrr per application: 100
max. number of concurrent MAP (SRI, PSL) requests: 20
max. value of the application parameter 'max_msids_per_request': 99

Program termination

To quit the module gracefully, press the 'Close' button or Alt+F4 keys once, confirm the quit request and wait until the message box with the text 'Ready to quit' appears.

To quit the module immediately press and confirm 'Close' twice. In this case pending slir and eme_lir requests will be lost.

SNMP trap list

UID	Type	Text	Remarks	To Do
If `bAlternateTrapUID` is set to TRUE
5000	CEA	`'Sga-AAR-Logic v1.00' module is started.`	Send a welcome message; indication of module start-up
5000	CRI	`'Sga-AAR-Logic v1.00' module has been shut down by operator.`	Send a farewell warning message; indication of module shut-down	Start the `'Sga-AAR-Logic v1.00'` module
0	INF	`Connection to 'Sga-PSLquery' module is up.`
5002	CRI/CEA	`Connection to 'Sga-PSLquery' module has died.`	CRI on the connection has died, CEA on it has been restored	Check if the IP connection between the `'Sga-AAR-Logic'` and the `'Sga-PSLquery'` modules is correct or if the module `'Sga-PSLquery'` is alive
0	INF	`Connection to 'SGA-Diameter_ProvideLocation' module is up.`
5003	CRI/CEA	`Connection to 'SGA-Diameter_ProvideLocation' module has died.`	CRI on the connection has died, CEA on it has been restored	Check if the IP connection between the `'Sga-AAR-Logic'` and the `'SGA-Diameter_ProvideLocation'` modules is correct or if the module `'SGA-Diameter_ProvideLocation'` is alive
5050	CRI/CEA	`Could not load the application parameters files.`	CRI on the files could not be loaded, CEA on the files has been loaded	Check if the application parameters and the application list files are present, if they are valid and if the corresponding INI file settings are correct
If `bAlternateTrapUID` is set to FALSE
0	INF	`'Sga-AAR-Logic v1.00' module is started.`	Send a welcome message; indication of module start-up
0	WAR	`'Sga-AAR-Logic v1.00' module has been shut down by operator.`	Send a farewell warning message; indication of module shut-down	Start the `'Sga-AAR-Logic v1.00'` module
0	INF	`Connection to 'Sga-PSLquery' module is up.`
++N	CRI	`Connection to 'Sga-PSLquery' module has died.`	CRI on the connection has died, CEA on it has been restored	Check if the IP connection between the `'Sga-AAR-Logic'` and the `'Sga-PSLquery'` modules is correct or if the module `'Sga-PSLquery'` is alive
N	CEA	`Connection to 'Sga-PSLquery' module has died.`	Connection to 'Sga-PSLquery' module is up after a down
0	INF	`Connection to 'SGA-Diameter_ProvideLocation' module is up.`
++N	CRI	`Connection to 'SGA-Diameter_ProvideLocation' module has died.`	CRI on the connection has died, CEA on it has been restored	Check if the IP connection between the `'Sga-AAR-Logic'` and the `'SGA-Diameter_ProvideLocation'` modules is correct or if the module `'SGA-Diameter_ProvideLocation'` is alive
N	CEA	`Connection to 'SGA-Diameter_ProvideLocation' module has died.`	Connection to 'SGA-Diameter_ProvideLocation' module is up after a down
++N	CRI/CEA	`Could not load the application parameters files.`	CRI on the file could not be loaded, CEA on the file has been loaded	Check if the application parameters and the application list files are present, if they are valid and if the corresponding INI file settings are correct

Version history

v1.13

(f) HTTPs bugfix

v1.12

(n) HTTPs for client requests, using OpenSSL v1.1.0.
(n) INI/[HTTPs]/bEnable.
(n) INI/[HTTPs]/sCertFilePath.
(n) INI/[HTTPs]/sPrivateKeyPath.
(n) INI/[HTTPs]/bUsePrivateKeyPassword.
(n) INI/[HTTPs]/sPrivateKeyPassword.

v1.11

(f) In case of vmscno=all and the Diameter_PL request timed out then the result was "system failure" despite the successful PSL request.
(f) Answer of the last VLR is sent on MLP for vmscno="all" request.

v1.10

(f) All VLRs and MMEs were interrogated when the interrogation of the HLR provided VLR failed for an MSISDN request after a vmscno="all" request.

v1.09

(n) Location can be requested based on the IMSI and MME Id.
(n) Connection to DiameterPL query modul.
(n) MLP request: The vmscno="all" option introduced to interrogate listed VLRs and MMEs till a response having location information or end of list of requested nodes.
(n) INI/[DiameterPL]/sRemoteIPAddress.
(n) INI/[DiameterPL]/wRemoteTCPPort.
(n) INI/[DiameterPL]/wPLqueryTimeOutMsec.
(n) INI/[MSCs to be queried]/sGT01..sGT19 (logged at start-up and reload).
(n) INI/[MMEs to be queried]/sHost01..sHost19 (logged at start-up and reload).
(n) INI/[MLP]/bUseLegacyXML (defaults to False).
(n) INI/[MLP]/bTryFirstMSCGTs (defaults to True).
(n) Menu item: [File]/Reload MSC GTs / MME hosts.
(c) CDR fields are added: MME Id, Diam/PL DateTime (GMT), Diam/PL duration [ms], Diam/PL result.

v1.08

v1.06

v1.05

(n) Location can be requested based on the IMSI and MSC number.
(n) CDR file: 'IMSI' column added.
(c) CDR file: 'VLR number' column renamed as 'VMSC number'.

v1.04

(f) MLP answer/report: white space characters in error text were also omittted.

v1.03

v1.02

First official release.

The AAR Logic module("Sga-AAR-Logic")

Table of Contents