TSP Lab	SgaWC_SS7 - The 'Who Called' Module	SgaWC_SS7

The 'Who Called' module for SS7
`("SgaWC_SS7")`

Features

Connects via MAP over SS7 to the MSC
Maintains mid-level SS7 functions (SLTM, SNM, etc.)
Handles real and virtual speech channels
Handles connections with the HLR using MAP (Phase 1 or Phase 2) protocol over SS7
Answers an ACM for IAMs and after a given period sends a REL with adjustable release cause value
Creates 'WhoCalled' SMS in 'Busy' cases for the called subscribers
Sends 'reporSM_DeliveryStatus' to the HLR in 'Not Reachable' cases
Receives and answers the 'alertServiceCentre' messages from the HLR
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]
	A: Allow MTP2 auto-connecting	(left-side )	Allows automatic (re-)connecting to the MSC on SS7 channel A
	A: Disconnect MTP2 now		Immediately disconnects SS7 channel A from the MSC
	A: Send BLO for all speech channels		Blocks all speech channels on PCM 'A' by sending 'Blocking circuit' message
	A: Send RSC for all speech channels		Resets all speech channels on PCM 'A' by sending 'Reset circuit' message
	A: Send UBL for all speech channels		Unblocks speech channels on PCM 'A'
	B: Allow MTP2 auto-connecting	(right-side )	Allows automatic (re-)connecting to the MSC on SS7 channel B
	B: Disconnect MTP2 now		Immediately disconnects SS7 channel B from the MSC
	B: Send BLO for all speech channels		Blocks all speech channels on PCM 'B' by sending 'Blocking circuit' message
	B: Send RSC for all speech channels		Resets all speech channels on PCM 'B' by sending 'Reset circuit' message
	B: Send UBL for all speech channels		Unblocks speech channels on PCM 'B'
	X: Send BLO for all speech channels		Blocks all virtual speech channels
	X: Send RSC for all speech channels		Resets all virtual speech channels
	X: Send UBL for all speech channels		Unblocks all virtual 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 (`SgaWC_SS7.ini`) file
[DSP Debug]
	Show DSP debug info for SS7(A) now		Shows debug information for SS7 channel A in the status line of the program window
	Show DSP debug info for SS7(B) now		Shows debug information for SS7 channel B in the status line of the program window
	Clear debug info line		Clears the debug information from the status line of the program window

The bottom status-line

PCM: status of the PCM frame in the receiver connection (its color is gray in normal works, red refers to error)
MTP2: SS7/MTP2 status of the connection (its color is gray in normal works, red refers to error)
bps: LSSU and MSU bits received in the last second
permil: idle time of the given program thread in the last second (ms)
Error counters:
- pcm: number of PCM disconnections (physical problems)
- mtp2: number of SS7/MTP2 disconnections
- dsp: number of communication errors between DSPs of the Sga47 card and the program
- msu: received an uninterpretable or misaddressed MSU (wrong Point Code)
- tcap: number of wrong TCAP messages
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)
MSU's buffered for Tx: number of MSU's buffered for transmitting

Status of timeslots:
- white: unused
- yellow: SS7 signaling timeslot
- black: speech channel
- green: speech channel, ready
- red: speech channel blocked
- purple: allocated speech channel (IAM{CIC})
- the 0'th timeslot is synchronization channel

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 "SgaWC_SS7_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.
A:IAM_Rx: IAM's that look fine, received on channel 'A'
A:IAM_bad_Rx: IAM's without legible CagPN or RedGN/OriCN, received on channel 'A'
A:SRI4SM_Tx: SendRoutingInfoForSM MSU's, sent on channel 'A'
A:FwdSM_Tx: ForwardSM MSU's (with the "InvisibleSMS"), sent on channel 'A'
A:ReportReq_Tx: ReportSMDeliveryStatus MSU's, sent on channel 'A'
A_AlertSC_Rx: AlertSC or AlertSCWithoutResult MSU's, received on channel 'A'
B:IAM_Rx: IAM's that look fine, received on channel 'B'
B:IAM_bad_Rx: IAM's without legible CagPN or RedGN/OriCN, received on channel 'B'
B:SRI4SM_Tx: SendRoutingInfoForSM MSU's, sent on channel 'B'
B:FwdSM_Tx: ForwardSM MSU's (with the "InvisibleSMS"), sent on channel 'B'
B:ReportReq_Tx: ReportSMDeliveryStatus MSU's, sent on channel 'B'
B_AlertSC_Rx: AlertSC or AlertSCWithoutResult MSU's, received on channel 'B'
SMS_Busy: WhoCalled short messages sent in busy case
SMS_NotReachable: WhoCalled short messages sent in not-reachable cases (other than busy)
SMS_NotifyM: NotifyMe short messages sent in not-reachable cases (other than busy)

Configuration (SgaWC_SS7.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!)
[SGA-47 Card]
	wBaseAddress	0xD800	The I/O address of the SGA-47 card, selected with DIP switches on the card
	sMTP2ObjectFile	MTP2_47 v2.06 (+00 dB 120 Ohm).obj	The file name of the firmware program
[SS7]
	bSS7AAllowMTP2AutoConnect	True	(Refer to the `[SS7]/A: Allow MTP2 auto-connecting` menu item!)
	bSS7BAllowMTP2AutoConnect	True	(Refer to the `[SS7]/B: Allow MTP2 auto-connecting` menu item!)
[SS7 Advanced]
	bEmergencyMTP2Startup	True	Enables MTP2 Emergency Startup option. Provides faster MTP2 establishing.
	bySS7ATimeSlot	1	SS7 signaling time slot on the PCM A
	bySS7BTimeSlot	1	SS7 signaling time slot on the PCM B
	wSS7LocalPointCode_NI2	130	Local SS7 point code for messages with national numbering (Network Indicator = 2)
	wSS7LocalPointCode_NI3	130	Local point code for messages with international numbering (Network Indicator = 3)
	szSS7LocalGT	38167100015	Global Title of this service centre, used as GT parameter in MAP messages sent to the HLR
	wSS7ARemotePointCode	8579	Point code of the remote system (MSC) what the SgaWC_SS7 connected to by PCM 'A'
	wSS7BRemotePointCode	8579	Point code of the remote system (MSC) what the SgaWC_SS7 connected to by PCM 'B'
	wSS7ACICOffset	0	Offset for circuit identifiers in the PCM 'A' when they have higher number than 31
	wSS7BCICOffset	32	Offset for CICs in the PCM 'B' when they have higher number than 31
	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)
	sSS7FakeGT	38167100015	Used in ForwardSM/SM-RP-OA as SCAddressOA; should usually be the same as the value of sSS7LocalGT
	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.)
	wThreadPeriod	100	Time period when idle threads are given CPU time slice (given in milliseconds)
[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\SgaWC_SS7_BL_WCBusy.lst	List for those people who do not allow a WhoCalled SMS sent while he/she is busy.
	sBLFileWCOther	C:\Sga-WhoCalled\SgaWC_SS7_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\SgaWC_SS7_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\SgaWC_SS7_WL_NotifyA.lst	Exception for `sBLFileNotifyA`
	sBLFileNotifyB	C:\Sga-WhoCalled\SgaWC_SS7_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_A]			This section contains the list of timeslots defined as speech channels in PCM 'A'
	wTS#02	1	The 2nd timeslot is used as a speech channel.
[TimeSlots_B]			This section contains the list of timeslots defined as speech channels in PCM 'B'
	wTS#03	1	The 3rd timeslot is used as a speech channel.
[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 (SS7) v0.92' module is started.`	Sends a welcome message
9	CRI	`'SGA - Who Called (SS7) v0.92' module has been shut down by operator.`	Sends a farewell WARning message	Start the `'SGA - Who Called (SS7) v0.92'` module
90	CEA	`SS7(A)/MTP2 connection is up.`
90	CRI	`SS7(A)/MTP2 connection has died.`		Check whether PCM connection is correct
90	CRI	`SS7(A)/MTP2 connection has died. (operator)`		Check if PCM connection is correct
90	CRI	`SS7(A)/MTP2 connection has died. (PCM also)`		Check if PCM connection is correct
91	CEA	`SS7(B)/MTP2 connection is up.`
91	CRI	`SS7(B)/MTP2 connection has died.`		Check whether PCM connection is correct
91	CRI	`SS7(B)/MTP2 connection has died. (operator)`		Check whether PCM connection is correct
91	CRI	`SS7(B)/MTP2 connection has died. (PCM also)`		Check if PCM connection is correct
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 (SS7) v0.92' module is started.`	Sends a welcome message
0	WAR	`'SGA - Who Called (SS7) v0.92' module has been shut down by operator.`	Sends a farewell WARning message	Start the module
0	INF	`SS7(A/B)/MTP2 connection is up.`	When connection A/B is up first
++N	CRI	`SS7(A/B)/MTP2 connection has died.`		Check if PCM connection is correct
++N	CRI	`SS7(A/B)/MTP2 connection has died. (operator)`		Check whether PCM connection is correct
++N	CRI	`SS7(A/B)/MTP2 connection has died. (PCM also)`		Check if PCM connection is correct
N	CEA	`SS7(A/B)/MTP2 connection has died.`	When connection A/B is up after a down
++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 SgaWC_SS7.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 "SgaWC_SS7.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 SS7("SgaWC_SS7")

Features

User interface

The main menu

The bottom status-line

Black list feature

An example

Statistics

Fields of statistics file:

Configuration (SgaWC_SS7.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 SS7
`("SgaWC_SS7")`

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