1. EAGLE Application Processor Provisioning Database Interface User's Guide
  2. PDBI Request/Response Messages

3 PDBI Request/Response Messages

This chapter describes available requests and the possible responses for PDBI request/response messages.

Overview

This chapter defines the Database Interface (PDBI) request and response messages. The messages are listed in alphabetical order.

Provisioning

Provisioning clients connect to the EPAPs through the PDBI. The PDBI consists of commands and their parameters, which allow you to define the messages that provision the G-Flex, G-Port, INP, EIR, A-Port, and/or IS41 GSM Migration features and allow the retrieval of feature data.

PDBI messages are sent across a TCP/IP socket. The client application (defined by the customer) is responsible for connecting to the Provisioning Database Application (PDBA) well-known port and being able to send and receive the defined messages.

Note:

The customer must write his own client application that uses the PDBI to communicate with the PDBA.

PDBI messages (requests and responses) are NULL-terminated strings, which allows sending and receiving the messages from any language that has socket capability (for example, Perl or Java).

Message Definitions

Each message definition consists of one request and one or more responses. A request is a message sent by the client to the client application to invoke a service. A response is a message returned to the client by the client application to confirm that the a requested service has been invoked, the transaction has been completed, or a connection has been established.

Request IDs

Each request has an integer identification (iid) as its first element. The client can use the iid to match returned responses with the original requests The integer is expressed as a decimal number in ASCII and has a range from 1 to 4294967295. The iid is optional. If an iid is not provided on a request, the corresponding response also does not have one.

Optional Parameters

Optional parameters are surrounded by square brackets [ ] in the syntax examples. If you want to omit an optional parameter from the request command, omit the entire field including the label, value, and following comma. Do not leave a comma in as a place holder. The parameter labels in the fields that are sent on the request provide enough information to determine which parameters were omitted. However, the field labels must be present on all specified parameters.

For example, examine the following syntax: 

 sample_msg(field1 #, field2 #, [field3 <yes/no>], field4 <0..255>)

If you want to omit the field3 parameter of a request, you might enter the request command using the following syntax: 


sample_msg(field1 123, field2 456, field4 128)

Common Response Format

Responses use the same basic format.

If an integer identification (iid) was provided in the request, the response iid corresponds to the iid of the original request. A return code indicates either success (zero) or failure (non-zero). See Appendix A, “PDBI Message Error Codes, for a mapping between the return code labels described in this section and the real integer value.

Additionally, an optional data element returns request-specific return information.

Each defined response declares the errors it returns (with their meanings) and what the data section should look like for each error. If a response does not require a data section (meaning it is just a simple ACK or NAK), the data section does not appear at all. In that case, the last item in the response is the return code (rc).

The following example shows the syntax of the common response format. This format applies to all response messages described in this chapter unless stated otherwise. 


rsp ([iid <iid from request>,] rc <return code>, [data (. . .)])

The format of each command response is shown in this chapter. The response information for each command is described in detail in Commands User's Guide.

Number Prefixes

The PDBA has the concept of default number prefixes. These are PDBA parameters that are configurable from Administration Guide. There are two number prefixes, one for DNs and DN Blocks and the other for IMSIs. They are completely separate and can be set or not set independently. When set, the number prefix values are automatically prepended to all DNs and DN Blocks or IMSIs (depending on the prefix type) in PDBI requests. The values are also stripped off of the DNs, DN Blocks and IMSIs in PDBI responses.

For example, if the DN Prefix is set to “34” in the UI and then an ent_sub request is sent to create DN 12345, the actual DN stored in the database and sent to the EAGLE is “3412345”. If a PDBI query is done for DN “12345” while the number prefix is still “34”, the “3412345” is found in the database, but only the DN value “12345” is returned in the PDBI response.

It is possible to override a default number prefix. The symbol ‘#’ at the beginning of a DN, DN Block, or IMSI means that it is the actual value and that no number prefix should be applied. This can occur in both requests and responses.

For example, if the PDBI client sends a value “#12345” in a request, it means that he literally means the value “12345”, not “3412345” (assuming that “34” is the that type's number prefix). If a PDBI response comes back with a “#12345”, it means that the DN, DN Block or IMSI literally had the value “12345”, not “3412345” (still assuming that “34” is the Number Prefix). A response with a “#” value is returned if a DN, DN Block or IMSI is found in the database that did not match its type's number prefix.

It is important to note that the “#” number prefix override is only valid for DNs, DN Blocks, and IMSIs. The “#” symbol at the beginning of any other parameter value does not parse.

Since the number prefix and the number prefix override apply to all requests and responses that have DNs, DN Blocks or IMSIs, it is not mentioned on each command separately.

The Number Prefix must conform to syntax rules for DN, NSDN, and DN Block values. Prefix lengths must not exceed 10 digits.

Common Responses

The response code examples given for each message indicate those codes that are specific for that message. Other response codes may apply, such as the more general error responses like PDBI_NOT_CONNECTED, PDBI_NO_ACTIVE_ TXN, PDBI_NOT_FOUND, PDBI_BAD_ARGS. These are not repeated for each message for simplicity.

No command can be issued until a connection has been established by issuing the connect request to a PDBA. This restriction includes data provisioning commands such as ent_sub, rtrv_sub, etc., as well as query commands such as status, dump_conn, etc.

Common Response Messages

Because the PDBI is a string-based API, all requests can return a Parse Failed response message or a Bad Argument response message.

Parse Failed Response

The Parse Failed response message is identified by return code PARSE_FAILED. This response message indicates a syntactical problem with the command received and can have a data section present to provide more information about the parse failure. Table 3-1 lists possible reasons for parse failures.

If the data section exists, two optional parameters are possible. The first parameter is a reason text string stating explicitly what was wrong with the request. The second parameter is a location string containing the place where the error occurs and, surrounded by curly braces, the portion of the original request that contained the error. If no specific information is available, the data section is not present in the response.

The following example shows the syntax of a Parse Failed response message: 


data ([reason “Missing comma”], [location “XXXXXXX{} dn XXXXXXXXX”])

Table 3-1 Parse Failure Reasons

Reason Description

Unknown request verb

The request verb did not match any of the known commands.

Space required

A white space character was missing after some element of the request.

Missing paren

An opening or closing parenthesis was missing.

Invalid value

An invalid value was provided for one of the parameters.

<name of parameter> parameter expected

Some mandatory parameter was missing.

Multiple <name of parameter> found

Multiple occurrences of a parameter were found that does not allow multiple occurrences.

Unknown parameter

An unknown parameter was found.

Missing comma

A comma was missing after a parameter.

Value expected

A parameter label was found with no value following it.

Duplicate parameter

A parameter that should have occurred only once was found more than once.

Numeric value too large

The value specified for a numeric parameter specified a number greater than the maximum integer.

Bad Arguments Response

The Bad Arguments response message is identified by return code BAD_ARGS. This response message indicates a semantic problem with the command received (for example, missing mandatory parameters or invalid parameter combinations). The data section of a Bad Arguments response message has a reason string that indicates what problem was encountered.

The following example shows the syntax of a Bad Arguments response message: 


data (reason "No version provided")

Transaction Too Big Response

The internal EAGLE RTDB imposes a transaction size limit on the PDBA. In order to ensure that the PDBA and the EAGLE databases are truly equivalent, this limit must be propagated by the PDBA onto the PDBI clients. As a result, all database changing commands that occur within a write transaction have the potential to fail with a TXN_TOO_BIG error.

The transaction size limit is 200. It limits the number of modifications to the EAGLE database. The limit is 200 EAGLE RTDB updates. Unfortunately, this may not have a one to one correlation to the PDBI update commands. This is because a single PDBI command can result in several changes to the underlying database.

For example, a single PDBI command ent_sub, which contains IMSI 12345, DN 67890, DN 67891, and SP 101010, is performed by two EAGLE database commands, one for the IMSI and one for the DNs. The worst case number of EAGLE database commands that can occur due to one PDBI command is nine if the force parameter is not used. If the force parameter is set to yes, the highest possible number of EAGLE database commands in a single PDBI command is 17.

Multiple Segmented Responses

For some responses, it is possible that all of the data cannot be returned in one response. In this case, multiple responses for the same request are returned. The first through (N-1)th response have a return code of PARTIAL_SUCCESS to indicate that there should be more following them. The Nth response has the return code SUCCESS to indicate that it is the final response. Multiple responses also use the segment parameter at the beginning of the data section to allow the client to know that no responses have been missed. The segment parameter value starts at one for the first response and is incremented by 1 in each subsequent response for that request up to and including the final response that contains the SUCCESS return code. For consistency, the segment parameter is also present in single message responses with the value of 1.

Errors Not Returned to Client

Two return codes are not returned to a PDBI client. They are PDBI_INTERRUPTED and PDBI_UNIMPLEMENTED.

  • PDBI_INTERRUPTED is used internally to cancel requests that are in progress if the PDBI client abnormally disconnects. Since the return value is only used when the connection is broken, obviously the return code cannot be returned to the client.

  • PDBI_UNIMPLEMENTED is used during development of new features and commands to allow a valid return from commands that have been defined but are not implemented yet. Since the PDBA currently implements all of the commands described in this specification, the return code cannot be returned to the client.

Service Module Card Report

The PDBA keeps track of the status of the Service Module cards that it has connectivity to in the customer's network. Each card reports its information to the PDBA at regular intervals. The PDBA makes this information available to the PDBI clients in a Service Module card Report. The Service Module card Report can be requested by the client in several ways. These ways are spelled out in various commands that actually do the requesting. In all cases, the content and structure of the Service Module card Report is the same. The intent of the Service Module card Report is to inform the receiver what percentage of Service Module cards are at a specific database level. This information can be used by the client to determine when enough Service Module cards have a specific update to consider it safe for traffic.

The report includes the database level being reported on, the percentage of Service Module cards that have that level, and the total number of known Service Module cards. Also included is a list of all Service Module cards whose level did not meet or exceed the mentioned level. For each card in this list, the report provides the CLLI, card location, database status, and database level. If the database status is "loading", a percent loaded status is shown.

The client can either receive this report as a response to the rtrv_dsmrpt request, or it may be periodically received asynchronously if the client specifies the appropriate connect parameters. When the report is sent as a response to a normal synchronous request, the message begins with the normal rsp(…) label. However, when the report is sent as an asynchronous message, it begins with dsmrpt(…) to help identify that this is not a response to any recent request sent.

Messages

The messages described in this section are defined by commands and their parameters defined in the PDBI.

Connect

After a client has established a socket connection with the PDBA on its well- known port (5873), the client must issue a Connect request message. The PDBA returns a response message that indicates whether it is capable of accepting a new connection. There is a limit to the number of PDBI connections; the default is 16 clients. The connect command defines the Connect message.

If an attempt is made to connect more than the current client limit, a response is returned to the client: PDBI_TOO_MANY_CONNECTIONS. After the response is returned, the socket is automatically closed.

Note:

Although the default limit is 16 PDBI connections, Oracle is able to configure and support up to 128 connections. If more than 16 concurrent client connections are required, contact My Oracle Support for more information.

Request

The Connect request message is issued by the client to request a connection to the PDBA.

Parameters :

version

(Optional) Informs the PDBA of the API version this client application knows. This parameter decides whether or not the client application can successfully communicate with the PDBA.

Values:

1.0

rspsize

(Optional) Allows the client to specify the maximum size in Kilobytes of responses that the PDBA sends back. This parameter ensures that retrieve requests that result in a large number of instances being returned come back in manageable-sized responses to the client.

Values:

1 – 32 (default = 4)

switchactn

(Optional) Allows the client to specify what action is to be taken if the Active or Standby status of the PDBA changes as the result of a Switchover request.

Values:

none – No action taken (default)

close– Terminate this connection by closing the socket

endchar

(Optional) Allows the client to specify what character the PDBA uses to terminate responses.

Values:

null – Responses terminated with a NULL (\0) character (default)

newline– Responses terminated with a newline (\n) character

idletimeout

(Optional) Allows the client to specify the amount of time that the connection can remain idle before the PDBA should terminate it.

Values:

none – Connection is never terminated by PDBA for idleness. (default)

1 – 44640 – Terminate this connection after this many idle minutes.

[00-44640]:[00-59] – Terminate this connection after this many idle minutes and seconds. Limit is 44640:00.

txnmode

(Optional) Transaction mode allows the client to specify whether this connection operates in single transaction or normal transaction mode. This selection determines whether update requests can be sent individually or require the use of begin_txn and end_txnboundaries, to be considered write transactions on their own and allowed.

Values:

normal – All updates must be specified inside begin_txn and end_txn boundaries, which is the ‘normal transaction mode.’ (default)

single – Individual update requests are their own transactions. The use of begin_txn and end_txn boundary commands is not required in single transaction mode.

dsmrpt

(Optional) Allows the client to specify whether or not it wants to receive the asynchronous Service Module card Report messages.

Values:

no – The Service Module card Reports are not wanted (default).

yes – The Service Module card Reports are wanted.

dsmrptperc

(Optional) Allows the client to specify what percent to use in the Service Module card Report. This overrides the system wide default Service Module card Report percent value for this one connection.

Values:

1 – 100

dsmrptfreq
(optional) Allows the client to specify how often, in seconds, that the connection wants to receive the SM Report. This overrides the system wide default SM Report frequency value for this one connection. This parameter is only meaningful if dsmrpt has been specified as yes.

Note:

If a connection is configured to send asynchronously SM Reports and processes a command that takes a long time, SM Reports will be suspended until after the long running command is completed. For example, if a client connects with a dsmrptfreq of 1 and then requests a retrieve of millions of DNs, the SM Reports will be suspended until the retrieve command has completed. Once the SM Reports resume they will continue at the configured frequency..
Values:

1 – 86400 – Send the Service Module card Report in this many seconds.

Request syntax : 

Connect([iid XXXXX,] [version 1.0], [rspsize <1..32>], [switchactn <none/close>],        [endchar <null/newline>], [idletimeout <none/1..44640/[00-44640]:[00-59]>], [txnmode <normal/single>],        [dsmrpt <no/yes>], [dsmrptperc <1..100>], [dsmrptfreq <1..86400>])

Note:

The limit is 44640:00.

Response

The Connect response message indicates whether or not the PDBA is capable and willing to accept a new connection. If the connection is accepted, the data section in the response indicates the connection ID (iid) that was assigned and whether the PDBA connected to was running as the Active or Standby PDBA.

The return codes listed in this topic indicate the result of the Connect request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-2 Connect Response Return Codes

Return Code Text Description Data Section Contents
0

SUCCESS

Everything worked.

The assigned connection id and Active status are returned.

data (connectId ########, side active/standby)

1003

ALREADY_CONNECTED

A connect request was sent on a socket that already had an established connection.

NONE

1012

INVALID_VALUE

One of the fields specified had an invalid value.

The offending field is returned in the data section:

data (param <field label>)

1023

UNKNOWN_VERSION

The specified version is not known or not supported.

NONE

Disconnect

The Disconnect message is required to disconnect from the PDBA. The disconnect command defines the Disconnect message.

Request

The Disconnect request message is issued by the client to request a disconnect from the PDBA. This request tells the PDBA that the client has finished and allows the PDBA to clean up any connection-related data. If the client has a transaction open, the transaction is automatically aborted and any updates in the transaction are backed out. All Disconnectrequests result in the connection being broken.

Note:

The PDBA behavior is the same if the client neglects to send this request and just closes the socket, or if the client abnormally terminates and the operating system closes the socket.

Request syntax : 


disconnect([iid XXXXX])

Response

The Disconnect response message indicates either that the disconnect was successful without problems or that the disconnect was achieved through aborting a still-active transaction. Aborting an active transaction can occur because there were issues on the PDBA while cleaning up.

The return codes listed in Table 3-3 indicate the result of the Disconnect request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-3 Disconnect Response Return Codes

Return Code Text Description Data Section Contents

0

SUCCESS

Everything worked.

NONE

1010

ACTIVE_TXN

There was a transaction still active. It was aborted.

NONE

Begin Transaction

The Begin Transaction message starts a read or write transaction, which is required for all data-related commands (to create, update, delete, or retrieve subscriptions). A client connection can only have one transaction open at a time. The begin_txncommand defines the Begin Transaction message.

The following commands are not required to be issued from within a transaction: switchover, status, dump_conn.

Begin Transaction Request

By opening a read transaction, the client indicates to the PDBA that only data querying requests are sent; no database-changing requests (create, update, or delete) are sent. Any database-changing requests sent in a read transaction return a failure. Multiple client applications can have read transactions open at the same time. Responses from querying requests are sent back to the client immediately. There is no need to end the read transaction until you are through sending requests. Read transactions can be sent to either the Active or Standby PDBAs.

Take care when opening a read transaction on the standby PDBA. While two PDBAs are communicating normally, the data on the standby is valid. However, if the connection between the two PDBAs is broken and they cannot communicate, the information contained on the standby PDBA does not contain the new updates written to the active PDBA while the connection was broken. Thus in this case, data obtained from a read transaction on the standby PDBA would not be current and accurate information.

When the connection is re-established, the standby PDB is automatically re-synched to the current level of the active PDB. It is possible to achieve greater performance by sending read transactions to the standby PDB and write transactions to the active PDB. However, the precautions noted above should be considered.

By opening a write transaction, the client informs the PDBA that the database is updated in some way. After opening a write transaction, the client can send database-changing requests. Each command is evaluated for validity and cached locally.

Note:

The commands are not saved in the database or sent to the RTDB until the write transaction is ended.

The commands within the transaction can also be aborted (or rolled back) with an abort_txn command any time before the transaction is ended with the end_txn command. Only one client is allowed to open a write transaction at a time. Write transactions can be opened only on the Active PDBA. Attempts to open a write transaction on the Standby PDBA result in an error response.

It is possible for a client to make querying requests inside a write transaction. In this case, it is important for the client to remember that the data returned can reflect any updates that the write transaction has made so far but not yet committed. If the write transaction is aborted, the data retrieved from the query might no longer be valid.

The begin_txn command defines the Begin Transaction request message.

Parameters :

type

(Mandatory) Type of transaction to open.

Values:

read or write

timeout

(Optional) How many seconds to wait for the write transaction if another connection already has it.

Values:

0 (return immediately if not available; default)

1 - 3600 seconds

Request syntax : 


begin_txn([iid XXXXX,] type <read|write>, [timeout <0..3600>])

Begin Transaction Response

The return codes in Table 3-4 indicate the result of the Begin Transaction request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-4 Begin Transaction Response Return Codes

Return Code Text Description Data Section Contents

0

SUCCESS

Everything worked.

NONE

1005

WRITE_UNAVAIL

Another client already has a write transaction open. This is returned only to clients who have WRITE access permissions.

Clients who have only READ access receive NO_WRITE_PERMISSION even when another write transaction is open.

The IP address information of the client that already has the write transaction.

data (id <connection id>, ip <ip addr>, port <port num>)

1006

NO_WRITE_PERMISSION

The PDBI client making the connection does not have WRITE access permissions.

NONE

1008

STANDBY_SIDE

An attempt to open a write transaction occurred on the Standby PDBA.

NONE

1010

ACTIVE_TXN

A read or write transaction is already open on this connection.

NONE

1012

INVALID_VALUE

One of the fields specified had an invalid value.

The offending field is returned in the data section:

data (param <field label>)

End Transaction

The End Transaction message completes a read or write transaction. The behavior depends on whether the active transaction was a read or write transaction. The end_txn command defines the End Transaction message.

End Transaction Request

For a read transaction, the End Transaction request message informs the PDBA that it is done making queries. There are no database commitment.

For a write transaction that had successful updates, the End Transaction request message causes the database changes to be committed and sent to the RTDB. The new database level is returned in the data section of the response. The updates are not committed to the PDB until the end_txn command is received.

If none of the updates was successful, a NO_UPDATES code is returned, and the dblevel does not change. If any one of the commands was successful, a SUCCESS code is returned, and the dblevel is incremented. Note that the dblevel is incremented to the same value following a transaction with successful updates regardless of whether all updates were successful or only one.

The dblevel indicates the database level of the destination after the database action has occurred. It is incremented after every write transaction. The level is incremented by one after each successful write transaction, regardless of how many commands are sent in the transaction or whether the commands are creates or deletes. This value is used by the Service Module cards to check consistency with the RTDB.

Request syntax : 


end_txn([iid XXXXX])

End Transaction Response

The End Transaction response message signals that the database update is done. This response does not imply anything about whether or not the updates have made it to the RTDB yet. If the response contains the SUCCESS return code, then the update was successfully committed in the PDB. If any failure response is returned, the database commit failed. The end_txn request causes the transaction to end regardless of whether any updates were actually made to the PDB.

The return codes listed in Table 3-5 indicate the result of the End Transaction request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-5 End Transaction Response Return Codes

Return Code Text Description Data Section Contents

0

SUCCESS

Database update was successful.

If the transaction type was write, the new database level is returned.

data (dblevel #######)

1009

NO_ACTIVE_TXN

There was no currently active transaction for this connection.

NONE

1017

NO_UPDATES

The write transaction had no successful updates. No database change occurs, and no new database level is returned.

NONE

1031

DB_EXCEPTION

An unexpected exception was thrown during the database commit. The entire transaction was rolled back to ensure predicable behavior. Contact Oracle.

NONE

Abort Transaction

The Abort Transaction message aborts a currently executing read or write transaction. If the transaction was a read transaction, the transaction is simply closed. The abort_txn command defines the Abort Transaction message.

Request

This request aborts the currently executing transaction. If the current transaction is a write transaction, any updates are rolled back.

Note:

Sending an abort transaction request while receiving responses from a query request does not cause the query responses to stop.

Request syntax : 


abort_txn([iid XXXXX])

Response

The return codes listed in Table 3-6 indicates the result of the Abort Transaction request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-6 Abort Transaction Response Return Code

Return Code Text Description Data Section Contents

0

SUCCESS

Abort successful.

NONE

1009

NO_ACTIVE_TXN

There was no currently active transaction for this connection.

NONE

Create Subscription

Create Subscription messages define different combinations of subscriptions by using the ent_sub command with a different set of parameters. The following subscriptions can be created:

  • Subscription containing a single IMSI with no DNs

  • Subscription containing an IMSI and one to eight DNs

  • One or more DNs on the same NE with no IMSI

  • Subscription porting a block of DNs

When a request to create a subscription fails due to provisioning checks added for the EPAP Provisioning Blocklist feature, the beginning (bprovbl) and ending (eprovbl) address string of the conflicting EPAP Provisioning Blocklist will be returned in the response.

Subscription Containing a Single IMSI with No DNs
This command attempts to create an IMSI record that contains no DNs. By default, if the IMSI already exists, the command is rejected. Using the optionalforce parameter changes the default behavior to overwrite an existing IMSI. If the existing IMSI that is overwritten has DNs, those DNs are deleted. If the IMSI conflicts with an entry in the EPAP Provisioning Blocklist table, the command will be rejected and use of the optional force parameter will not override this function.

Note:

Only the G-Flex feature uses this type of subscription data.

The ent_sub command defines the request message for a subscription containing a single IMSI with no DNs.

Parameters :

imsi

A single IMSI.

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

sp

Specifies which SP the IMSI is on. The sp must correspond to an existing SP entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

force

(Optional) Indicates whether the client wants existing instances to be overwritten.

Values:

yes or no (default = no).

timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 - 3600 seconds

Rules :

  1. Using the force parameter cannot override conflicts with a provisioning blocklist entry.

Request syntax : 


ent_sub([iid XXXXX,] imsi XXXXX , sp XXXXX
[, force yes/no] [, timeout <0..3600>])
Subscription Containing an IMSI and One to Eight DNs
This command attempts to create a subscription with one IMSI and up to eight DNs. If the IMSI already exists and none of the DNs specified in the request exists as a stand-alone DN or on another IMSI, the request adds the specified DNs to the existing IMSI. If the number of DNs currently existing on the IMSI and the number of DNs specified in the request total more than eight, the request is rejected. If any of the DNs in the request match a DN already existing on the specified IMSI, it is not counted twice toward the eight-DN limit.The optional force parameter allows the client to change the default behavior and overwrite existing entries. If any of the DNs in the request conflict with a DN Block marked ineligible for splitting, the request is rejected. The use of optional force parameter would not change this behavior. If the IMSI already existed, it is deleted and recreated with the data in the request. This means that if the existing IMSI had DNs, those DNs are also deleted. If any of the DNs specified in the request already exist, those existing DNs are changed to point to the new IMSI and removed from the existing IMSI table. If removing the DNs results in the previous IMSI having no DNs, the IMSI with no DN is not deleted. If the IMSI or any of the DNs specified conflicts with an entry in the EPAP Provisioning Blocklist table, the command will be rejected and use of the optional force parameter will not override this function.

Note:

This type of subscription data is used only by the G-Flex feature.

The ent_sub command defines the request message for a subscription containing one IMSI and one to eight DNs.

Parameters :

imsi

A single IMSI.

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

dn

A DN (specified in international format) to be associated with the specified IMSI. There can be up to eight DNs specified.

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

sp

Specifies which SP the IMSI and DNs are on. The sp must correspond to an existing SP entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

force

(Optional) Indicates whether the client wants existing instances to be overwritten.

Values:

yes or no (default = no)

timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 - 3600 seconds

Rules :

  1. Using the force parameter cannot override conflicts with a provisioning blocklist entry.

  2. When the IMSI does not already exist, the sp parameter is required. If the command specifies new DNs for an existing, IMSI, the sp parameter is not required and the existing sp is not changed.

Request syntax : 


ent_sub([iid XXXXX,] imsi XXXXX, dn XXXXX, …, dn XXXXX
, sp XXXXX, [, force yes/no] [, timeout <0..3600>])
One or More DNs on the Same NE with no IMSI

This command attempts to create up to eight single DNs without associating any of them with an IMSI. They are all stand-alone DNs. Specifying more than one DN per request is only for performance reasons. When the request is complete, there is no relationship between them.

By default, if any of the specified DNs conflicts with an existing single DN, the entire command is rejected (including the DNs without conflict). The optional force parameter allows you to change the default behavior to overwrite existing DNs.

If any of the DNs specified conflicts with an entry in the EPAP Provisioning Blocklist table or with a DN Block marked ineligible for splitting, the command will be rejected and use of the optional force parameter will not override this function.

Stand-alone DNs might or might not be associated with a network entity, but they cannot be associated with both an SP and an RN at the same time.

If the newly created DN falls in the middle of an existing DN block, the new DN is considered to be an exception to the block. The block is still kept intact; it is not split into separate blocks around the new single DN, and the enter will succeed.

Guidelines for using the TIF Number Substitution parameter nsdn and st can be found in TIF Number Substitution Relationships . The default value for subscriber type st is Public. The rtrv_sub() command will not list st in its response for records that have the default value Public.

The IDP calling and called party blocklist parameters (cgbl/cdbl) are optional and have a default value of no. The GRN entity can optionally be associated with the DN. The GRN is used as redirection digits if either the calling or called party blocklist parameters are set to yes. The IDP blocklist feature is not related to the EPAP Provisioning Blocklist feature.

The (pt) parameter also defines the prepaid type. The prepaid type (portability type value of 3 or 4) determines which IN platform the short message is directed to. The pt parameter can be specified only for DNs; it cannot be specified when an IMSI is in the command.portability type (

For example, if a single ent_sub request specifies both an IMSI and a DN, you cannot specify pt. However, you can use the upd_sub request to add a pt to the DN. To add a DN and pt in one request, theent_sub must not specify an IMSI.

The pt values are mutually exclusive, that is, a single subscription cannot have simultaneously a value 1 (ported out) and also 3 (prepaid 1). However, there is no effect on the G-Port function if pt type 3 through 35 is specified. In these cases, if a message is being processed for G-Port and the DN block matches with a pt type 3 through 35, G-Port considers it the same as if the pt type = none.

The ent_sub command defines the request message for one or more DNs on the same NE with no IMSI.

Parameters :

dn
A DN (specified in international format). There can be up to eight DNs specified.
Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

pt

(Optional) The portability type for the created DN. This field is only used by G-Port, A-Port, IS41 GSM Migration, and PPSMS. For G-Port and A-Port, it controls number Portability Status encoding in SRI acks. For IS41 GSM Migration, it identifies whether a subscriber has or has not migrated from IS41 to GSM, (maintaining a single GSM handset). For PPSMS, it identifies a DN as one of two types needing PPSMS intercept.

Values:

none – no status (default = none)

0 – not known to be ported, migrated to IS41 or non-migrated IS41 sub (used for IS41 GSM Migration)

1 – own number ported out (used for G-Port and A-Port)

2 – foreign number ported to foreign network (used for G-Port and A-Port)

3 – prepaid 1 (used by PPSMS)

4 – prepaid 2 (used by PPSMS)

5 – migrated to GSM (used for IS41 GSM Migration)

6 – prepaid 3 (used by PPSMS)

7 – prepaid 4 (used by PPSMS)

8 – prepaid 5 (used by PPSMS)

9 – prepaid 6 (used by PPSMS)

10 – prepaid 7 (used by PPSMS)

11 – prepaid 8 (used by PPSMS)

12 – prepaid 9 (used by PPSMS)

13 – prepaid 10 (used by PPSMS)

14 – prepaid 11 (used by PPSMS)

15 – prepaid 12 (used by PPSMS)

16 – prepaid 13 (used by PPSMS)

17 – prepaid 14 (used by PPSMS)

18 – prepaid 15 (used by PPSMS)

19 – prepaid 16 (used by PPSMS)

20 – prepaid 17 (used by PPSMS)

21 – prepaid 18 (used by PPSMS)

22 – prepaid 19 (used by PPSMS)

23 – prepaid 20 (used by PPSMS)

24 – prepaid 21 (used by PPSMS)

25 – prepaid 22 (used by PPSMS)

26 – prepaid 23 (used by PPSMS)

27 – prepaid 24 (used by PPSMS)

28 – prepaid 25 (used by PPSMS)

29 – prepaid 26 (used by PPSMS)

30 – prepaid 27 (used by PPSMS)

31 – prepaid 28 (used by PPSMS)

32 – prepaid 29 (used by PPSMS)

33 – prepaid 30 (used by PPSMS)

34 – prepaid 31 (used by PPSMS)

35 – prepaid 32 (used by PPSMS)

36 – not identified to be ported

sp
(Optional) Specifies which SP the DN(s) are on. The sp must correspond to an existing SP entity. Most INP-only customers do not need to use SP.
Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

rn

(Optional) Specifies which RN the DNs are on. If the requested RN does not already exist, a blank one with no values is automatically created. G-Flex-only customers should not use RNs.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

vms

(Optional) Specifies which Voicemail Server the DN(s) are on and corresponds to the E.164 address of the voicemail server. The VMS must correspond to an existing VMS entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

grn

(Optional) Specifies which Generic Routing Number the DN(s) are on and corresponds to the E.164 address used when the EAGLE “NE Query Only Option” has been turned on. The GRN must correspond to an existing GRN entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

asd

(Optional) Additional Subscriber Data to be associated with the DN.

Values

1 to 10 hexadecimal digits expressed using ASCII characters.

st

(Optional) The subscriber type for created DNs.

Values

A decimal number in the range

0 - public

1 - private

nsdn

A TIF Number Substitution DN (specified in international format).

Values:

  • a string with 5 to 15 characters where each character must be a number from 0 to F.
cgbl
(Optional) IDP calling party blocklist.
Values
no - IDP calling party blocklist is disabled.
yes - IDP calling party blocklist is enabled
cdbl
(Optional) IDP called party blocklist.
Values
no - IDP called party blocklist is disabled.
yes - IDP called party blocklist is enabled.
lsblset
(Optional) A TIF Linkset based blocklist parameter that is used to decide if the DN needs to be blocklisted or not.
Values
a number from 1 to 255.
By default, no value is selected.
force

(Optional) Indicates whether the client wants existing instances to be overwritten.

Values:

yes or no (default = no)

timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 - 3600 seconds

Rules :

  1. It is not valid to specify bothsp andrn.

  2. Conflicts with an EPAP Provisioning blocklist entry and cannot be circumvented using the force parameter.

  3. It is not valid to specify more than 2 Network Entity types (sp,rn,vms,grn).

  4. Total command length must not exceed 247 characters.

    Note:

    Entering commands that exceed this length will result in the PDBI_CMD_LENGTH_EXCEEDED error (value 1045). In order to avoid this, remove unnecessary characters (including white space and parameters that are specified as the default value). If necessary, consider performing this provisioning in two steps by using an enter command followed by an update command.

  5. The DN given bynsdn must exist.

  6. Subscriber typest must be defined when using thensdn parameter

  7. It is not legal to specify the 2 Network Entitiesasd, andnsdn.

Request syntax: 

Ent_sub([iid XXXXX,] dn XXXXX, . . ., dn XXXXX, [pt <none/0/1/2/3/4……35>,] [st <0/1>,]
[nsdn XXXXX,] [sp XXXXX,] [rn XXXXX,] [vms XXXXX,] [grn XXXXX,] [asd XXXXX,]
[cgbl < no/yes>,] [cdbl <no/yes>,] [lsblset <1,2……255>,] [force yes/no,] [timeout <0..3600>])
Subscription Porting a Block of DNs

This command attempts to create a new DN block. By default, if the new DN block conflicts with any part of an existing DN block, the command is rejected. When the DN Block Self Healing feature is on, if the new DN Block to be added is a subset of the existing block with different properties and the existing DN Block has the splitting ability set to yes. The original DN Block will be split to accommodate the new DN Block. A new parameter split is added for this purpose. The default value for split parameter is yes.The force parameter is not supported for this command.

DN blocks might or might not be associated with a network entity, but they cannot be associated with both an SP and an RN at the same time.

Guidelines for using the TIF Number Substitution (TIF NS) parameter nsdn and st can be found in TIF Number Substitution Relationships . The default value for subscriber type st is Public. The rtrv_sub() command will not list st in its response for records that have the default value Public.

Guidelines for using the DN Block Self Healing parameter split can be found in DN Block Self Healing. The default value for the split parameter is yes. The rtrv_sub() command does not list split in its response for records that have the default value yes.

The IDP calling and called party blocklist parameters (cgbl/cdbl) are optional and have a default value of no. The GRN entity can optionally be associated with the DN Block. The GRN is used as redirection digits if either the calling or called party blocklist parameters are set toyes. The IDP A-Party Blocklist feature is not related to the EPAP Provisioning Blocklist feature.

The pt parameter is used to define the prepaid type. The prepaid type (value of 3 through 35) determines which IN platform the short message is directed to. The pt values are mutually exclusive, that is, a single subscription cannot have simultaneously a value 1 (ported out) and also 3 (prepaid 1). However, there is no effect on the G-Port function if pt type 3 through 35 is specified. In these cases, if a message is being processed for G-Port and the DN block matches with a pt type 3 through 35, G-Port considers it the same as if the pt type = none. This command is used only in the G-Port (and by extension PPSMS), V-Flex, and INP features; the portability type parameter applies only to G-Port and PPSMS.

The ent_sub command defines the request message for a block of DNs.

Parameters :

bdn

The beginning DN (specified in international format).

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

edn

The ending DN (specified in international format).

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

pt

(Optional) The portability type for the created DN. This field is only used by G-Port, A-Port, IS41 GSM Migration, and PPSMS. For G-Port and A-Port, it controls number Portability Status encoding in SRI acks. For IS41 GSM Migration, it identifies whether a subscriber has or has not migrated from IS41 to GSM, (maintaining a single GSM handset). For PPSMS, it identifies a DN as one of two types needing PPSMS intercept.

Values:

none – no status (default = none)

0 – not known to be ported, migrated to IS41 or non-migrated IS41 sub (used for IS41 GSM Migration)

1 – own number ported out (used for G-Port and A-Port)

2 – foreign number ported to foreign network (used for G-Port and A-Port)

3 – prepaid 1 (used by PPSMS)

4 – prepaid 2 (used by PPSMS)

5 – migrated to GSM (used for IS41 GSM Migration)

6 – prepaid 3 (used by PPSMS)

7 – prepaid 4 (used by PPSMS)

8 – prepaid 5 (used by PPSMS)

9 – prepaid 6 (used by PPSMS)

10 – prepaid 7 (used by PPSMS)

11 – prepaid 8 (used by PPSMS)

12 – prepaid 9 (used by PPSMS)

13 – prepaid 10 (used byPPSMS)

14 – prepaid 11 (used by PPSMS)

15 – prepaid 12 (used by PPSMS)

16 – prepaid 13 (used by PPSMS)

17 – prepaid 14 (used by PPSMS)

18 – prepaid 15 (used by PPSMS)

19 – prepaid 16 (used by PPSMS)

20 – prepaid 17 (used by PPSMS)

21 – prepaid 18 (used by PPSMS)

22 – prepaid 19 (used by PPSMS)

23 – prepaid 20 (used by PPSMS)

24 – prepaid 21 (used by PPSMS)

25 – prepaid 22 (used by PPSMS)

26 – prepaid 23 (used by PPSMS)

27 – prepaid 24 (used by PPSMS)

28 – prepaid 25 (used by PPSMS)

29 – prepaid 26 (used by PPSMS)

30 – prepaid 27 (used by PPSMS)

31 – prepaid 28 (used by PPSMS)

32 – prepaid 29 (used by PPSMS)

33 – prepaid 30 (used by PPSMS)

34 – prepaid 31 (used by PPSMS)

35 – prepaid 32 (used by PPSMS)

36 – not identified to be ported

sp

(Optional) Specifies which SP the DN(s) are on. The sp must correspond to an existing SP entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

rn

(Optional) Specifies which RN the DNs are on. If the requested RN does not already exist, a blank one with no values is automatically created. G-Flex-only customers should not use RNs.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

vms

(Optional) Specifies which Voicemail Server the DN(s) are on and corresponds to the E.164 address of the voicemail server. The VMS must correspond to an existing VMS entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

grn

(Optional) Specifies which Generic Routing Number the DN(s) are on and corresponds to the E.164 address used when the EAGLE “NE Query Only Option” has been turned on. The GRN must correspond to an existing GRN entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

asd

(Optional) Additional Subscriber Data to be associated with the DN Block.

Values

1 to 10 hexadecimal digits expressed using ASCII characters.

st

(Optional) The subscriber type for created DNs.

Values

A decimal number in the range

0 - public

1 - private

nsdn

A TIF NS DN (specified in international format).

Values:

  • a string with 5 to 15 characters where each character must be a number from 0 to F.
cgbl
(Optional) IDP calling party blocklist.
Values
no - IDP calling party blocklist is disabled.
yes - IDP calling party blocklist is enabled
cdbl
(Optional) IDP called party blocklist.
Values
no - IDP called party blocklist is disabled.
yes - IDP called party blocklist is enabled.
lsblset
(Optional) A TIF Linkset based Blocklist parameter that is used to decide if the DN needs to be blocklisted or not.
Values
a number from 1 to 255.
By default, no value is selected.
split
(Optional) Specifies whether a DN Block is eligible for splitting.
Values
yes – splitting is enabled for DN Block self heal (default= yes).
no – splitting is disabled for DN Block self heal.
force
(Optional) Indicates whether the client wants existing instances to be overwritten.
Values
yes or no ( default=no)
timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 - 3600 seconds

Rules :

  1. The bdn and edn parameter values must have the same number of digits.

  2. It is not valid to specify bothsp andrn.

  3. It is not valid to specify more than 2 Network Entity types (sp,rn,vms,grn).

  4. The DN given by nsdn must exist.
  5. Subscriber type st must be defined when using the nsdn parameter

  6. It is not legal to specify the 2 Network Entitiesasd, andnsdn.

The DN given by nsdn must exist. The DN given by nsdn must exist.

Request syntax : 

Ent_sub([iid XXXXX,] bdn XXXXX, edn XXXXX, [pt <none/0/1/2/3/4/….35>,] [st <0/1>,]
[nsdn XXXXX,] [sp XXXXX,] [rn XXXXX,] [vms XXXXX,] [grn XXXXX,] [asd XXXXX,]
[cgbl < no/yes>,] [cdbl <no/yes>,][lsblset <1,2……255>,]  [split yes/no,] [force yes/no,] [timeout <0..3600>])
Create Subscription Responses

The return codes in Table 3-7 might result from the Create Subscription request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-7 Create Subscription Response Return Codes

Return Code Text Description Data Section Contents
0

SUCCESS

Everything worked.

NONE

1005

WRITE_UNAVAIL

Another client already has a write transaction open.

IP address information of client that already has the write transaction.

data (id <connection id>, ip <ip addr>, port <port num>)

1006 NO_WRITE_PERMISSION

The PDBI client making request does not have write access permissions.

NONE
1009

NO_ACTIVE_TXN

There was no currently active transaction for this connection.

NONE

1011

WRITE_IN_READ_TXN

The create command was sent on a read transaction.

NONE

1012

INVALID_VALUE

One of the fields specified had an invalid value.

The offending field is returned in the data section:

data (param <field label>)

1014

CONFLICT_FOUND

An entry was found already in database matching an element of this request. If force yes parameter is used and this option is supported for this dta type, this error is not returned. Rather, existing instances are overwritten.

The offending existing element is returned. The type depends on the type of request.

data (dn XXXXX)

data (imsi XXXXX)

data (bdn XXXXX, edn XXXXX)

data (bprovbl XXXX, eprovBL XXXX)

1017

NO_UPDATES

The database already contains data in request. No update was necessary.

NONE

1021

NE_NOT_FOUND

The specified NE does not exist.

NONE

1027

IMSI_DN_LIMIT

The addition of DNs specified in request would cause IMSI to have more than eight DNs

NONE
1029

TXN_TOO_BIG

This request would cause current transaction to be larger than limit.

NONE
1032 MAX_IMSI_LIMIT Could not add new IMSI to the database. Adding a new IMSI would exceed the max allowed IMSIs. NONE
1033 MAX_DN_LIMIT Could not add new DN(s) to the database. Adding a new DN(s) would exceed the max allowed DNs. NONE
1034 MAX_DNBLK_LIMIT Could not add new DN Block to the database. Adding a new DN Block would exceed the max allowed DN Blocks. NONE
1044 SUB_NE_LIMIT There are too many network entities for a DN or DN Block. NONE
1046 MAX_ASD_LIMIT The database to exceeds the global limit of unique ASD records. NONE
1047 DN_NOT_FOUND The DN specified by nsdn does not exist. The offending existing element will be returned. data (nsdn XXXXX)
1048 MAX_ASSOCIATIONS This request contains too many associations for a DN or DN Block. The error is raised when TIF Number Substitution is combined with other associations and distinct from SUB_NE_LIMIT. NONE
1049

UNRESOLVED_DEPENDENCY

This record is referred to by other records. When using force to enter a pre-existing IMSI that has a DN with unresolved dependencies, the DN and the count of each dependency are returned. If more than one DN has unresolved dependencies, only one will be returned in this error. Data (dn XXXXX, counts([nsdn #####]))
1050 INCOMPATIBLE_ST The specified ST value conflicts with the ST value of NSDN. The ST value of NSDN will be returned in the data section data (st <0/1>)
1051

INCOMPATIBLE_ROP

 The GRN ROP value conflicts with the GMT value for the specified ASD. The GRN value for the ASD will be returned in the data section. data (grn #####)
1052

DNB_SAME_PROPERTIES

 The new DN Block requested by the operator is a subset of an existing block with same properties. The bdn and edn of conflicting block will be returned.
1053

MULTI_DNB_CONFLICT

 The new DN Block could not be added to the database as multiple conflicting DN Blocks were found within given bdn-edn. NONE
1054

DNB_SPLIT_NOT_ALLOWED

The new DN Block tries to split an existing DN Block that is not allowed to be split or a new individual DN is entered within an existing DN Block that is not allowed to be split. The bdn and edn of conflicting block will be returned.
1058 IMSI_FULL Could not add new IMSI to the database. Adding new IMSI would exceed the supported SMxG card size. The other supported subscriptions are allowed if space is available on the corresponding SMxG card. NONE
1060 DN_FULL Could not add new DN to the database. Adding new DN would exceed the supported SMxG card size. The other supported subscriptions are allowed if space is available on the corresponding SMxG card. NONE
1061 ASD_FULL Could not add new ASD to the database. Adding new ASD would exceed the supported SMxG card size. The other supported subscriptions are allowed if space is available on the corresponding SMxG card. NONE
1062 IMSI_ENT_NOT_ALLOWED Could not add new IMSI to the database. The RTDB is either down or incoherent. Adding new IMSI requires creation of new IMSI table which may lead to over-allocation. NONE

Update Subscription

Update Subscription

This command modifies existing subscription data. Specific scenarios are described in the usage variations below. Although all of the usage variations are called upd_sub , the existence of certain parameters changes what is meant.

Modify the SP for a Specific IMSI

This command attempts to modify the sp field for a specific IMSI. If the IMSI has any DNs associated with it, the DNs are modified to use the specified SP.

Note:

This type of subscription data is used only by the G-Flex feature.

Parameters:

imsi

A single IMSI.

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

sp

Specifies which SP the IMSI is being moved to. The SP must correspond to an existing SP entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 - 3600 seconds

Rules :

  1. Thesp parameter must be specified.

Request syntax : 


upd_sub([iid XXXXX,] imsi XXXXX, sp XXXXX,
[timeout <0..3600>])
Modify the Subscription Data of a Single DN

This command attempts to modify the Network Entity (SP, RN, VMS,or GRN) and portability type fields of a specific DN. If the DN is a stand-alone DN, the fields are simply modified. If the DN is associated with an IMSI and a new NE was specified in the request, the DN is removed from the IMSI and changed to use the specified NE directly.

Updating a DN by setting the sp and rn to the value none will result in a DN that is not associated with a Network Entity. If a DN was already associated with a sp or rn, specifying a new sp or rn will result in a replacement. Any update in which a Network Entity type is specified will only be allowed if the DN has not reached its maximum of 2 NEs per DN.

If a DN has a NE association and an update command specifies a new NE of the same NE type, a replacement is attempted. Updating a DN by setting a NE type (sp/rn/vms/grn) to the value none, results in a DN that is no longer associated with that NE. If a DN has an existing NE association and an update command specifies a NE of a different NE type, will attempt to add a new NE association. To replace a NE association with a new NE association of a different type, remove the old NE (specifying value none) and enter the new NE. This is done in a single request or as two separate requests (one command to remove the old NE and one command to add the new NE). Any update in which a Network Entity type is specified is only allowed if the DN has not reached its maximum of 2 NEs.

Guidelines for using the TIF Number Substitution parameter nsdn and st can be found in TIF Number Substitution Relationships . The default value for subscriber type st is Public. The rtrv_sub() command will not list st in its response for records that have the default value Public.

The IDP calling and called party blocklist parameters (cgbl/cdbl) are optional and have a default value of no. The GRN entity can optionally be associated with the DN. The GRN is used as redirection digits if either the calling or called party blocklist parameters are set to yes. The IDP A-Party Blocklist feature is not related to the EPAP Provisioning Blocklist feature.

If an update requires a replacement other than sp/rn for sp/rn, the user may specify the new Network Entity and the Network entity to be removed should be specified as a value of none. This may be done in a single request or as two separate requests (1 to remove the old NE and 1 to add the new NE).

This command is used for G-Flex, G-Port, and INP features, although some of the specific parameters are only meaningful on specific features.

Parameters:

dn

A single DN (specified in international format).

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

pt

(Optional) The portability type for the created DN. This field is only used by G-Port, A-Port, IS41 GSM Migration, and PPSMS. For G-Port and A-Port, it controls number Portability Status encoding in SRI acks. For IS41 GSM Migration, it identifies whether a subscriber has or has not migrated from IS41 to GSM, (maintaining a single GSM handset). For PPSMS, it identifies a DN as one of two types needing PPSMS intercept.

Values:

none – no status (default = none)

0 – not known to be ported, migrated to IS41 or non-migrated IS41 sub (used for IS41 GSM Migration)

1 – own number ported out (used for G-Port and A-Port)

2 – foreign number ported to foreign network (used for G-Port and A-Port)

3 – prepaid 1 (used by PPSMS)

4 – prepaid 2 (used by PPSMS)

5 – migrated to GSM (used for IS41 GSM Migration)

6 – prepaid 3 (used by PPSMS)

7 – prepaid 4 (used by PPSMS)

8 – prepaid 5 (used by PPSMS)

9 – prepaid 6 (used by PPSMS)

10 – prepaid 7 (used by PPSMS)

11 – prepaid 8 (used by PPSMS)

12 – prepaid 9 (used by PPSMS)

13 – prepaid 10 (used by PPSMS)

14 – prepaid 11 (used by PPSMS)

15 – prepaid 12 (used by PPSMS)

16 – prepaid 13 (used by PPSMS)

17 – prepaid 14 (used by PPSMS)

18 – prepaid 15 (used by PPSMS)

19 – prepaid 16 (used by PPSMS)

20 – prepaid 17 (used by PPSMS)

21 – prepaid 18 (used by PPSMS)

22 – prepaid 19 (used by PPSMS)

23 – prepaid 20 (used by PPSMS)

24 – prepaid 21 (used by PPSMS)

25 – prepaid 22 (used by PPSMS)

26 – prepaid 23 (used by PPSMS)

27 – prepaid 24 (used by PPSMS)

28 – prepaid 25 (used by PPSMS)

29 – prepaid 26 (used by PPSMS)

30 – prepaid 27 (used by PPSMS)

31 – prepaid 28 (used by PPSMS)

32 – prepaid 29 (used by PPSMS)

33 – prepaid 30 (used by PPSMS)

34 – prepaid 31 (used by PPSMS)

35 – prepaid 32 (used by PPSMS)

36 – not identified to be ported

sp

(Optional) Specifies which SP the DN is being moved to. The sp must correspond to an existing SP entity. Most INP only customers do not need to use sp.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

none – Sets the sp to not point to any network entity.

vms

(Optional) Specifies which Voicemail Server the DN(s) are on and corresponds to the E.164 address of the voicemail server. The VMS must correspond to an existing VMS entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

grn

(Optional) Specifies which Generic Routing Number the DN(s) are on and corresponds to the E.164 address used when the EAGLE “NE Query Only Option” has been turned on. The GRN must correspond to an existing GRN entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

none – Sets the rms to not point to any GRN entity.

rn

(Optional) Specifies which RN the DN is being moved to. If the requested RN does not already exist, a blank one with no values is automatically created. G-Flex-only customers should not use RNs.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

none – Sets the rn to not point to any network entity.

asd

(Optional) Additional Subscriber Data to be associated with the DN Block. Leading zeros are significant.

Values

1 to 10 hexadecimal digits expressed using ASCII characters. Leading zeros are significant.

none – Removes additional subscriber data from the DN.

st

(Optional) The subscriber type for created DNs.

Values

A decimal number in the range

0 - public

1 - private

nsdn

A TIF NS DN (specified in international format).

Values:

  • a string with 5 to 15 characters where each character must be a number from 0 to F.
cgbl
(Optional) IDP calling party blocklist.
Values
no - IDP calling party blocklist is disabled.
yes - IDP calling party blocklist is enabled
cdbl
(Optional) IDP called party blocklist.
Values
no - IDP called party blocklist is disabled.
yes - IDP called party blocklist is enabled.
lsblset
(Optional) A TIF Linkset based Blocklist parameter that is used to decide if the DN needs to be blocklisted or not.
Values
a number from 1 to 255.
By default, no value is selected.
timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 - 3600 seconds

Rules :

  1. It is not valid to create more than 2 Network Entity associations.

  2. The DN given by nsdn must exist.
  3. Cannot update a DN to have the 2 Network Entities asd and nsdn together.

  4. It is not valid to specify both sp andrn, unless they are both set tonone.

Request syntax : 

Upd_sub([iid XXXXX,] dn XXXXX, [pt <none/0/1/2/3//….35>,] [st <0/1>,] [nsdn XXXXX,]
[sp XXXXX,] [rn XXXXX,] [vms XXXXX,] [grn XXXXX,] [asd XXXXX,] [cgbl <no/yes>,]
[cdbl < no/yes>,][lsblset <1,2……255>,]  [force yes/no,] [timeout <0..3600>])
Move an existing DN to an Existing IMSI

This command is used to move an existing DN to an existing IMSI. The DN is changed to use the SP of the IMSI.

If the DN is already associated with an IMSI, it will be removed from that IMSI and associated with the new IMSI. The original IMSI will not be removed, even if this results in it having no DNs associated with it.

If the DN is already associated with a vms or grn, those NE associations will be removed when the DN is moved to the specified IMSI. IMSIs and DNs on IMSIs can only be associated with 1 NE.

Parameters :

dn

A single DN (specified in international format).

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

imsi

A single IMSI.

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 - 3600 seconds

Request syntax : 


upd_sub([iid XXXXX,] dn XXXXX, imsi XXXXX
[, timeout <0..3600>])
Modify the Subscription Information for a DN Block

This command modifies the subscription data for a DN block. The block specified must exactly match an existing block. It cannot span multiple blocks or into unused DNs. It cannot be a subset of an existing block

DN blocks might or might not be associated with a network entity, but they cannot be associated with both an SP and an RN at the same time. If a DN block has a NE association and the update command specifies a new NE of the same NE type, a replacement is attempted. Updating a DN block by setting a NE type (sp/rn/vms/grn) to the value none, results in a DN that is no longer associated with that NE. If a DN block has an existing NE association and the update command specifies a NE of a different NE type, will attempt to add a new NE association. To replace a NE association with a new NE association of a different type, remove the old NE (specifying value none) and enter the new NE. This is done in a single request or as two separate requests (one command to remove the old NE and one command to add the new NE). Any update in which a Network Entity type is specified is only allowed if the DN block has not reached its maximum of 2 NEs.

Guidelines for using the Number Substitution parameter nsdn and st can be found in TIF Number Substitution Relationships . The default value for subscriber type st is Public. The rtrv_sub() command will not list st in its response for records that have the default value Public.

The IDP calling and called party blocklist parameters (cgbl/cdbl) are optional and have a default value of no. The GRN entity can optionally be associated with the DN. The GRN is used as redirection digits if either the calling or called party blocklist parameters are set to yes. The IDP A-Party blocklist feature is not related to the EPAP Provisioning Blocklist feature.

The DN Block Self Healing parameter (split) is optional and has a default value of yes. This parameter can be modified by the user at any time without affecting any other attribute of the DN Block. Guidelines for the DN Block Self Healing feature can be found in DN Block Self Healing. The rtrv_sub() command will not list split in its response for records that have the default value yes.

Note:

DN blocks are used only in the G-Port, PPSMS, and INP features.

Parameters :

bdn

The beginning DN (specified in international format).

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

edn

The ending DN (specified in international format).

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

pt

(Optional) The portability type for the created DN. This field is only used by G-Port, A-Port, IS41 GSM Migration, and PPSMS. For G-Port and A-Port, it controls number Portability Status encoding in SRI acks. For IS41 GSM Migration, it identifies whether a subscriber has or has not migrated from IS41 to GSM, (maintaining a single GSM handset). For PPSMS, it identifies a DN as one of two types needing PPSMS intercept.

Values:

none – no status (default = none)

0 – not known to be ported, migrated to IS41 or non-migrated IS41 sub (used for IS41 GSM Migration)

1 – own number ported out (used for G-Port and A-Port)

2 – foreign number ported to foreign network (used for G-Port and A-Port)

3 – prepaid 1 (used by PPSMS)

4 – prepaid 2 (used by PPSMS)

5 – migrated to GSM (used for IS41 GSM Migration)

6 – prepaid 3 (used by PPSMS)

7 – prepaid 4 (used by PPSMS)

8 – prepaid 5 (used by PPSMS)

9 – prepaid 6 (used by PPSMS)

10 – prepaid 7 (used by PPSMS)

11 – prepaid 8 (used by PPSMS)

12 – prepaid 9 (used by PPSMS)

13 – prepaid 10 (used by PPSMS)

14 – prepaid 11 (used by PPSMS)

15 – prepaid 12 (used by PPSMS)

16 – prepaid 13 (used by PPSMS)

17 – prepaid 14 (used by PPSMS)

18 – prepaid 15 (used by PPSMS)

19 – prepaid 16 (used by PPSMS)

20 – prepaid 17 (used by PPSMS)

21 – prepaid 18 (used by PPSMS)

22 – prepaid 19 (used by PPSMS)

23 – prepaid 20 (used by PPSMS)

24 – prepaid 21 (used by PPSMS)

25 – prepaid 22 (used by PPSMS)

26 – prepaid 23 (used by PPSMS)

27 – prepaid 24 (used by PPSMS)

28 – prepaid 25 (used by PPSMS)

29 – prepaid 26 (used by PPSMS)

30 – prepaid 27 (used by PPSMS)

31 – prepaid 28 (used by PPSMS)

32 – prepaid 29 (used by PPSMS)

33 – prepaid 30 (used by PPSMS)

34 – prepaid 31 (used by PPSMS)

35 – prepaid 32 (used by PPSMS)

36 – not identified to be ported

sp

(Optional) Specifies which SP the DN Block is being moved to. The sp must correspond to an existing SP entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

none – Sets the sp to not point to any SP entity.

rn

(Optional) Specifies which RN the DN is being moved to. If the requested RN does not already exist, a blank one with no values is automatically created. G-Flex-only customers should not use RNs.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

none – Sets the rn to not point to any RN entity.

vms

(Optional) Specifies which Voicemail Server the DN(s) are on and corresponds to the E.164 address of the voicemail server. The VMS must correspond to an existing VMS entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

none – Sets the vms to not point to any VMS entity.
grn

(Optional) Specifies which Generic Routing Number the DN(s) are on and corresponds to the E.164 address used when the EAGLE “NE Query Only Option” has been turned on. The GRN must correspond to an existing GRN entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

none – Sets the grn to not point to any GRN entity.

asd

(Optional) Additional Subscriber Data to be associated with the DN Block.

Values

1 to 10 hexadecimal digits expressed using ASCII characters. Leading zeros are significant.

none – Removes additional subscriber data from the DN.

st

(Optional) The subscriber type for created DNs.

Values

A decimal number in the range

0 - public

1 - private

nsdn

A TIF Number Substitution DN (specified in international format).

Values:

  • a string with 5 to 15 characters where each character must be a number from 0 to F.
cgbl
(Optional) IDP calling party blocklist.
Values
no - IDP calling party blocklist is disabled.
yes - IDP calling party blocklist is enabled
cdbl
(Optional) IDP called party blocklist.
Values
no - IDP called party blocklist is disabled.
yes - IDP called party blocklist is enabled.
lsblset
(Optional) A TIF Linkset based blocklist parameter that is used to decide if the DN needs to be blocklisted or not.
Values
a number from 1 to 255.
By default, no value is selected.
split
(Optional) Specifies whether a DN Block is eligible for splitting.
Values
yes – splitting is enabled for DN Block self heal (default = yes).
no – splitting is disabled for DN Block self heal.
timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 - 3600 seconds

Rules :

  1. The bdn and edn parameter values must have the same number of digits.

  2. It is not valid to create more than 2 Network Entity associations.

  3. The DN given by nsdn must exist.

  4. A DN Block cannot be updated to have two Network Entities, asd and nsdn, together.

  5. See TIF Number Substitution Relationships for complete rules.

  6. See DN Block Self Healing for complete rules.

The bdn and edn parameter values must have the same number of digits.

Request syntax : 

Upd_sub([iid XXXXX,] bdn XXXXX, edn XXXXX, [pt <none/0/1/2/3//….35>,] [st <0/1>,]
[nsdn XXXXX,] [sp XXXXX,] [rn XXXXX,] [vms XXXXX,] [grn XXXXX,] [asd XXXXX,]
[cgbl < no/yes>,] [cdbl <no/yes>,] [lsblset <1,2……255>,] [split <no/yes>,] [timeout <0..3600>])
Update Subscription Responses

The return codes listed in Table 3-8 indicate the result of the Update Subscription request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-8 Update Subscription Response Return Codes

Return Code Text Description Data Section Contents

0

SUCCESS

Everything worked.

NONE

1012

INVALID_VALUE

One of the fields specified had an invalid value.

The offending field is returned in data section:

data (param <field label>)

1011

WRITE_IN_

READ_TXN

The command was sent on a read only transaction.

NONE

1013

NOT_FOUND

The requested DN, DN block, or IMSI was not found.

NONE

1027

IMSI_DN_LIMIT

The IMSI already has maximum number of DNs.

NONE

1029

TXN_TOO_BIG

This request would cause current transaction to be larger than limit.

NONE

1017

NO_UPDATES

Database already contains date in request. No update is necessary.

NONE

1009

NO_ACTIVE_TXN

There is no currently active transaction for this connection.

NONE

1021

NE_NOT_FOUND

NE specified does not exist.

NONE

1006

NO_WRITE_PERMISSION

PDBI client making request does not have write access permissions.

NONE

1005

WRITE_UNAVAIL

Another client already has a write transaction open.

IP address information of client that already has write transaction.

data (id <connection id>, ip <ip addr>, port <port num>)

1044

SUB_NE_LIMIT

This request would cause the DN or DN Block to have more than the maximum of 2 NE associations

NONE

1046

MAX_ASD_LIMIT

This request would cause the database to exceed the global limit of unique ASD records.

NONE

1047 DN_NOT_FOUND The DN specified by nsdn does not exist. The offending existing element will be returned. data (nsdn XXXXX)
1048 MAX_ASSOCIATIONS This request contains too many associations for a DN or DN Block. The error is raised when Number Substitution is combined with other associations and distinct from SUB_NE_LIMIT. NONE
1049 UNRESOLVED_DEPENDENCY This record is referred to by other records. When using force to enter a pre-existing IMSI that has a DN with unresolved dependencies, the DN and the count of each dependency are returned. If more than one DN has unresolved dependencies, only one will be returned in this error. Data (dn XXXXX, counts([nsdn #####]))
1050 INCOMPATIBLE_ST The specified ST value conflicts with the ST value of NSDN. The ST value of NSDN will be returned in the data section data (st <0/1>)

Delete Subscription

This command deletes subscription records. The specific usage variations follow. Although all of the usage variations are called dlt_sub, the existence of certain parameters change what is meant.

Delete an IMSI

This command attempts to delete the specified IMSI. If the IMSI has any DNs associated with it, the DNs are also deleted.

Parameters :

imsi

The IMSI to delete.

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 - 3600 seconds

Request syntax : 


dlt_sub([iid XXXXX,] imsi XXXXX, [timeout <0..3600>])
Delete a Single DN

This command attempts to delete a single DN. The DN is deleted even if the DN is associated with an IMSI. The IMSI remains even if this operation results in no DNs being associated with the IMSI.

Parameters :

dn

The single DN to delete (specified in international format).

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 - 3600 seconds

Request syntax : 


dlt_sub([iid XXXXX,] dn XXXXX, [timeout <0..3600>])
Delete a DN block

This command attempts to delete an existing DN block. The block specified must exactly match an existing block. It cannot span multiple blocks or into unused DNs. It cannot be a subset of an existing block.

If the DN Block Self Healing feature is on, an attempt to delete the subrange when master range properties mismatch or an attempt to delete the master range itself will be rejected. Guidelines for the DN Block Self Healing feature can be found in DN Block Self Healing.

Parameters :

bdn

The beginning DN of the block to delete (specified in international format).

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

edn

The ending DN of the block to delete (specified in international format).

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 - 3600 seconds

Rules :

  1. The bdn and edn parameter values must have the same number of digits.

Request syntax : 


dlt_sub([iid XXXXX,] bdn XXXXX, edn xxxxx, [timeout <0..3600>])
Delete Subscription Responses

The return codes listed in Table 3-9 indicate the result of the Delete Subscription request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-9 Delete Subscription Response Return Codes

Return Code Text Description Data Section Contents

0

SUCCESS

Everything worked.

NONE

1011

WRITE_IN_READ_TXN

The command was sent on a read only transaction.

NONE

1013

NOT_FOUND

The requested DN, DN block, or IMSI was not found.

NONE

1029

TXN_TOO_BIG

This request would cause current transaction to be larger than the limit.

NONE

1009

NO_ACTIVE_TXN

There is no currently active transaction for this connection.

NONE

1006

NO_WRITE_PERMISSION

PDBI client making request does not have write access permissions.

NONE

1005

WRITE_UNAVAIL

Another client already has a write transaction open.

IP address information of client that already has the write transaction.

data (id <connection id>, ip <ip addr>, port <port num>)

1049 UNRESOLVED_DEPENDENCY This record is referred to by other records. When using force to enter a pre-existing IMSI that has a DN with unresolved dependencies, the DN and the count of each dependency are returned. If more than one DN has unresolved dependencies, only one will be returned in this error. Data (dn XXXXX, counts([nsdn #####]))
1055 DNB_PARENT_PROPERTY

_MISMATCH

 Fragments of a master range have differing attributes. No automated resolution is possible to coalesce these records to satisfy a delete command. The bdn and edn of two differing master range fragments are returned.
1056 DNB_DLT_NOT_ALLOWED Fragments of a master range cannot be deleted while subranges are present The bdn and edn of a subrange are returned.

Retrieve Subscription Data

The command allows the client to retrieve information about the existing subscription data. The specific usage variations follow. Although all of the usage variations are called rtrv_sub, the existence of certain parameters change what is meant.

When multiple filtering parameters are specified (pt, sp, and rn), any output data must pass ALL of the filters specified. For example, if sp is specified, only instances referencing the specified SP values will be returned.

Retrieve Subscription Information About a Specific DN

This command retrieves the subscription information for a specific DN. If the G-Port or INP feature is available and the specific DN is not found, the PDBA also tries to find a DN block that the DN is in.

Parameters :

dn

The specific DN to retrieve (specified in international format).

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

pt

(Optional) The portability type for the created DN. This field is only used by G-Port, A-Port, IS41 GSM Migration, and PPSMS. For G-Port and A-Port, it controls number Portability Status encoding in SRI acks. For IS41 GSM Migration, it identifies whether a subscriber has or has not migrated from IS41 to GSM, (maintaining a single GSM handset). For PPSMS, it identifies a DN as one of two types needing PPSMS intercept.

Values:

none – no status (default = none)

0 – not known to be ported, migrated to IS41 or non-migrated IS41 sub (used for IS41 GSM Migration)

1 – own number ported out (used for G-Port and A-Port)

2 – foreign number ported to foreign network (used for G-Port and A-Port)

3 – prepaid 1 (used by PPSMS)

4 – prepaid 2 (used by PPSMS)

5 – migrated to GSM (used for IS41 GSM Migration)

6 – prepaid 3 (used by PPSMS)

7 – prepaid 4 (used by PPSMS)

8 – prepaid 5 (used by PPSMS)

9 – prepaid 6 (used by PPSMS)

10 – prepaid 7 (used by PPSMS)

11 – prepaid 8 (used by PPSMS)

12 – prepaid 9 (used by PPSMS)

13 – prepaid 10 (used by PPSMS)

14 – prepaid 11 (used by PPSMS)

15 – prepaid 12 (used by PPSMS)

16 – prepaid 13 (used by PPSMS)

17 – prepaid 14 (used by PPSMS)

18 – prepaid 15 (used by PPSMS)

19 – prepaid 16 (used by PPSMS)

20 – prepaid 17 (used by PPSMS)

21 – prepaid 18 (used by PPSMS)

22 – prepaid 19 (used by PPSMS)

23 – prepaid 20 (used by PPSMS)

24 – prepaid 21 (used by PPSMS)

25 – prepaid 22 (used by PPSMS)

26 – prepaid 23 (used by PPSMS)

27 – prepaid 24 (used by PPSMS)

28 – prepaid 25 (used by PPSMS)

29 – prepaid 26 (used by PPSMS)

30 – prepaid 27 (used by PPSMS)

31 – prepaid 28 (used by PPSMS)

32 – prepaid 29 (used by PPSMS)

33 – prepaid 30 (used by PPSMS)

34 – prepaid 31 (used by PPSMS)

35 – prepaid 32 (used by PPSMS)

36 – not identified to be ported

sp

(Optional) Filters the request to just retrieve the DNs in the range that are on the provided SP.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

none – Filters for instances not on an SP.

rn

(Optional) Filters the request to just retrieve the DNs in the range that are on the provided RN.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

none – Filters for instances not on an RN.

vms

(Optional) Specifies which Voicemail Server the DN(s) are on and corresponds to the E.164 address of the voicemail server. The VMS must correspond to an existing VMS entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

none – Sets the vms to not point to any network entity.
grn

(Optional) Specifies which Generic Routing Number the DN(s) are on and corresponds to the E.164 address used when the EAGLE “NE Query Only Option” has been turned on. The GRN must correspond to an existing GRN entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

none – Sets the grn to not point to any network entity.

asd

(Optional) Additional Subscriber Data to be associated with the DN Block.

Values

1 to 10 hexadecimal digits expressed using ASCII characters. Leading zeros are significant.

none – Removes additional subscriber data from the DN.

st

(Optional) The subscriber type for created DNs.

Values

A decimal number in the range

0 - public

1 - private

nsdn

A Number Substitution DN (specified in international format).

Values:

  • a string with 5 to 15 characters where each character must be a number from 0 to F.
cgbl
(Optional) IDP calling party blocklist.
Values
no - IDP calling party blocklist is disabled.
yes - IDP calling party blocklist is enabled
cdbl
(Optional) IDP called party blocklist.
Values
no - IDP called party blocklist is disabled.
yes - IDP called party blocklist is enabled.
lsblset
(Optional) A TIF Linkset based Blocklist parameter that is used to decide if the DN needs to be blocklisted or not.
Values
a number from 1 to 255.
By default, no value is selected.
split
(Optional) Specifies the DN Block splitting ability. This parameter filters the request to retrieve only those DN Blocks that have the specified split value. This parameter must be specified in order to be used as a filter. If this parameter is not specified, filtering on the split value is not performed.
Values
no – DN Block splitting is disabled.
yes – DN Block splitting is enabled.
data

(Optional) Lets the requester specify the type of output data to be returned. See Retrieve Subscription Data Responses for additional information.

Values:

all– Return all known data for each instance (default).

neonly – Return only the Network Element information for each instance.

count – Return only a single instance count of all instances matching the query.

num

(Optional) Allows the client to limit the number of items that are returned.

Values:

1 - 40000000

Request syntax : 


Rtrv_sub([iid XXXXX,] dn XXXXX, [type <block/single>,] [pt <none/0/1/2/3/4/….35>],
[st <0/1>,] [nsdn XXXXX,] [sp XXXXX,] [rn XXXXX,] [vms XXXXX,] [grn XXXXX,] [asd XXXXX,] 
[cgbl <no/yes>,] [cdbl <no/yes>,] [lsblset <1,2……255>,] [split <no/yes>,] [data <all/neonly/count>,] [num <1..40000000>])
Retrieve Subscription Information for a Range of DNs

This command retrieves all of the subscription data within a range of DNs.

Parameters :

bdn

The starting dn for the DN range (specified in international format).

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

edn

The ending dn for the DN range (specified in international format).

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

type

(Optional) Whether to report the DN blocks or the single DNs.

Values:

block – Searches the DN Block table. Reports only DN Blocks, regardless of whether any provisioned Single DNs fall within the specified number range

single (default) - Searches the Single DN table. Returns only DNs that were provisioned as Single DNs, regardless of whether the DN number falls within the number range of a provisioned DN block)

pt

(Optional) The portability type for the created DN. This field is only used by G-Port, A-Port, IS41 GSM Migration, and PPSMS. For G-Port and A-Port, it controls number Portability Status encoding in SRI acks. For IS41 GSM Migration, it identifies whether a subscriber has or has not migrated from IS41 to GSM, (maintaining a single GSM handset). For PPSMS, it identifies a DN as one of two types needing PPSMS intercept.

Values:

none – no status (default = none)

0 – not known to be ported, migrated to IS41 or non-migrated IS41 sub (used for IS41 GSM Migration)

1 – own number ported out (used for G-Port and A-Port)

2 – foreign number ported to foreign network (used for G-Port and A-Port)

3 – prepaid 1 (used by PPSMS)

4 – prepaid 2 (used by PPSMS)

5 – migrated to GSM (used for IS41 GSM Migration)

6 – prepaid 3 (used by PPSMS)

7 – prepaid 4 (used by PPSMS)

8 – prepaid 5 (used by PPSMS)

9 – prepaid 6 (used by PPSMS)

10 – prepaid 7 (used by PPSMS)

11 – prepaid 8 (used by PPSMS)

12 – prepaid 9 (used by PPSMS)

13 – prepaid 10 (used by PPSMS)

14 – prepaid 11 (used by PPSMS)

15 – prepaid 12 (used by PPSMS)

16 – prepaid 13 (used by PPSMS)

17 – prepaid 14 (used by PPSMS)

18 – prepaid 15 (used by PPSMS)

19 – prepaid 16 (used by PPSMS)

20 – prepaid 17 (used by PPSMS)

21 – prepaid 18 (used by PPSMS)

22 – prepaid 19 (used by PPSMS)

23 – prepaid 20 (used by PPSMS)

24 – prepaid 21 (used by PPSMS)

25 – prepaid 22 (used by PPSMS)

26 – prepaid 23 (used by PPSMS)

27 – prepaid 24 (used by PPSMS)

28 – prepaid 25 (used by PPSMS)

29 – prepaid 26 (used by PPSMS)

30 – prepaid 27 (used by PPSMS)

31 – prepaid 28 (used by PPSMS)

32 – prepaid 29 (used by PPSMS)

33 – prepaid 30 (used by PPSMS)

34 – prepaid 31 (used by PPSMS)

35 – prepaid 32 (used by PPSMS)

36 – not identified to be ported

sp

(Optional) Filters the request to just retrieve the DNs in the range that are on the provided SP.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

none – Filters for instances not on an SP.

rn

(Optional) Filters the request to just retrieve the DNs in the range that are on the provided RN.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

none – Filters for instances not on an RN.

vms

(Optional) Specifies which Voicemail Server the DN(s) are on and corresponds to the E.164 address of the voicemail server. The VMS must correspond to an existing VMS entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

none – Sets the vms to not point to any network entity.
grn

(Optional) Specifies which Generic Routing Number the DN(s) are on and corresponds to the E.164 address used when the EAGLE “NE Query Only Option” has been turned on. The GRN must correspond to an existing GRN entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

none – Sets the grn to not point to any network entity.

asd

(Optional) Additional Subscriber Data to be associated with the DN Block.

Values

1 to 10 hexadecimal digits expressed using ASCII characters. Leading zeros are significant.

none – Removes additional subscriber data from the DN.

st

(Optional) The subscriber type for created DNs.

Values

A decimal number in the range

0 - public

1 - private

nsdn

A Number Substitution DN (specified in international format).

Values:

  • a string with 5 to 15 characters where each character must be a number from 0 to F.
cgbl
(Optional) IDP calling party blocklist.
Values
no - IDP calling party blocklist is disabled.
yes - IDP calling party blocklist is enabled
cdbl
(Optional) IDP called party blocklist.
Values
no - IDP called party blocklist is disabled.
yes - IDP called party blocklist is enabled.
lsblset
(Optional) A TIF Linkset based Blocklist parameter that is used to decide if the DN needs to be blocklisted or not.
Values
a number from 1 to 255.
By default, no value is selected.
split
(Optional) Specifies the DN Block splitting ability. This parameter filters the request to retrieve only those DN Blocks that have the specified split value. This parameter must be specified in order to be used as a filter. If this parameter is not specified, filtering on the split value is not performed.
Values
no – DN Block splitting is disabled.
yes – DN Block splitting is enabled.
data

(Optional) Lets the requester specify the type of output data to be returned. See Retrieve Subscription Data Responses for additional information.

Values:

all– Return all known data for each instance (default).

neonly – Return only the Network Element information for each instance.

count – Return only a single instance count of all instances matching the query.

num

(Optional) Allows the client to limit the number of items that are returned.

Values:

1 - 40000000

Rules :

  1. Specifying both sp and rn is not allowed because it would always result in no instances being found.

  2. Thetype parameter acts to filter the responses based on how the data was provisioned. For instance, ifblock is specified, only DN blocks (that were provisioned as blocks) are returned. Ifsingle is specified, only DNs that were provisioned as single DNs are returned.

    Note:

    If a substantial number of records are requested, there is a significant delay before responses start coming back.

  3. Specifying a combination of 2 Network Entity types (sp, rn, vms, grn) other than sp and rn is allowed and will result in instances matching both associations. Only specifying 1 NE will return all instances associated with the NE, even if instances are associated with other NEs.

There is no association between the position of a DN in the database and the chronological order in which it is provisioned. Thus, the response to the retrieve command gives no indication of which DNs were provisioned first and which were provisioned last. It simply returns all DNs associated with an IMSI. Likewise, the provisioning order of DNs have no effect on where DNs are physically placed in the database.

The instance count values are given as optional because they are not returned for every procedure call. For instance, IMSIs are not returned for commands related to retrieval of DNs.

Request syntax : 

Rtrv_sub([iid XXXXX,] bdn XXXXX, edn XXXXX, [type <block/single>,] [pt <none/0/1/2/3/4/….35>],
[st <0/1>,] [nsdn XXXXX,] [sp XXXXX,] [rn XXXXX,] [vms XXXXX,] [grn XXXXX,] [asd XXXXX,] [cgbl <no/yes>,] [cdbl <no/yes>,] [lsblset <1,2……255>,] [split <no/yes>,] [data <all/neonly/count>,] [num <1..40000000>])
Retrieve Subscription Information About a Specific IMSI

This command retrieves the subscription information for a specific IMSI. If the IMSI is associated with DNs, they are returned as well.

Parameters :

imsi

The specific IMSI to retrieve.

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

data

(Optional) Lets the requester specify the type of output data to be returned. See Retrieve Subscription Data Responses for additional information.

Values:

all – Return all known data for each instance (i.e., list the DNs on each IMSI) (default).

neonly – Return only the Network Element information for each instance.

Request syntax : 


rtrv_sub([iid XXXXX,] imsi XXXXX, [data <all/neonly>])
Retrieve Subscription Information for a Range of IMSIs

This command retrieves all of the subscription data within a range of IMSIs.

Parameters :

bimsi

The starting IMSI for the IMSI range.

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

eimsi

The ending IMSI for the IMSI range.

Values:

5 to 15 hexadecimal digits expressed using ASCII characters.

sp

(Optional) Filters the request to just retrieve the DNs in the range that are on the provided SP.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

data

(Optional) Lets the requester specify the type of output data to be returned. See Retrieve Subscription Data Responses for additional information.

Values:

all – Return all known data for each instance (i.e., list the DNs on each IMSI) (default).

neonly – Return only the Network Element information for each instance.

count – Return only a single instance count of all instances matching the query.

num

(Optional) Allows the client to limit the number of items to be returned.

Values:

1 - 40000000

Note:

If a substantial number of records are requested, there is a significant delay before the responses start coming back.

Request syntax : 


rtrv_sub([iid XXXXX,] bimsi XXXXX, eimsi XXXXX, [sp XXXXX,]
[data <all/neonly/count>,] [num <1..40000000>])
Retrieve Subscription Data Responses

The syntax of the data section of responses to a successful Retrieve Subscription Data request depends on the type of records being returned. DN records, DN block records, IMSI records, or instance counts can be returned. Each type of data being returned has a different syntax.

The responses that actually return instance data also have optional relationship information that can be present. For example, in an IMSI response there is a list of the DNs that are on that IMSI. If all the requester cares about is the IMSI-to-SP mapping, this additional DN relationship information can be omitted from the IMSI section of the response by specifying the value neonly in the data parameter. Adata value of all returns all of the optional information that is present in the instances. The same type of relationship information is also present in the DN section and the same parameter has the effect of omitting it.

Note:

  1. The st parameter will appear in the response only if its value differs from the system default (Public). See TIF Number Substitution Relationships for more details about number substitution.
  2. The cdbl parameter will be listed in the rtrv_sub() command response only when it’s value is yes.
  3. The cgbl parameter will be listed in the rtrv_sub() command response only when it’s value is yes.
  4. In case of DN Block, the split parameter will be listed in the rtrv_sub() command response only when its value is no.

  • Response syntax for an IMSI query: 

    
data ([segment XXXXX], imsis (imsi (id XXXXX,
[dns ( XXXXX, . . .),]  sp XXXXX) ),
. . .
(. . .) ) )

  • Response syntax for a DN query: 

    data (segment XXXXX, dns (dn (id XXXXX, [imsi XXXXX,] [pt <none/0/1/2/3/4/….35>], [sp XXXXX,] [rn XXXXX] [vms XXXXX,] [grn XXXXX,] [asd XXXXX,] [st <1>,] [nsdn XXXXX]), [cgbl <yes>,] [cdbl <yes>,]
. . .,
( . . . ) ) )
    
data ([segment XXXXX], dns (dn (id XXXXX, [imsi XXXXX,]
[pt <0/1/2/3/4/5/none>], [sp XXXXX,] [rn XXXXX]) ),
. . .,
(. . .) ) )

  • Response syntax for a DN block query: 

    data (segment XXXXX, dnblocks (dnblock (bdn XXXXX, edn XXXXX, [pt <none/0/1/2/3/4/….35>], [sp XXXXX,] [rn XXXXX,] [vms XXXXX,] [grn XXXXX,] [asd XXXXX,] [st <1>,] [nsdn XXXXX]), [cgbl <yes>,] [cdbl <yes>,] [split <no>,]  
. . .,
( . . . ) ) )

  • Response syntax for a count query:

    Requests that specify adata parameter ofcount gets just one response that contains the instance count for the type of subscription data that they are querying. Only one of the optional counts would be present in the response. 

    
data (counts ([imsi #####,] [dn #####,] [dnblock #####]) )

The return codes listed in Table 3-10 indicate the result of the Retrieve Subscription Data request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-10 Retrieve Subscription Data Response Return Codes

Return Code Text Description Data Section Contents
0

SUCCESS

The request succeeded and this is the last (or only) response.

Depends on the request type, etc.

1012

INVALID_VALUE

One of the fields specified had an invalid value.

Offending field is returned in data section:

data (param <field label>)

1016

PARTIAL_SUCCESS

The request has succeeded, but this is only one of many responses.

Depends on the request type, etc.

1013

NOT_FOUND

The requested DN, DN block, or IMSI was not found.

NONE

1009

NO_ACTIVE_TXN

There is no currently active transaction for this connection.

NONE

1021

NE_NOT_FOUND

An NE to filter was specified, but the NE does not exist.

NONE

Create Network Entity

The ent_entity command creates an entity object (such as an SP) and its corresponding global title translation. There is a limit of 150,000 network entity instances.

It is valid for entities of different types to have the same id. Spare point codes, indicated by an optional s- prefix, are supported for Network Entities with a pctype of intl and natl.

Create Network Entity Request

Parameters :

id

Identifier for this network entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

type

Type of network entity being created.

Values:

SP – Signal Point

RN – Routing Number. (G-Flex only customers do not use RNs. Used for A-Port and IS41 GSM Migration features.)

VMS – Voicemail Server. (Used for V-Flex customers.)

GRN – Generic Routing Number

pctype

Specifies the type of the point code.

Values:

intl - ITU international point code in the form zone-area-id (z-aaa-i).

natl - ITU national point code in the form of ITU number (nnnnn).

nl24 - ITU national 24-bit point code in the form of msa-ssa-sp (mmm-sss-ppp).

ansi - ANSI point code in the form of network-cluster-member (nnn-ccc-mmm).

none - No point code specified. (Only valid for RNs, VMSs, and GRNs.)

pc

Point code value. The valid values depend on the pctype parameter.

Values:

For pctype of intl the format is zone-area-id [(s-)z-aaa-i].

s - Optional spare point code indicator

z= 0 – 7

aaa= 0 – 255

i= 0 - 7

Note: The value 0-0-0 is not valid.

For pctype of natl the format is number [(s-)nnnnn].

nnnnn= 1 – 16383

For pctype of ansi, the format is network-cluster-member (nnn-ccc-mmm).

s - Optional spare point code indicator

nnn= 1 – 255

ccc= 1 – 255 (if network = 1 – 5)

= 0 – 255 (if network = 6 – 255)

mmm= 0 – 255

For pctype of none, the pc parameter is not allowed.

gc

(Optional) Group code. This optional parameter is part of the point code value for ITU Duplicate Point Code Support feature.

Values:

aa - zz

ri

Routing indicator. This parameter indicates whether a subsequent global title translation is required.

Values:

GT = Global Title. Indicates that a subsequent translation is required.

SSN = Subsystem Number. Indicates that no further translation is required.

ssn

(Optional) New subsystem number. This parameter identifies the subsystem address that is to receive the message.

Values:

0, 2 – 255

none (default)

ccgt

(Optional) Cancel called global title.

Values:

yes or no (default)

ntt

(Optional) New translation type. This parameter identifies the translation type value to replace the received translation type value.

Values:

0 – 255

none (default)

nnai

(Optional) New nature of address.

Values:

0 – 127

none (default)

nnp

(Optional) New numbering plan.

Values:

0 – 15

none (default)

da

(Optional) Digit action. The parameter specifies what changes, if any, to apply to the Called Party GTA.

Values:

none – No change to the Called Party GTA (default)

replace – Replace Called Party GTA with the entity id

prefix – Prefix Called Party GTA with the entity id

insert – Insert entity id after country code (CC + Entity Id + NDC + SC)

delccprefix – Delete country code, then prepend the entity id.

delcc – Delete country code.

spare1 – No change to GTA. Digit action value of 6 passed to EAGLE.

spare2 – No change to GTA. Digit action value of 7 passed to EAGLE.

srfimsi

(Optional) The IMSI returned by a SRF indicating the Subscription Network of the subscriber. This parameter is only used by the G-Port features and only for RNs.

Values:

5 to 15 hex digits expressed using ASCII characters.

timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 - 3600 seconds

Rules :

  1. If the pctype is none, none of the optional parameters can be specified.

  2. If ri is GT,ccgt must be no.

  3. Ifccgt isyes, the parameters ntt, nnai, nnp, and da cannot be set.

  4. The maximum number of network entities (150,000) must not be reached.

  5. Parameter gc can be specified only when pctype = natl.

Request syntax : 


ent_entity([iid XXXXX,] id XXXXX, type <SP/RN/VMS/GRN>, pctype
<intl/natl/ansi/none>, [pc <pc value>,], [gc <gc value>,]
[ri <GT/SSN>,] [ssn <0/2..255/none>,] [ccgt <yes/no>,]
[ntt <0..255/none>,] [nnai <0..127/none>,] [nnp <0..15/none>,]
[da <none/replace/prefix/insert/delccprefix/delcc/spare1
/spare2>,] [srfimsi XXXXX] [, timeout <0..3600>])

Create Network Entity Response

The return codes listed in Table 3-11 indicate the result of the Create network entity request. See PDBI Message Error Codesfor the recommended actions to help resolve the error related return codes.

Table 3-11 Create Network Entity Response Return Codes

Return Code Text Description Data Section Contents
0 SUCCESS

Everything worked.

NONE
1005 WRITE_UNAVAIL

Another client already has a write transaction open.

IP address information of client that already has the write transaction.

data (id <connection id>, ip <ip addr>, port <port num>)

1006 NO_WRITE_PERMISSION

PDBI client making request does not have write access permissions.

NONE
1009 NO_ACTIVE_TXN

There is no currently active transaction for this connection.

NONE
1011 WRITE_IN_READ_TXN

The command was sent on a read only transaction.

NONE
1012 INVALID_VALUE

One of the fields specified had an invalid value.

Offending field is returned in data section: data (param <field label>)

1015 ITEM_EXISTS

The network entity already exists.

 
1029 TXN_TOO_BIG

This request would cause current transaction to be larger than the limit.

NONE
1035 MAX_NE_LIMIT

Could not add new Network Entity to the database. Adding a new Network Entity would exceed the max allowed Network Entities.

 NONE

Update Network Entity

The upd_entitycommand modifies an entity object (such as an SP) and its corresponding global title translation.

Spare point codes, indicated by an optional s- prefix, are supported for Network Entities with a pctype of intl and natl.

Update Network Entity Request

Parameters :

id

Global title address for this network entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

type

Type of network entity being updated.

Values:

SP – Signal Point

RN – Routing Number. (G-Flex only customers do not use RNs. Used for A-Port and IS41 GSM Migration features.)

VMS – Voicemail Server. (Used for V-Flex customers.)

GRN – Generic Routing Number

pctype

(Optional) Specifies the type of the point code. If the pctype of an existing NE is changed, then the pc parameter must also be specified.

Values:

  • intl - ITU international point code in the form zone-area-id (z-aaa-i).
  • natl - ITU national point code in the form of ITU number (nnnnn).
  • nl24 - ITU national 24-bit point code in the form of msa-ssa-sp (mmm-sss-ppp).
  • ansi - ANSI point code in the form of network-cluster-member (nnn-ccc-mmm).
  • none - No point code specified. (Only valid for RNs, VMSs, and GRNs.)
pc

(Optional) Point code value. The valid values depend on the pctype parameter. If no pctype parameter is specified, the pctype of the existing instance is used.

Values:

For pctype of intl the format is zone-area-id [(s-)z-aaa-i].

s - Optional spare point code indicator

z= 0 – 7

aaa= 0 – 255

i= 0 – 7

Note: The value 0-0-0 is not valid.

For pctype of natl the format is number [(s-)nnnnn].

s - Optional spare point code indicator

nnnnn= 1 – 16383

For pctype of ansi, the format is network-cluster-member (nnn-ccc-mmm).

nnn= 1 – 255

ccc= 1 – 255 (if network = 1 – 5)

= 0 – 255 (if network = 6 – 255)

mmm= 0 – 255

For pctype of none, the pc parameter is not allowed.

gc

(Optional) Group code. This optional parameter is part of the point code value for ITU Duplicate Point Code Support feature.

Values:

aa – zz

ri

(Optional) Routing indicator. This parameter indicates whether a subsequent global title translation is required.

Values:

GT = Global Title. Indicates that a subsequent translation is required.

SSN = Subsystem Number. Indicates that no further translation is required.

ssn

(Optional) Subsystem number. This parameter identifies the subsystem address that is to receive the message.

Values:

0, 2 – 255

none

ccgt

(Optional) Cancel called global title.

Values:

yes or no

ntt

(Optional) New translation type. This parameter identifies the type of global title translation to replace the received global title.

Values:

0 – 255

none

nnai

(Optional) New nature of address.

Values:

0 – 127

none

nnp

(Optional) New numbering plan.

Values:

0 – 15

none

da

(Optional) Digit action. The parameter specifies what changes, if any, to apply to the Called Party GTA.

Values:

none – No change to the Called Party GTA (default)

replace –Replace Called Party GTA with the entity id

prefix – Prefix Called Party GTA with the entity id

insert – Insert entity id after country code (CC + Entity Id + NDC + SC)

delccprefix – Delete country code, then prepend the entity id.

delcc – Delete country code.

spare1 – No change to GTA. Digit action value of 6 passed to EAGLE.

spare2 – No change to GTA. Digit action value of 7 passed to EAGLE.

srfimsi

(Optional) The IMSI returned by a SRF indicating the Subscription Network of the subscriber. This parameter is used only with the G-Port features and only on RNs.

Values:

5 to 15 hex digits expressed using ASCII characters.

timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 – 3600 seconds

Rules :

  1. Parameter id must already exist.

  2. If the pctype is none, none of the optional parameters can be specified.

  3. If ri is GT, ccgt must be no.

  4. If ccgt is yes, the parameters ntt, nnai, nnp, and da cannot be set.

  5. Parameter gc can be specified only when pctype = natl.

  6. If the pctype is changed to none, all of the other parameters are cleared out, including the srfimsi.

Request syntax : 


upd_entity([iid XXXXX,] id XXXXX, type <SP/RN>, [pctype
<intl/natl/ansi/none>,] [pc <pc value>,] [gc <gc value>,]
[ri <GT/SSN>,] [ssn <0/2..255/none>,] [ccgt <yes/no>,]
[ntt <0..255/none>,] [nnai <0..127/none>,] [nnp <0..15/none>,]
[da <none/replace/prefix/insert/delccprefix/delcc/spare1
/spare2>,] [srfimsi XXXXX,] [timeout <0..3600>])

Update Network Entity Response

The return codes listed in Table 3-12 indicate the result of the Update Network Entity request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-12 Update Network Entity Response Return Codes

Return Code Text Description Data Section Contents

0

SUCCESS

Everything worked.

NONE

1012

INVALID_VALUE

One of the fields specified had an invalid value.

Offending field is returned in data section:

data (param <field label>)

1011

WRITE_IN_READ_TXN

The command was sent on a read only transaction.

NONE

1013

NOT_FOUND

The requested SP was not found.

NONE

1029

TXN_TOO_BIG

This request would cause current transaction to be larger than the limit.

NONE

1009

NO_ACTIVE_TXN

There is no currently active transaction for this connection.

NONE

1017

NO_UPDATES

Database already contains the data in this request. No update necessary.

NONE

1006

NO_WRITE_PERMISSION

PDBI client making request does not have write access permissions.

NONE

1005

WRITE_UNAVAIL

Another client already has a write transaction open.

IP address information of client that already has the write transaction.

data (id <connection id>, ip <ip addr>, port <port num>)

Delete Network Entity

The dlt_entitycommand deletes an entity object and its corresponding global title translation.

Delete Network Entity Request

This command fails if the entity does not exist or the entity is referenced by a subscription.

Parameters :

id

Global title address for this network entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters

type

Type of network entity being deleted.

Values:

SP – Signal Point

RN – Routing Number (only available with G-Port, INP, A-Port, and IS41 GSM Migration features)

VMS – Voicemail Server. (Used for V-Flex customers.)

GRN – Generic Routing Number

timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 – 3600 seconds

Request syntax : 


dlt_entity([iid XXXXX,] id XXXXX, type <SP/RN/VMS/GRN>
[, timeout <0..3600>])

Delete Network Entity Response

The return codes listed in Table 3-13 indicates the result of the Delete Network Entity request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-13 Delete Network Entity Response Return Codes

Return Code Text Description Data Section Contents

0

SUCCESS

Everything worked.

NONE

1012

INVALID_VALUE

One of the fields specified had an invalid value.

Offending field is returned in data section: data (param <field label>)

1011

WRITE_IN_READ_TXN

The command was sent on a read only transaction.

NONE

1022

CONTAINS_SUBS

The NE to be deleted still contains subscription data.

The counts for each type of subscription data on the NE are returned.

data (counts([imsi #####,] [dn #####,] [dnblock #####,]))

1013

NOT_FOUND

The requested SP was not found.

NONE

1029

TXN_TOO_BIG

The request would cause the current transaction t be larger than the limit.

NONE

1009

NO_ACTIVE_TXN

There is no currently active transaction for this connection.

NONE

Retrieve Network Entity

This command retrieves one or all of the network entities. The specific usage variations follow. Although all of the usage variations are called rtrv_entity, the existence of certain parameters change what is meant.

Retrieve the Information for a Specific NE

Parameters :

id

Global title address for this network entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters

type

Type of network entity to be retrieved.

Values:

SP – Signal Point

RN – Routing Number (only available with G-Port, INP, A-Port, and IS41 GSM Migration features)

VMS – Voicemail Server. (Used for V-Flex customers.)

GRN – Generic Routing Number

Request syntax : 


rtrv_entity([iid XXXXX,] id XXXXX, type <SP/RN/VMS/GRN>)
Retrieve the Information for a Range of NEs

Parameters :

id

Global title address for this network entity.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters

bid

Global title address for the first network entity in the range.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

eid

Global title address for the last network entity in the range.

Values:

1 to 15 hexadecimal digits expressed using ASCII characters.

type

(Optional) Type of network entity being deleted.

Values:

SP – Signal Point

RN – Routing Number (only available with G-Port, INP, A-Port, and IS-41 GSM Migration features)

VMS – Voicemail Server. (Used for V-Flex customers.)

GRN – Generic Routing Number

data

(Optional) Lets the requester specify the type of output data to be returned. See the response section for additional information.

Values:

all – Return all known data for each instance (default)

neonly – Return just the ID/type for each instance

count – Return only a instance count of all instances matching the query.

num

(Optional) Limits the number of entities to be returned. If the num parameter is omitted, all entities in the range are returned.

Values:

1 – 150000

Request syntax : 


rtrv_entity([iid XXXXX,] bid XXXXX, eid XXXXX, [type <SP/RN/VMS/GRN>,]
[[data ,all/neonly/count>], num <1..1000>])
Retrieve the Information for All NEs

Parameters :

num

(Optional) Limits the number of entities to be returned. If the num parameter is omitted, all entities are returned.

Values:

1 – 150000

Request syntax : 


rtrv_entity([iid XXXXX,] [num <1..150000>])
Retrieve Network Entity Responses

The data section for the responses of all rtrv_entity request types depends on the data parameter type specified in the request. If the data value is all, the data section contains a list of all instances that matched the request. It contains a segment parameter similar to the one in rtrv_sub for large range retrievals, followed by a list of network entities (news). With the exception of pctype, parameters whose values are none are not present in the response.


data ( segment #####, nes( (id XXXXX, type <SP/RN>, pctype
<intl/natl/ansi/none>, [pc <point code>,] [gc <group code>,]
ri <GT/SSN>, [ssn <0,2..225>,] ccgt <yes/no>, [ntt <0..255>,]
[nna <0..127>,] [nnp <0..15>,]
[da <replace/prefix/insert/delcc/delccprefix/spare1/spare2>,]
[srfimsi XXXXX,] counts([imsi ###,] [dn ###,] [dnblock ###])),
( ... ) )

As with the responses for retrieving subscriptions, the response can be broken up into multiple responses due to size constraints. Intermediate responses have the return code PARTIAL_SUCCESS.

If the data value is count, the data section contains only the number of instances that matched the query. 


data (counts(ne ###))

The return codes listed in Table 3-14 indicate the result of the Retrieve Network Entity request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-14 Retrieve Network Entity Response Return Codes

Return Code Text Description Data Section Contents

0

SUCCESS

The request succeeded and this is the last (or only) response.

See data description above.

1005

WRITE_UNAVAIL

Another client already has a write transaction open.

IP address information of client that already has the write transaction.

data (id <connection id>, ip <ip addr>, port <port num>)

1006

NO_WRITE_PERMISSION

PDBI client making request does not have write access permissions.

NONE

1009

NO_ACTIVE_TXN

There is no currently active transaction for this connection.

NONE

1012

INVALID_VALUE

One of the fields specified had an invalid value.

Offending field is returned in data section: data (param <field label>)

1013

NOT_FOUND

The requested id was not found.

NONE

1016

PARTIAL_SUCCESS

The request has succeeded, but this is only one response in many.

See data description above.

Switchover

The switchover command causes the two PDBAs to switch Active/Standby status. By default, the command works like a toggle switch. The PDBA receiving the request changes its status from Active to Standby or from Standby to Active and informs the other PDBA to do the opposite.The side parameter in the request specifies the desired status for the receiving PDBA. If this parameter is used, the receiving PDBA attempts to set itself to the requested status and tells the mate PDBA to set itself to the opposite status. If the two PDBAs are already in the desired states, no action is taken.

Because the goal of the switchover command is to change the Active/Standby status of the PDBA, and because write transactions can be done only on the Active PDBA, it is a requirement that no write transactions be active for a switchover to be performed. It is also a requirement that all asynchronous replication be completed before the switchover is permitted.

The switchover command has a timeout parameter (similar to the begin_txn command) to allow the command to wait for any existing write transactions to complete. If the switchover command is being sent to the standby side and the active side has a write transaction that was left open, sending the switchover command with the force parameter set to yes overrides the open write transaction; it also allows the switchover to occur. While this behavior is permitted, it is extremely dangerous to steal the write transaction from an active client.

If the write transaction is truly hung for whatever reason, it is much safer to stop and restart the PDBA that has the write transaction hung. If the switchover command is being sent to the active side while another client has the write transaction open, the switchover is unsuccessful with WRITE_UNAVAIL, even if the force option is used. The force option is also ignored if the databases are not yet synchronized.

By default, if a PDBA application receives a switchover request but the PDBA is unable to communicate with its mate PDBA, the request fails. An optional force parameter can be used to cause the receiving PDBA to ignore the fact that it cannot communicate with its mate and perform the switchover anyway. This option can be useful if communication between the two PDBAs has been broken, but the PDBA that was previously Standby needs to become Active.

Use the switchover command very carefully. It is possible to use this command in such a way that causes the two PDBs to be out of synch. When the PDBAs are successfully communicating, changing the Active/Standby status of either PDBA causes the other PDBA to change as well. However, if the two PDBAs are unable to communicate, then a switchover command received by one of them fails because it cannot inform the mate that a switchover is taking place. This failure ensures that both PDBAs do not think that they are the Active PDBA.

If the force parameter is used and both PDBAs become Active, it is the client’s responsibility to ensure that they are not both written to.

If updates are sent to both PDBs while they are not communicating with each other, the databases can become irreversibly out of synch. When the PDBAs see each other again, they detect the synchronization problem and force both PDBAs to be in Standby mode. Any attempt to switchover either PDBA to be active fails with the DB_MAINT_REQD return code until the problem is corrected. At that point, one PDB would have to be recreated from the other PDB, and the RTDB processes connected to the PDBA with the recreated PDB must reload (causing the cards on the EAGLEs also to reload).The PDBA that receives the switchover request attempts to change the state of the remote PDBA first and then change its own state. In the unlikely event that one of the PDBAs terminates during the handling of the switchover request, it is theoretically possible for the two PDBAs to be set to the same state. If this were to happen, the PDBAs automatically fix the situation when the software is restarted.This command can be issued only by client that have WRITE permission. It cannot be issued from inside a transaction, nor can any other PDBI clients (on either PDBA) have thewrite transaction open.

Switchover Request

Parameters :

side

(Optional) Specifies whether the receiving side is to be set to: Active or Standby. Without this parameter, the switchover command works like a toggle switch.

Values:

active – Set receiving side to Active.

standby – Set receiving side to Standby.

timeout

(Optional) Specifies how long to wait for an existing write transaction to complete.

Values:

0 (return immediately if not available; default)

1 –3600 seconds
force

(Optional) Forces the switch on the receiving side. This is useful when the two PDBA processes are unable to communicate (due to network problems or remote PDBA down) and you need to make the local PDBA Active anyway. By default, the local PDBA rejects a switchover request if it cannot communicate with the remote PDBA.

Values:

yes and no (default)

Request syntax : 


switchover([iid XXXXX,] [side <active/standby>],
[timeout <0-3600>], [force <yes/no>])

Switchover Response

The return codes listed in Table 3-15 indicate the result of the Switchover request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-15 Switchover Response Return Codes

Return Code Text Description Data Section Contents
0

SUCCESS

Switchover worked.

NONE

1012

INVALID_VALUE

One of the fields specified had an invalid value.

Offending field is returned in data section: data (param <field label>)

1007

NO_MATE

The PDBA could not negotiate a switchover with its mate. The switchover was denied.

NONE

1005

WRITE_UNAVAIL

There is another connection on this PDBA with the write transaction open.

The IP address information of the client that already has the write transaction.

data (id <connection id>, ip <ip addr>, port <port num>)

1006

NO_WRITE_PERMISSION

The connection requesting the switchover does not have WRITE permission.

NONE

1010

ACTIVE_TXN

The command was issued from within a transaction.

NONE

1026

MATE_BUSY

The mate PDBA currently has a write transaction open.

NONE

1030

DB_MAINT_REQD

Replication is unable to get the two databases in synch. Call Oracle.

NONE

1036 REPLICATING Asynchronous replication is still in progress. The number of levels remaining to replicate. data (levels <num>)
1043 BAD_SWITCH_IN_ABP The PDBA status is controlled by the PDBA Proxy feature and cannot be changed manually. Call Oracle for more information. NONE

PDBA Status Query

The status command queries status information from the PDBA. This command is not required to be framed inside a transaction. However, a connection must first be opened.

If the status request is made from within a transaction, the Number Prefix fields contain the values configured when the transaction started. Changes to the Number Prefixes from the user interface do not affect currently existing transactions.

If the status request is made from outside a transaction, the Number Prefixes contain the actual currently configured values. In either case, if there is no configured Number Prefixes in the user interface, the dnprefix and imsiprefix parameters are omitted to ensure backward compatibility.

Instance counts are shown as optional because certain entities/subscription types may not exist in the PDBA. For example, for clients that provision only NEs and DNs and no IMSIs (that is, G-Port), the IMSI counts are not returned.

PDBA Status Query Request

Parameters : None

Request syntax : 


status([iid XXXXX])

PDBA Status Query Response

The data section of a successful PDBA Status Query contains the following information:

  • PDBA version number

  • Active/Standby status

  • Mate connectivity – Whether or not this PDBA is connected to its mate PDBA.

  • DN prefix – The default number prefix that is currently configured for DNs and DN Blocks, if any.

  • IMSI prefix – The default number prefix that is currently configured for IMSI, if any.

  • DB Level

  • Birthdate – UNIX time_t value for time that the PDB was originally created.

  • Instance counts

    • IMSI

    • DN

    • DN block

    • NE

    • ReplLog 
      
data (version 1.0, side <active/standby>, mate
<present/absent>, dblevel #####, [dnprefix ####,]
[imsiprefix ####,] birthdate ##########, counts
([imsi #####,] [dn #####,] [dnblock #####,] [ne #####],)
[repllog #####])

The return code listed in Table 3-16 indicates the result of the PDBA Status Query request.

Table 3-16 PDBA Status Query Response Return Code

Return Code Text Description Data Section Contents

0

SUCCESS

Status query successful.

See description above.

Dump Connections

The dump_conn command requests the PDBA to dump connection information for debugging. This command is not required to be framed inside a transaction. However, a connection must first be opened.

Dump Connections Request

Parameters :

type

Which type of connection to display information for.

Values:

PDBI – PDBI Clients

RTDB – RTDB Clients

MAINT – Maintenance Clients

MATE – PDBA Mate

all – PDBI, RTDB, MAINT, and MATE (default)

Request syntax : 


dump_conn(iid XXXXX, [type <PDBI/RTDB/MAINT/MATE/all>])

Dump Connections Responses

The data section of a successful Dump Connections request contains the following syntax. The optional access parameter is returned only for PDBI connections.


data(connections((type <PDBI/RTDB/MAINT/MATE>, [id <connId>,]
ip <IP Addr>, port ####, [access <read/write>]), . . .
(type <PDBI/RTDB/MAINT/MATE>, [id <connId>,] ip <IP Addr>,
port ####, [access <read/write>]) ))

The return code listed in Table 3-17 indicates the result of the Dump Connections request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-17 Dump Connections Response Return Code

Return Code Text Description Data Section Contents

0

SUCCESS

Connection list returned.

See above.

1012

INVALID_VALUE

One of the fields specified had an invalid value.

Offending field is returned in data section:

data (param <field label>)

Create IMEI Data

This command creates either a single IMEI with its appropriate list type or a block of IMEIs with the associated list type. This command is also used to add additional IMSIs to a particular IMEI.

Create a Single Entry IMEI

This command is used to create a new IMEI. Using the optional force parameter changes the default behavior to overwrite any existing entry with the new data.

The ent_eir command defines the request message for a single entry IMEI.

Parameters :

imei

A single IMEI.

Values:

14 or 15 hexadecimal digits expressed using ASCII characters. Only the first 14 digits of the IMEI are stored and displayed on retrieval.

svn

(Optional) Software Version Number.

Values:

A 2-digit number 0-9 (default = 0).

allow

(Optional) Select list type of Allow.

Values:

yes or no (default = no).

gray

(Optional) Select list type of Gray.

Values:

yes or no (default = no).

block

(Optional) Select list type of block.

Values:

yes or no (default = no).

imsi

The IMSI(s) to be associated with an IMEI.

Values:

5 to 15 hexadecimal digits expressed using ASCII characters. Up to 8 IMSIs can be provisioned for an IMEI.

force

(Optional) Indicates whether the client wants existing instances to be overwritten.

Values:

yes or no (default = no)

timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 – 3600 seconds

Rules

  1. Each imei provisioned must reside on at least one list type (allow, gray, or block) and can also reside on any combination of 1, 2, or 3 lists concurrently.

  2. If the imei includes the optional 15th character (the check digit), the check digit is provided by the Customers Client Software and must match the EPAPs (via calculated algorithm). The check digit is not stored; it is only used to verify the imei.

  3. A individual imei supercedes an imei block range.

  4. Total command length must not exceed 247 characters.

    Note:

    Entering commands that exceed this length will result in the PDBI_CMD_LENGTH_EXCEEDED error (value 1045). In order to avoid this, remove unnecessary characters (including white space and parameters that are specified as the default value). If necessary, consider performing this provisioning in two steps by using an enter command followed by an update command.

Request syntax:


ent_eir( [iid XXXXX] imei XXXXX, [svn 0..99,] [allow yes/no,]
[grey yes/no,] [block yes/no,] [imsi XXXXX, ..., imsi XXXXX]
[force yes/no,] [timeout <0..3600>])
Create a Block Entry of IMEIs

The ent_eir command defines the request message for a block entry of IMEIs.

Parameters :

bimei

The beginning IMEI in a block.

Values:

14 or 15 hexadecimal digits expressed using ASCII characters. Only the first 14 digits of the IMEI are stored and displayed on retrieval.

eimei

The ending IMEI in a block.

Values:

14 or 15 hexadecimal digits expressed using ASCII characters. Only the first 14 digits of the IMEI are stored and displayed on retrieval.

allow

(Optional) Select list type of Allow.

Values:

yes or no (default = no).

gray

(Optional) Select list type of Gray.

Values:

yes or no (default = no).

block

(Optional) Select list type of block.

Values:

yes or no (default = no).

timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 - 3600 seconds

Rules

  1. Each imei provisioned must reside on at least one list type (allow, gray, or block) and can also reside on any combination of 1, 2, or 3 lists concurrently.

  2. If the imei includes the optional 15th character (the check digit), the check digit is provided by the Customers Client Software and must match the EPAPs (via calculated algorithm). The check digit is not stored; it is only used to verify the imei. The check digit is run on both the bimei and eimei when applicable.

  3. The svn is not provisionable on an imei block entry.

Request syntax:


ent_eir([[iid XXXXX] bimei XXXXX, eimei XXXXX, [allow yes/no,]
[grey yes/no,] [allow yes/no] [timeout <0..3600>])
Create a New IMSI and Associate it with an Existing IMEI

The ent_eir command defines the request message to create a new IMSI and associate it with an existing IMEI. This is the EIR specific IMSI, not the G-Port/G-Flex IMSI.

Parameters :

imei

A single IMEI.

Values:

14 or 15 hexadecimal digits expressed using ASCII characters. Only the first 14 digits of the IMEI are stored and displayed on retrieval.

imsi

The IMSI(s) to be associated with an IMEI.

Values:

5 to 15 hexadecimal digits expressed using ASCII characters. Up to 8 IMSIs can be provisioned for an IMEI.

timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 – 3600 seconds

Rules:

  1. If the imei includes the optional 15th character (the check digit), the check digit is provided by the Customers Client Software and must match the EPAPs (via a calculated by algorithm). The check digit is not stored; it is only used to verify the imei.

  2. Total command length must not exceed 247 characters.

    Note:

    Entering commands that exceed this length will result in the PDBI_CMD_LENGTH_EXCEEDED error (value 1045). In order to avoid this, remove unnecessary characters (including white space and parameters that are specified as the default value). If necessary, consider performing this provisioning in two steps by using an enter command followed by an update command.

Request syntax:


ent_eir( [iid XXXXX] imei XXXXX, [imsi XXXXX, …, imsi XXXXX]
[timeout <0..3600>])
Create IMEI Data Responses

The return codes in Table 3-18 may result from the Create IMEI request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-18 Create IMEI Response Return Codes

Return Code Text Description Data Section Contents
0 SUCCESS

Everything worked.

NONE
1005 WRITE_UNAVAIL

Another client already has a write transaction open.

IP address information of client that already has the write transaction.

data (id <connection id>, ip <ip addr>, port <port num>)

1006 NO_WRITE_PERMISSION

The PDBI client making request does not have write access permissions.

NONE
1009 NO_ACTIVE_TXN

There was no currently active transaction for this connection.

NONE
1011 WRITE_IN_READ_TXN

The create command was sent on a read only transaction.

NONE
1012 INVALID_VALUE

One of the fields specified had an invalid value.

The offending field is returned in the data section:

data (param <field label>)

1014 CONFLICT_FOUND

An entry was found already in database matching an element of this request. If force yes parameter is used, this error is not returned. Rather, existing instances are overwritten.

The offending existing element is returned.

data (imei XXXXX)

1017 NO_UPDATES

The database already contains data in request. No update was necessary.

NONE
1029 TXN_TOO_BIG

This request would cause current transaction to be larger than limit.

NONE
1037 CHECK_ DIGIT_ ERROR

The check digit provisioned did not match the calculated check digit.

imei, bimei, or eimei

data (param imei xxxxx)

1039 IMEI_IMSI_LIMIT

Would cause more than 8 IMSIs to be provisioned on an IMEI.

NONE
1040 MAX_IMEI_LIMIT

Exceeded the maximum number of individual IMEIs.

NONE
1041 MAX_IMEI_BLK_LIMIT

Exceeded the maximum number of IMEI blocks.

NONE
1058 IMSI_FULL Could not add new IMSI to the database. Adding new IMSI would exceed the supported SMxG card size. The other supported subscriptions are allowed if space is available on the corresponding SMxG card. NONE
1059 IMEI_FULL Could not add new IMEI to the database. Adding new IMEI would exceed the supported SMxG card size. The other supported subscriptions are allowed if space is available on the corresponding SMxG card. NONE
1062 IMSI_ENT_NOT_ALLOWED Could not add new IMSI to the database. The RTDB is either down or incoherent. Adding new IMSI requires creation of new IMSI table which may lead to over-allocation. NONE
1063 IMEI_ENT_NOT_ALLOWED Could not add new IMEI to the database. The RTDB is either down or incoherent. Adding new IMEI requires creation of new IMEI table which may lead to over-allocation. NONE

Update IMEI Data

This command allows the list types for an IMEI or SVN to be changed.

Update a Single Entry IMEI

This command is used to update an existing single entry IMEI.

The upd_eir command defines the request message to update a single entry IMEI.

Parameters :

imei

A single IMEI.

Values:

14 or 15 hexadecimal digits expressed using ASCII characters. Only the first 14 digits of the IMEI are stored and displayed on retrieval.

svn

(Optional) Software Version Number.

Values:

A 2-digit number 0-9 (default is not changed).

allow

(Optional) Select list type of Allow.

Values:

yes or no (default is not changed).

gray

(Optional) Select list type of Gray.

Values:

yes or no (default is not changed).

block

(Optional) Select list type of block.

Values:

yes or no (default is not changed).

timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 - 3600 seconds

imsi (optional)

Rules

  1. The resulting imei must have at least 1 list type (allow, gray or block) turned on.
  2. If the imei includes the optional 15th character (the check digit), the check digit is provided by the Customers Client Software and must match the EPAPs (via calculated algorithm). The check digit is not stored; it is only used to verify the imei.
  3. Limit imsi to 400 per imei.

Request syntax: 


upd_eir([iid XXXXX,] imei xxxxx, [svn 0..99,]
[allow yes/no,] [gray yes/no,] [block yes/no,]  
imsi xxxxx, …, imsi xxxxx,] [timeout <0..3600>])
Update a Block Entry of IMEIs

The upd_eir command defines the request message to update a block entry of IMEIs.

Parameters :

bimei

The beginning IMEI in a block.

Values:

14 or 15 hexadecimal digits expressed using ASCII characters. Only the first 14 digits of the IMEI are stored and displayed on retrieval.

eimei

The ending IMEI in a block.

Values:

14 or 15 hexadecimal digits expressed using ASCII characters. Only the first 14 digits of the IMEI are stored and displayed on retrieval.

allow

(Optional) Select list type of Allow.

Values:

yes or no (default is not changed).

gray

(Optional) Select list type of Gray.

Values:

yes or no (default is not changed).

block

(Optional) Select list type of block.

Values:

yes or no (default is not changed).

timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default) 1 - 3600 seconds

Rules

  1. The resulting imei must have at least 1 list type (allow, gray or block) turned on.

  2. If the imei includes the optional 15th character (the check digit), the check digit is provided by the Customers Client Software and must match the EPAPs (via calculated algorithm). The check digit is not stored; it is only used to verify the imei.

Request syntax:


upd_eir([iid XXXXX] bimei XXXXX, eimei XXXXX, [allow
yes/no,][grey yes/no,] [block yes/no,] [timeout <0..3600>]))
Update IMEI Data Responses

The return codes in Table 3-19 may result from the Update IMEI request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-19 Update IMEI Response Return Codes

Return Code Text Description Data Section Contents

0

SUCCESS

Everything worked.

NONE

1012

INVALID_VALUE

One of the fields specified had an invalid value.

The offending field is returned in the data section:

data (param <field label>)

1042

NO_LIST_FOR_IMEI

A minimum of 1 list type must be provisioned for the resulting IMEI.

NONE

1037

CHECK_ DIGIT_ ERROR

The check digit provisioned did not match the calculated check digit.

imei, bimei, or eimei

data (param imei xxxxx)

1013

NOT_FOUND

The requested IMEI or IMEI block was not found.

NONE

1011

WRITE_IN_READ_TXN

The update command was sent on a read only transaction.

NONE

1029

TXN_TOO_BIG

This request would cause current transaction to be larger than limit.

NONE

1017

NO_UPDATES

The database already contains the data in the request. No update was necessary.

NONE

1009

NO_ACTIVE_TXN

There was no currently active transaction for this connection.

NONE

1006

NO_WRITE_PERMISSION

The PDBI client making request does not have write access permissions.

NONE

1005

WRITE_UNAVAIL

Another client already has a write transaction open.

IP address information of client that already has the write transaction.

data (id <connection id>, ip <ip addr>, port <port num>)

Delete IMEI Data

This command is used to delete an individual IMEI or a IMEI block. This command is also used to delete an IMSI from the associated IMEI.

Delete a Single Entry IMEI

This command is used to delete a single entry IMEI and all associated IMSIs.

The dlt_eir command defines the request message to delete a single entry IMEI.

Parameters :

imei

A single IMEI.

Values:

14 or 15 hexadecimal digits expressed using ASCII characters. Only the first 14 digits of the IMEI are stored and displayed on retrieval.

timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 - 3600 seconds

Rules

  1. If the imei includes the optional 15th character (the check digit), the check digit is provided by the Customers Client Software and must match the EPAPs (via calculated algorithm). The check digit is not stored; it is only used to verify the imei.

Request syntax:


dlt_eir([iid XXXXX] imei XXXXX)
Delete a Block of IMEIs

The dlt_eir command defines the request message to delete an IMEI block.

Parameters :

bimei

The beginning IMEI in a block.

Values:

14 or 15 hexadecimal digits expressed using ASCII characters. Only the first 14 digits of the IMEI are stored and displayed on retrieval.

eimei

The ending IMEI in a block.

Values:

14 or 15 hexadecimal digits expressed using ASCII characters. Only the first 14 digits of the IMEI are stored and displayed on retrieval.

timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 - 3600 seconds

Rules

  1. If the imei includes the optional 15th character (the check digit), the check digit is provided by the Customers Client Software and must match the EPAPs (via calculated algorithm). The check digit is not stored; it is only used to verify the imei.

Request syntax:


dlt_eir([iid XXXXX,] bimei XXXXX, eimei XXXXX)
Delete IMSI(s) from the Associated IMEI

This command is used to delete the IMSI from the specified IMEI. This is the EIR specific IMSI, not the G-Port/G-FlexIMSI.

The dlt_eir command is used to delete the IMSI from the associated IMEI.

Parameters :

imei

A single IMEI.

Values:

14 or 15 hexadecimal digits expressed using ASCII characters. Only the first 14 digits of the IMEI are stored and displayed on retrieval.

imsi

The IMSI(s) to be associated with an IMEI.

Values:

5 to 15 hexadecimal digits expressed using ASCII characters. Up to 8 IMSIs can be provisioned for an IMEI.

all - used to remove all IMSIs associated withan IMEI.

timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 - 3600 seconds

Request syntax: 


dlt_eir([iid xxxxx,]imei XXXXX, imsi XXXXX[,….,imsi XXXXX])
Delete the IMSI from all IMEIs

This command is used to delete the IMSI from all IMEIs. This is the EIR specific IMSI, not the G-Port/G-FlexIMSI.

The dlt_eir command is used to delete the IMSI from all IMEIs.

Parameters :

imsi

The IMSI(s) reference to be deleted from the IMEI.

Values:

5 to 15 hexadecimal digits expressed using ASCII characters. Up to 8 IMSIs can be provisioned for an IMEI.

timeout

(Optional) Specify the number of seconds to wait for the write transaction if another connection already has it. Clients waiting for the write transaction with this mechanism are processed in the order that their requests were received. This option is only allowed if the client used the txnmode single option on its connect request.

Values:

0 (return immediately if not available; default)

1 - 3600 seconds

Request syntax: 


dlt_eir([iid XXXXX,]imsi XXXXX)
Delete IMEI Data Responses

The return codes in Table 3-20 may result from the Delete IMEI request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-20 Update IMEI Response Return Codes

Return Code Text Description Data Section Contents
0

SUCCESS

Everything worked.

NONE

1012

INVALID_VALUE

One of the fields specified had an invalid value.

The offending field is returned in the data section:

data (param <field label>)

1037

CHECK _DIGIT _ERROR

The check digit provisioned did not match the calculated check digit.

imei, bimei, or eimei

data (param imei xxxxx)

1013

NOT_FOUND

The requested IMEI or IMEI block was not found.

NONE

1038

IMSI_NOT_FOUND

IMSI not found on specified IMEI.

NONE

1011

WRITE_IN_READ_TXN

The delete command was sent on a read only transaction.

NONE

1029

TXN_TOO_BIG

This request would cause current transaction to be larger than limit.

NONE

1017

NO_UPDATES

The database already contains the data in the request. No update was necessary.

NONE

1009

NO_ACTIVE_TXN

There was no currently active transaction for this connection.

NONE

1006

NO_WRITE_PERMISSION

The PDBI client making request does not have write access permissions.

NONE

1005

WRITE_UNAVAIL

Another client already has a write transaction open.

IP address information of client that already has the write transaction.

data (id <connection id>, ip <ip addr>, port <port num>)

Retrieve IMEI Data

This command displays the provisioned IMEI data.

Retrieve All the Data Associated with a Single IMEI Entry

This command is used to retrieve the IMEI data specified. If the IMEI specified is not found in the individual entry table but resides in an IMEI block, then that IMEI block will be displayed.

The rtrv_eir command defines the request message to retrieve all the data associated with a single IMEI entry.

Parameters :

imei

A single IMEI.

Values:

14 or 15 hexadecimal digits expressed using ASCII characters. Only the first 14 digits of the IMEI are stored and displayed on retrieval.

Rules

  1. If the imei includes the optional 15th character (the check digit), the check digit is provided by the Customers Client Software and must match the EPAPs (via calculated algorithm). The check digit is not stored; it is only used to verify the imei.

Request syntax:


rtrv_eir([iid XXXXX,] imei XXXXX)
Retrieve IMEI Data: Retrieve a Range of IMEIs

This command is used to retrieve either a range of individual IMEI(s) or IMEI blocks.

Parameters :

bimei

The beginning IMEI in a block.

Values:

14 or 15 hexadecimal digits expressed using ASCII characters. Only the first 14 digits of the IMEI are stored and displayed on retrieval.

eimei

The ending IMEI in a block.

Values:

14 or 15 hexadecimal digits expressed using ASCII characters. Only the first 14 digits of the IMEI are stored and displayed on retrieval.

type

(Optional) IMEI blocks or single IMEI.

Values:

block - Searches the IMEI Block table. Only reports IMEI Blocks, regardless of whether any provisioned Single IMEIs fall within the specified number range.

single (default) - Searches the Single IMEI table. Only IMEIs provisioned as Single IMEIs are returned, regardless of whether the IMEI number falls within the number range of a provisioned IMEI block.

allow

(Optional) Filters request to retrieve the IMEIs found on the Allow list.

Values:

yes or no (default = no filter).

gray

(Optional) Filters request to retrieve the IMEIs found on the Gray list.

Values:

yes or no (default = no filter).

block

(Optional) Filters request to retrieve the IMEIs found on the block list.

Values:

yes or no (default = no filter).

imsi

(Optional) Filters request to retrieve the IMEIs on the specified IMSI.

Values:

5 to 15 hexadecimal digits expressed using ASCII characters (default= none). Only valid when type is single.

data

(Optional) Specifies type of output data.

Values:

all (default) - Returns all known data for each instance.

count - Return a single instance count of all instances matching the query.

num

(Optional) Limits number of entities returned. If omitted, all entities are returned.

Values:

0 - 40000000

Rules

  1. If the imei includes the optional 15th character (the check digit), the check digit is provided by the Customers Client Software and must match the EPAPs (via calculated algorithm). The check digit is not stored; it is only used to verify the imei.

Request syntax:


rtrv_eir([iid XXXXX,] bimei XXXXX, eimei XXXXX, [type
<block/single>,] [allow <yes/no>,] [gray <yes/no>,] [block
<yes/no>,] [imsi XXXXX] [data <all/count>] [num 0..40000000])
Retrieve IMEI Data Responses

The syntax of the data section of responses to a successful Retrieve IMEI request depends on the type of records being returned. Both single IMEI and range IMEIs data is supported. Each type of data being returned has a different syntax.

  • Response syntax for an IMEI single query: 

    
data (segment XXXXX,
imeis (imei(id XXXXX, svn ##, allow yes/no, gray yes/no, block yes/no, [imsis (xxxxx, ....  xxxxx....)),
. . .
( . . . ) ) )

  • Response syntax for an IMEI block query: 

    
data (segment XXXXX,
meiblock (imeiblock (bimei xxxxx, eimei xxxxx, allow yes/no, gray yes/no, block yes/no, ),
. . .
( . . . ) ) )

  • Response syntax for an IMEI count query: 

    
data (counts (imei #####)
data (counts (imeiblock #####)

The return codes listed in Table 3-21 indicate the result of the Retrieve IMEI request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-21 Retrieve IMEI Response Return Codes

Return Code Text Description Data Section Contents

0

SUCCESS

Everything worked.

NONE

1011

NOT_FOUND

IMEI (block) not found.

NONE

1012

INVALID_VALUE

One of the fields specified had an invalid value.

Offending field is returned in data section:

data (param <field label>)

1016

PARTIAL_SUCCESS

The request has succeeded, but this is only one of many responses.

Depends on the request type, etc.

1029

NO_ACTIVE_TXN

There is no currently active transaction for this connection.

NONE

1037

CHECK_ DIGIT _ERROR

The check digit provisioned did not match the calculated check digit.

imei, bieme or eimei

data (param imei xxxxx)

1038

IMSI_NOT_FOUND

The IMSI requested as part of the filter does not exist .

NONE

Request Service Module Card Report

This command is used to retrieve the Service Module card Report in a synchronous manner. This command is not required to be sent from inside a transaction.

Retrieve the Service Module Card Report Request

There are two parameters that adjust what percent or level to run the report for. The two parameters are mutually exclusive. If neither is specified, then the report will be run with the default percent value for the connection. The caller can also specify whether or not they want the Service Module card exception list.

The rtrv_dsmrpt command defines the request message to retrieve the Service Module card report data.

Parameters :

percent

(Optional) The percent to use for this one report. Cannot be specified with level.

Values:

1 – 100

level

(Optional) Specific database level to use for this one report. Cannot be specified with percent.

Values:

1 – 4294967295

data

(Optional) Lets the requester specify whether or not they want to the see list of Service Module cards that were not at the main database level mentioned in the report.

Values:

status (default) - Return the list of Service Module cards.

none – Do not return the list of Service Module cards.

Request syntax: 


rtrv_dsmrpt([iid XXXXX,] [percent ###], [level #####], [data
<none/except>])

Request Service Module Card Report Response

The data section of a successful Service Module card report request contains the following information:

Parameters :

segment

This parameter contains the message segment number.

Values: ≥ 1 – Incrementing integer starting from 1.

level

The database level that the report is referring to. The Service Module cards that satisfy the report have levels equal to or greater than this value.

Values: 0 – 4294967295

percent

The percentage of known Service Module cards that meet or exceed the level

specified.

Values: 0 – 100

numdsms

The total number of known Service Module cards in the customer's network.

Values: 0 – ####

dsms

List of Service Module cards that did not have a database level equal to or larger than main message's level. Each Service Module card contains the following information.

clli
Identifier for the Service Module card's EAGLE node. Values: String up to 11 characters long
cardloc

Location identifier for the Service Module card in the EAGLE node. Values: Four digit number

status

The database status of the Service Module card.

Values: loading - The card is currently loading the database.

resync - The card is loaded, but catching up to current provisioning stream.

coherent - The database is loaded and receiving normal provisioning

incoherent - Internal error on Service Module card (write failed to database)

inconsistent - Data mismatch between EPAP RTDB and Service Module card RTDB.

corrupt - Internal error on Service Module card checksum failure).

level - The database level for this card.

Values: 0 – 4294967295

loadperc - The percent of the database that has been loaded during initial booting of the card. This field is only meaningful when the status is loading, so it will only appear then.

Values: 0 – 100


rsp([iid XXXX,] rc 0, data (segment ###, level ####, percent <0..100>, numdsms ####,
    dsms (
     dsm (clli AAAA, cardloc ####, status <values below>, level #### [, loadperc <0..100>]),
     . . .
     dsm (. . .) ) )

The return codes listed in Table 3-22 indicate the result of the Retrieve Service Module card report request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-22 Retrieve Service Module Card Report Response Return Codes

Return Code Text Description Data Section Contents

0

SUCCESS

Everything worked.

See above.

1012

INVALID_VALUE

One of the fields specified had an invalid value.

Offending field is returned in data section:

data (param <field label>)

1016

PARTIAL_SUCCESS

The request has succeeded, but this is only one of many responses.

Depends on the request type, etc.

Retrieve Service Module Card Report

There are two parameters that adjust what percent or level to run the report for. The two parameters are mutually exclusive. If neither is specified, then the report will be run with the default percent value for the connection. The caller can also specify whether or not they want the Service Module card exception list.

The rtrv_dsmrpt command defines the request message to retrieve the Service Module card report data.

Parameters :

percent

(Optional) The percent to use for this one report. Cannot be specified with level.

Values:

1 – 100

level

(Optional) Specific database level to use for this one report. Cannot be specified with percent.

Values:

1 – 4294967295

data

(Optional) Lets the requester specify whether or not they want to the see list of Service Module cards that were not at the main database level mentioned in the report.

Values:

status (default) - Return the list of Service Module cards.

none – Do not return the list of Service Module cards.

Request syntax: 


rtrv_dsmrpt([iid XXXXX,] [percent ###], [level #####], [data
<none/except>])

Retrieve Service Module Card Report: Response

The data section of a successful Service Module card report request contains the following information:

Parameters :

segment

This parameter contains the message segment number.

Values: ≥ 1 – Incrementing integer starting from 1.

level

The database level that the report is referring to. The Service Module cards that satisfy the report have levels equal to or greater than this value.

Values: 0 – 4294967295

percent

The percentage of known Service Module cards that meet or exceed the level

specified.

Values: 0 – 100

numdsms

The total number of known Service Module cards in the customer's network.

Values: 0 – ####

dsms

List of Service Module cards that did not have a database level equal to or larger than main message's level. Each Service Module card contains the following information.

clli

Identifier for the Service Module card's EAGLE node. Values: String up to 11 characters long

cardloc

Location identifier for the Service Module card in the EAGLE node. Values: Four digit number

status

The database status of the Service Module card.

Values: loading - The card is currently loading the database.

resync - The card is loaded, but catching up to current provisioning stream.

coherent - The database is loaded and receiving normal provisioning

incoherent - Internal error on Service Module card (write failed to database)

inconsistent - Data mismatch between EPAP RTDB and Service Module card RTDB.

corrupt - Internal error on Service Module card checksum failure).

level - The database level for this card.

Values: 0 – 4294967295

loadperc - The percent of the database that has been loaded during initial booting of the card. This field is only meaningful when the status is loading, so it will only appear then.

Values: 0 – 100


rsp([iid XXXX,] rc 0, data (segment ###, level ####, percent <0..100>, numdsms ####,
    dsms (
     dsm (clli AAAA, cardloc ####, status <values below>, level #### [, loadperc <0..100>]),
     . . .
     dsm (. . .) ) )

The return codes listed in Table 3-23 indicate the result of the Retrieve Service Module card report request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-23 Retrieve Service Module Card Report Response Return Codes

Return Code Text Description Data Section Contents

0

SUCCESS

Everything worked.

See above.

1012

INVALID_VALUE

One of the fields specified had an invalid value.

Offending field is returned in data section:

data (param <field label>)

1016

PARTIAL_SUCCESS

The request has succeeded, but this is only one of many responses.

Depends on the request type, etc.

Retrieve a List of the Service Module Cards

This command is used to retrieve all or a subset of the Service Module cards known to the PDBA. It does not need to be sent from inside a transaction. This request is different that the Service Module card Report in that it does not attempt to determine any percent complete at a given level. It simply returns all of the Service Module cards that meet the filter criteria.

The rtrv_dsmlist command defines the request message to retrieve the Service Module card data.

Parameters :

clli

(Optional) Retrieve only the Service Module cards on the specified EAGLE node.

Values:

1 - 11 alphanumeric characters, hyphen, or underscore.

cardloc

(Optional) Retrieve only the Service Module cards that are in the specified card location.

Values:

Four digit number.

status

(Optional) Retrieve only the Service Module cards that have the specified database status.

Values:

loading - The card is currently loading the database.

resync - The card is loaded, but catching up to current provisioning stream.

coherent - The database is loaded and receiving normal provisioning

incoherent - Internal error on Service Module card (i.e. write failed to database)

inconsistent - Data mismatch between EPAP RTDB and Service Module card RTDB.

corrupt - Internal error on Service Module card (checksum failure)

data

(Optional) Debugging option. Lets the requester specify whether they want to the see all available information the PDBA has about cards.

Values:

status – Return the standard list of data for each card (default)

all – Return additional debug information

Request syntax: 


rtrv_dsmlist([iid XXXXX,] [clli XXXX], [cardloc ####], [status
<value list above>])

Retrieve a List of the Service Module cards Response

The data section of a successful PDBA Status Query request contains the following information:

Parameters :

segment

This parameter contains the message segment number.

Values: ≥ 1 - Incrementing integer starting from 1.

dsms

List of Service Module cards that did not have a database level equal to or larger than main message's level. Each Service Module card contains the following information.

clli

Identifier for the Service Module card's EAGLE node. Values: String up to 11 characters long

cardloc

Location identifier for the Service Module card in the EAGLE node. Values: four-digit number

status

The database status of the Service Module card.

Values: loading - The card is currently loading the database.

resync - The card is loaded, but catching up to current provisioning stream.

coherent - The database is loaded and receiving normal provisioning

incoherent - Internal error on Service Module card (write failed to database)

inconsistent - Data mismatch between EPAP RTDB and Service Module card RTDB.

corrupt - Internal error on Service Module card checksum failure).

level - The database level for this card.

Values: 0 – 4294967295

loadperc - The percent of the database that has been loaded during initial booting of the card. This field is only meaningful when the status is loading, so it will only appear then.

Values: 0 – 100


rsp([iid XXXX,] rc 0, data (segment ###, level ####, percent <0..100>, numdsms ####,
    dsms (
     dsm (clli AAAA, cardloc ####, status <values below>, level #### [, loadperc <0..100>]),
     . . .
     dsm (. . .) ) )

The return codes listed in Table 3-24 indicate the result of the Retrieve Service Module card list report request. See PDBI Message Error Codes for the recommended actions to help resolve the error related return codes.

Table 3-24 Retrieve Service Module Card List Response Return Codes

Return Code Text Description Data Section Contents

0

SUCCESS

Everything worked.

See above.

1012

INVALID_VALUE

One of the fields specified had an invalid value.

Offending field is returned in data section:

data (param <field label>)

1013

NOT_FOUND

There were no Service Module cards found. If one or more filters were specified, then there were no cards that matched the filter

NONE

1016

PARTIAL_SUCCESS

The request has succeeded, but this is only one of many responses.

Depends on the request type, etc.