TSP Lab	SgaWCx - The 'Who Called' Module	SgaWCx

The 'Who Called' module for Sigtran
`("SgaWCx")`

Features

Implements the WhoCalled and NotifyMe service logic
Connects via Sigtran associations to the MSC (using the GyX_SCTP module for this purpose)
For ISUP triggers:
- Handles virtual speech channels
- Answers an ACM for incoming IAMs and after a given period sends a REL with adjustable release cause value
For SIP triggers:
- Acts as an Application Server using UDP over IP and receives SIP messages from the IMS
- Answers periodic OPTIONS messages with 200OK
- Answers an INVITE message with a Response containing a configurable status-code and receives
Handles connections with the HLR using MAP (Phase 1 or Phase 2) protocol
Sends 'reporSM_DeliveryStatus' to the HLR in 'Not Reachable' cases
Receives and answers the 'alertServiceCentre' messages from the HLR
Creates 'WhoCalled' SMS in 'Busy' cases for the called subscribers
Creates 'WhoCalled' SMS for the called and 'NotifyMe' SMS for the calling subscribers
Black List for subscribers who do not want to get information SMS (in case of WhoCalled and NotifyMe, as well)
Exception list for callers with mobile number portability (NotifyME case)
Creates alarms on PCM events and on SMS file writing problems and when an unknown MSU received
Generates 15-minute statistics in CSV format about incoming calls and SMS's
Accepts remote 'ReloadBlackLists' requests via UDP/IP (from the client SgaWC_UDP_LoadBlackList.exe).

User interface

The main menu

Menu	Menuitem	Shortcut(s)	Meaning
[Log]
	Find line containing...	(Ctrl-F)	Finds text in log window
	Find next matching line	(F3)	Finds next occurrence of text in log window
	Details		Detail level of logging (Off, Normal, Detailed, or Debug)
[SS7]
	Send BLO for all speech channels		Blocks all speech channels by sending 'Blocking circuit' message
	Send RSC for all speech channels		Resets all speech channels by sending 'Reset circuit' message
	Send UBL for all speech channels		Unblocks speech channels
[BlackLists]
	Reload Content	Ctrl+B	Reloads blacklist files
[MSISDN Memory]
	Drop contents		All MSISDN pairs will be deleted
	Dump contents		List all MSISDN pairs into the log. Be careful with it, logging onto screen is very resource consuming!
[Options]
	Auto scroll	(ScrollLock, or )	Allows automatic scrolling of the log screen
	Flush counters		Logs the status bar counters into the log and onto the screen
	Flush & reset counters		Logs the status bar counters and clear them
	Save settings		Saves actual settings into the configuration (`SgaWCx.ini`) file

The bottom status-line

GyX: Status of the connection to the signaling interface module (its color is gray in normal works, red refers to error)
- bps: Current transfer speed
- Rx OK/Fail: All received right and failed messages
- Tx OK/Fail: All transmitted right and failed messages

SS7
- IAM Rx:
  - OK: number of received good IAM's
  - bad: number of badly formatted IAM's
  - noCIC: number IAM's with wrong CIC
- Alert
  - req: number of reportSM_deliveryStatus messages sent to the HLR
  - ans: answers of the HLR for requests (alertServiceCentre)
- Error counters:
  - msu: received an uninterpretable or misaddressed MSU (wrong Point Code)
  - tcap: number of wrong TCAP messages

UDP
- SIP:
  - INVITE: number of received SIP / INVITE messages
  - ACK: number of received SIP / ACK messages
  - OPTIONS: number of received SIP / OPTIONS messages
  - unexpected: number of received unexpected SIP messages

MSISDNmem
- alloc'd: actual number of entries in the MSISDN memory
- forgot: forgotten entries what reached the INI/[MSISDN Memory]/dwTimeOutSec value
- errFull: dropped pairs because MSISDN memory is full (INI/[MSISDN Memory]/dwCount)

SMS
- Busy: counter for Busy SMS's
- NotReachable: counter for NotReachable SMS's
- Notify: counter for Notify SMS's

Uptime: time elapsed since the module started

Black list feature

Black lists can be applied on SMS sending to ban individuals or groups, as well.
Four lists can be defined. Their entries can be put either into a single file or into separate files.
The four lists are the following:
- Sga-WhoCalled.ini/[BlackLists]/sBLFileWCBusy
  - List for those people who do not allow a WhoCalled SMS sent while he/she is busy.
  - Valid entries start below the "[BlackList - WCBusy]" line.
- Sga-WhoCalled.ini/[BlackLists]/sBLFileWCOther
  - List for those people who do not allow a WhoCalled SMS sent while he/she is not reachable.
  - Valid entries start below the "[BlackList - WCOther]" line.
- Sga-WhoCalled.ini/[BlackLists]/sBLFileNotifyA
  - List for those people who do not allow a NotifyMe SMS sent when his/her called party becomes available again.
  - Valid entries start below the "[BlackList - Notify (A)]" line.
- Sga-WhoCalled.ini/[BlackLists]/sWLFileNotifyA
  - Exception list for people who would be blacklisted by a range defined by sBLFileNotifyA (i.e. Generally subscribers of other operators are not allowed to get NotifyMe SMS but they can change their operators with MNP so they become own subscribers with a foreign number and they allowed to get NotifyMe SMS by now.)
  - Valid entries start below the "[BlackList - Notify (A) / Exceptions]" line.
- Sga-WhoCalled.ini/[BlackLists]/sBLFileNotifyB
  - List for those people who do not allow a NotifyMe SMS sent to others about his/her availability.
  - Valid entries start below the "[BlackList - Notify (B)]" line.
Each MSISDN in the lists must be placed in a separate line; MSISDN prefixes (e.g., "49170" for whole Germany-D1) are allowed.
Entries can be listed in an arbitrary order.
Remark to be displayed for a particular entry (subscriber or group) can be assigned with an equal sign (e.g., "3630934567 = this is my phone").
Comment lines should start as this one, i.e., with a semicolon; empty lines are also allowed and ignored.
Lists are loaded at start-up automatically, and can be reloaded later at any time:
- locally using the "[BlackLists]/Reload Content" menuitem on the user interface)
- from a remote client using the SgaWC_UDP_LoadBlackList utility.

An example

        [BlackList - WCBusy]
        3620=PGSM subscribers are banned

        ; it is a short remark here
        363093040
        36309304056 = this is my phone
        363093040491

        363156789012345678901234567890=abcdefghijklmnopqrstuvwxyz
        3670=VRAM is also banned
        363156789012345678901234567890 = This is the very same as the one two lines above.

Statistics

Statistics reports are concatenated in every quarter hour to a daily CSV file with the naming convention "SgaWCx_Stat_YYYYMMDD.csv" residing in the directory referred by INI/[Advanced]/sStatFilesPath. Statistics data represent the actual value of the particular counters incremented since software start-up. Hence hourly or daily statistics can simply be derived by focusing (grep'ing) onto the requested data.

Fields of statistics file:

Time: Actual timestamp of counter read-out.
SIP/INVITE_Rx: Number of received INVITE messages
ISUP/IAM_Rx: Number of received IAM's that look fine
ISUP/IAM_bad_Rx: Number of received IAM's without legible CagPN or RedGN/OriCN
MAP/SRI4SM_Tx: Number of sent SendRoutingInfoForSM MSU's
MAP/FwdSM_Tx: Number of sent ForwardSM MSU's (with the "InvisibleSMS")
MAP/ReportReq_Tx: Number of sent ReportSMDeliveryStatus MSU's
MAP/AlertSC_Rx: Number of received AlertSC or AlertSCWithoutResult MSU's
SMS_Busy: WhoCalled short messages sent in busy case
SMS_NotReachable: WhoCalled short messages sent in not-reachable cases (other than busy)
SMS_NotifyMe: NotifyMe short messages sent in not-reachable cases (other than busy)

Configuration (SgaWCx.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!)
[SS7 over GyX]
	sRemoteIPAddress	127.0.0.3	IP address of GyX_SCTP module
	wRemoteTCPPort	9068	TCP port of GyX_SCTP
	wConnectRetryDelaySec	3	Period of attempts to reconnect
[SS7 Advanced]
	szSS7LocalGT	38167100015	Global Title of this service centre, used as GT parameter in MAP messages sent to the HLR
	sSS7FakeGT	38167100015	Used in ForwardSM/SM-RP-OA as SCAddressOA; should usually be the same as the value of sSS7LocalGT
	sMCC	36	Calling number from the IAM is prefixed with sMCC and then put into a reportSM_DeliveryReport message as MSISDN
	dwChannelSeizedTimeOut	2	A speech channel is released after this time (time between ACM and REL)
	byISUPCongestionReleaseCause	42	Release cause value in the REL messages (42 - Switching equipment congestion)
	sInvisibleSMSFile	C:\Sga-WhoCalled\SgaWC_InvisibleSMS.sms	Loaded on-the-fly; applied in ForwardSM (except B-Number); defaults to c:\InvisibleSMS.sms
	bySS7smsSCTSTZ	0x40	TimeZone of ServiceCenter parameter (TP-Service-Centre-Time-Stamp) can be adjusted. (0x40 means GMT+1 hour. The value is interpreted as specified in GSM 03.40; can be set either as decimal or hexadecimal, defaults to 0x00.)
[SIP Settings]
	wLocalUDPport	5060	Local UDP where the module listens to the incoming SIP messages
	sInviteResponse_Busy	486 Busy Here	Response value for busy case
	sInviteResponse_NotReachable	480 Temporarily not available	Response value for not reachable case
	sInviteResponse_other	400 Bad Request (no redirection reason found)	Response value when no redicerction reason found in the Invite message
[SGAfiles]	Message saving feature currently is only for SIP, not for ISUP or MAP. ISUP and MAP messages can be saved through the GyX_SCTP module. Entries in this section are reloaded once per every second.
	sFilesPath	D:\SGAfiles	Path for SGA files. The content of the sFilesPath entry is considered when opening an SGA file. Leave (or change) sFilesPath entry empty not to write these file.
	sSigLinkID	SIP	sSigLinkID entry may consist of three characters
	dwFilePeriodMin	1440	Period of SGA files creation
[MSISDN Memory]
	dwCount	100000	Maximum number of existing MSISDN pairs for 'Not Reachable' case
	dwTimeOutSec	259200	Specifies a remembering time for 'Not Reachable' pairs in seconds. Pairs reaching this time will be forgotten.
	sBackupFile	c:\SgaWC_MSISDNMemoryBackupFile.bin	"MSISDN Memory" is saved at exit, and can optionally be reloaded at next start-up.
	byAutoloadBackupFile	2	Possible values are: 0 - means never load the saved MSISDN memory at startup 1 - means always load the saved MSISDN memory without asking 2 - means that at startup a dialog box appears asking whether load the saved MSISDN number or not (default).
[BlackLists]
	dwMaxEntriesEach	50000	Each lists can contain at most 50000 entries
	sBLFileWCBusy	C:\Sga-WhoCalled\SgaWCx_BL_WCBusy.lst	List for those people who do not allow a WhoCalled SMS sent while he/she is busy.
	sBLFileWCOther	C:\Sga-WhoCalled\SgaWCx_BL_WCOther.lst	List for those people who do not allow a WhoCalled SMS sent while he/she is not reachable.
	sBLFileNotifyA	C:\Sga-WhoCalled\SgaWCx_BL_NotifyA.lst	List for those people who do not allow a NotifyMe SMS sent when his/her called party becomes available again.
	sWLFileNotifyA	C:\Sga-WhoCalled\SgaWCx_WL_NotifyA.lst	Exception for `sBLFileNotifyA`
	sBLFileNotifyB	C:\Sga-WhoCalled\SgaWCx_BL_NotifyB.lst	List for those people who do not allow a NotifyMe SMS sent to others about his/her availability
	sRemoteRequestRemoteIPAddress	11.22.33.44	Accepts remote 'ReloadBlackLists' requests from the given IP address. (Can hold numeric Internet address only; default: empty, which means no restriction).
	wRemoteRequestLocalUDPPort	1967	UDP port when the application listens to the reload requests. (Suggested value for operation: 1967; default: 0, which means off)
[Advanced]
	wLogDetailLevel	3	(Equals to the listed order; refer to the `[Log]/Details` menu item!)
	dwMaxLinesInLogWindow	1000	Number of lines in the log window on screen
	sSMSPath	d:\SMSFiles	Defines the paths for storing created short messages in SMS files.
	sLogFilesPath	d:\LogFiles	Path for the LOG files
	sStatFilesPath	d:\StatFiles	Path for statistics reports
	sTrapFilesPath	d:\TrapFiles	Path for the SNMP Trap files to be sent to the NMC/NOC
	bAlternateTrapUID	False	Allows using fixed UIDs in SNMP traps (See SNMP trap list below for details)
[TimeSlots_X]			'Virtual' timeslots can be defined with the pointcode where from messages can arrive and the list of the circuit identifiers
	200	1,17,29,34	Messages using speech channel 1 or 17 or 29 or 34 can arrive from PC=200
[SMS Templates]			Here the SMSs can be preset which will be sent in the different cases
	sWCBusy	"Dear +#B, you are busy. +#A called you #N time(s), last on #D; please call him/her back!"	This text is put in the 'WhoCalled'SMS in 'Busy' cases
	sWCBusySenderMSISDN	36311234567	This field defines the sender of the SMS in Busy case. Sender can be numeric (normal MSISDN) or alphanumeric.
	byWCBusySenderNoA	0x91	The value from this entry is copied transparently into the Type-of-Address field(s) of the SMS PDU. Its value depends on what kind of `sWCBusySenderMSISDN` was set: 0x91 if the sender is numeric, 0xD0 if the sender is alphanumeric.
	sWCOther	"Dear +#B, you are other. +#A called you #N time(s), last on #D; please call him/her back!"	In other cases this text is sent to the unreachable subscriber
	sWCOtherSenderMSISDN	36311234567	This value will used as the sender of the SMS's in Other cases. Sender can be numeric (normal MSISDN) or alphanumeric.
	byWCOtherSenderNoA	0x91	The value from this entry is copied transparently into the Type-of-Address field(s) of the SMS PDU. Its value depends on what kind of `sWCOtherSenderMSISDN` was set: 0x91 if the sender is numeric, 0xD0 if the sender is alphanumeric.
	sNotify	"Dear +#B, you've tried to reach #N time(s) +#A, who is on again. Try to call him/her now!"	This notification SMS is transmitted to the subscriber who tried to reach another when he/she is as on again
	sNotifySenderMSISDN	YourOperator	This field defines the sender of the SMS in Notify cases. Sender can be numeric (normal MSISDN) or alphanumeric.
	byNotifySenderNoA	0xD0	The value from this entry is copied transparently into the Type-of-Address field(s) of the SMS PDU. Its value depends on what kind of `sWCNotifySenderMSISDN` was set: 0x91 if the sender is numeric, 0xD0 if the sender is alphanumeric.
	sDateTime	"%A, day %d of %B in the year %Y"	The date and time can be formatted by this entry put into the SMSs. For details see the next section!

SMS-text templates

valid SMS-template placeholders: #A, #B, #D, #N. (A complete example: "Dear +#B! +#A called you #N time(s), last at #D.")
- #A: the sender of the SMS
- #B: the recipient of the SMS
- #N: number of unsuccessful trying
- #D: date, its format can be set by sDateTime entry in the INI/[SMS Templates] section
percent sign ('%') character should not be used within the template
if an MSISDN is in nat'l (NoA=3) format, then it is prefixed with INI/[SS7 Advanced]/sMCC
placeholders in INI/[SMS Templates]/sDateTime:
- %a - Abbreviated weekday name
- %A - Full weekday name
- %b - Abbreviated month name
- %B - Full month name
- %c - Date and time representation appropriate for locale
- %d - Day of month as decimal number (01-31)
- %H - Hour in 24-hour format (00-23)
- %I - Hour in 12-hour format (01-12)
- %j - Day of year as decimal number (001-366)
- %m - Month as decimal number (01-12)
- %M - Minute as decimal number (00-59)
- %p - Current locale’s A.M./P.M. indicator for 12-hour clock
- %S - Second as decimal number (00-59)
- %U - Week of year as decimal number, with Sunday as first day of week (00-53)
- %w - Weekday as decimal number (0-6; Sunday is 0)
- %W - Week of year as decimal number, with Monday as first day of week (00-53)
- %x - Date representation for current locale
- %X - Time representation for current locale
- %y - Year without century, as decimal number (00-99)
- %Y - Year with century, as decimal number
- %z, %Z - Time-zone name or abbreviation; no characters if time zone is unknown
- %% - Percent sign
The # flag may prefix the formatting codes. In this case, the meaning of the format code is changed as follows:
- %#c - Long date and time representation, appropriate for current locale; for example: "Tuesday, March 14, 1995, 12:41:29"
- %#x - Long date representation, appropriate to current locale; for example: "Tuesday, March 14, 1995"
- %#d, %#H, %#I, %#j, %#m, %#M, %#S, %#U, %#w, %#W, %#y, %#Y - Remove leading zeros (if any)
Examples:
- "%H:%M:%S" ---> "12:42:28"
- "Today is %A, day %d of %B in the year %Y." ---> "Today is Tuesday, day 09 of May in the year 2006."

SNMP trap list

UID	Type	Text	Remarks	To Do
If `bAlternateTrapUID` is set to TRUE
9	CEA	`'SGA - Who Called v2.01' module is started.`	Sends a welcome message
9	CRI	`'SGA - Who Called v2.01' module has been shut down by operator.`	Sends a farewell WARning message	Start the `'SGA - Who Called v2.01'` module
90	CEA	`GyX: Connection to remote module established.`
90	CRI	`GyX: Connection to remote module is lost.`		Check the state of GyX module.
93	CRI	`Permanently could not open SMS files for writing.`	Tried to create SMS file 25 times, but all attempts failed	Check if there are SMS file in the path defined in the configuration file
93	CRI	`Failed to create an(y) SMS file.`	Generating temporary file name for SMS file failed	Check if the settings are correct in the `SS7MSMS.INI` configuration file or if there is the directory where the SMS files have to be placed
94	WAR	`Received an unexpected MSU, or its format is unknown.`		An MSU with unknown parameters received. (Wrong PC, CIC, GT, OperationCode.) Check the SS7 configuration.
If `bAlternateTrapUID` is set to FALSE
0	INF	`'SGA - Who Called v2.01' module is started.`	Sends a welcome message
0	WAR	`'SGA - Who Called v2.01' module has been shut down by operator.`	Sends a farewell WARning message	Start the module
++N	INF	`GyX: Connection to remote module established.`	When GyX connection is up first
++N	CRI	`GyX: Connection to remote module is lost.`		Check the state of GyX module.
N	CEA	`GyX: Connection to remote module established.`	When GyX connection is up after a disconnection
++N	CRI	`Permanently could not open SMS files for writing.`	Tried to create SMS file 25 times, but all attempts failed	Check if there are SMS file in the path defined in the configuration file
++N	CRI	`Failed to create an(y) SMS file.`	Generating temporary file name for SMS file failed	Check if the settings are correct in the `SS7MSMS.INI` configuration file or if there is the directory where the SMS files have to be placed

The Remote Client utility for reloading BlackLists
`("SgaWC_UDP_LoadBlackList")`

Features

The communication port for the 'ReloadBlackLists' remote request can be configured in SgaWCx.ini and SgaWC_UDP_LoadBlackList.ini files.
There is the possibility to apply a station restriction for the remote requests by setting [BlackLists]/sRemoteRequestRemoteIPAddress in "SgaWCx.ini"; if you leave this entry empty (which is the default setting), then properly formed remote requests are accepted regardless of the IP address.

Ways to reload black lists

There are two ways to reach the remote 'ReloadBlackLists' feature:

Using the provided simple utility "SgaWC_UDP_LoadBlackList.exe", which simply sends the required UDP packet to the "SGA - Who Called (SS7)" application, and can be invoked from the command line or from your batch file;
Creating an own application to send this UDP packet. The definition of the required UDP packet would provided on a request.

Configuration (SgaWC_UDP_LoadBlackList.ini) file settings

Section	Entry	Example	Meaning
[Advanced]
	sRemoteIPAddress	10.22.33.45	IP address of the machine where the Sga-WhoCalled application is running on.
	wRemoteUDPPort	1967	Communication port where the reload request are sent to.

The 'Who Called' module for Sigtran("SgaWCx")

Features

User interface

The main menu

The bottom status-line

Black list feature

An example

Statistics

Fields of statistics file:

Configuration (SgaWCx.ini) file settings

SMS-text templates

SNMP trap list

The Remote Client utility for reloading BlackLists("SgaWC_UDP_LoadBlackList")

Features

Ways to reload black lists

Configuration (SgaWC_UDP_LoadBlackList.ini) file settings

The 'Who Called' module for Sigtran
`("SgaWCx")`

The Remote Client utility for reloading BlackLists
`("SgaWC_UDP_LoadBlackList")`