Network-internal short dialing numbers
======================================

In addition to obviously necessary support for standard E.164 phone numbers
(assigning real NANP numbers to local subscribers, calling any other NANP
numbers whether they are local or not, calling international numbers outside of
NANP), ThemWi system sw implements an additional, entirely private and network-
internal, numbering space for 4-digit short dialing numbers.  Any time a ThemWi
GSM subscriber dials a number that consists of only (exactly) 4 digits, that
short number is looked up in this private ThemWi-defined numbering space.

In the present implementation, three different types of numbers can exist in
this private, network-internal short 4-digit number space, each described in
its own section below.

Abbreviated NANP numbers
------------------------

If you have a bunch of real NANP numbers from the same NPA-NXX prefix, you can
enter them into the master database of locally owned numbers (see
Number-database article) using this notation:

prefix NPA-NXX allow-abbrev

If the 'allow-abbrev' flag keyword is included, each NANP number entered under
this prefix (each following suffix line) gets added to the short 4-digit number
space: in addition to the standard option of dialing all 10 digits, the same
number can be reached by dialing only the last 4 digits, considered to be the
"station" part of the number (under a given "exchange") per NANP rules.

You do need to be careful with this facility, as conflicting numbers are not
allowed.  Enabling allow-abbrev mode makes sense under the following conditions:

1) You have one preferred NPA-NXX prefix, presumably corresponding to your
   geographic locality, and you reserve all of your native numbers (via BulkVS
   portal or equivalent from other providers) from that one preferred prefix.
   In this case you should set allow-abbrev on your "home" prefix, but whenever
   you have to add non-native numbers to your network (customer port-ins etc),
   those don't get the abbreviated dialing option, only full10.

2) You may enable allow-abbrev for more than one prefix if you reserve your
   numbers from multiple prefixes in a judicious manner, selecting 4-digit
   suffixes that don't overlap across your two (or more) prefixes.

Internal test numbers (ITNs)
----------------------------

An ITN is a 4-digit short dialing number (meaningful only inside your local GSM
network) that is assigned to a GSM subscriber and entered as such (4 digits
only) into OsmoHLR subscriber database.  When ITNs are used, a GSM subscriber
who gets an ITN is *not* given a real NANP telephone number, and thus cannot
make any calls to or receive any calls from the outside world.

Our own Themyscira Wireless operation does not presently use any ITNs.  This
facility was invented before we realized how cheap NANP numbers can be when they
are ordered "raw" or "bare": a basic reservation of a real 10-digit NANP number
from BulkVS *without* E911 provision and without SMS capability (regular,
non-emergency calls only) costs only $0.06 (6 cents) per number per month.  At
this insanely cheap price, it makes no sense to introduce ITNs, it is easier to
give a real NANP number to every GSM subscriber including lab-use-only test
SIMs - but the Mother does not believe in removing implemented functionality
without extremely strong justification, hence support for ITNs remains in our
software.

To define an ITN, enter a line like this into your master database of locally
owned numbers:

itn XXXX

where XXXX is the 4-digit number to be defined as an ITN.

Test sink numbers
-----------------

A test sink number is a private, network-internal 4-digit number that is
intended to serve as a destination or "sink" for test calls and test SMS.  Any
calls dialed to a test sink number will be handled by a special process which
only exists for that purpose (remains to be implemented), and any SMS sent to a
test sink number will be simply written into log-structured storage without any
further delivery to anywhere.  The purpose of test sink numbers is to exercise
outgoing call and outgoing SMS functions of GSM MS without needing a "real"
second party to serve as the recipient.

To define a test sink number, enter a line like this into your master database
of locally owned numbers:

test-sink XXXX

where XXXX is the 4-digit number to be defined as a test sink.

Historical perspective
======================

In the original design of ThemWi system sw, 4-digit short dialing numbers were
intended to be ITNs only, forming an internal-only numbering space that is
entirely disjoint from public E.164 numbers.  Operating on the assumption that
external NANP numbers would be expensive, the design model was that every GSM
subscriber would have an ITN, and then additionally some subscriber lines (those
belonging to human users, rather than lab test SIMs) would be given real
external phone numbers in NANP.  The fixed 4-digit length for internal short
numbers was chosen, contrary to the apparent custom in Osmocom community of
using 5-digit numbers for such internal "extensions", because a 5-digit number
can be a valid SMS short code in USA, and human users of Themyscira Wireless GSM
service need to be able to access these SMS short-code public services just like
customers of any other cell carrier in this country.

Shortly after beginning to implement the initial design described above, we
discovered how cheap real NANP numbers actually are, and got a batch of numbers
from our choice of NPA-NXX prefix.  We were then sitting on a batch of numbers
that had the same 6-digit prefix, but different 4-digit suffixes, and that was
how we got the idea of abbreviated dialing numbers: instead of completely
made-up ITNs, allow "home block" NANP numbers to be dialed (from one local GSM
phone to another) by just the last 4 digits of the external, globally valid
E.164 number.

Test sink numbers are our latest-so-far addition to the network-internal 4-digit
dialing number space, and we have yet to implement them beyond mere definition
in the local number database.