# &adminguide;

## Overview

This is a module for fast number portability handling. The client is this module and the server exists in the /utils/pdbt directory. The PDB module and server supports load-balancing and aggressive timeouts. Normally it does not need more than a few ms to query the remote server and return the reply to the configuration script.

The pdb module allows &kamailio; to send queries to a list of servers and store the answer in an AVP. The idea is to ask all servers in parallel and use the first answer, that comes back. A timeout for the query can be defined in milliseconds. The querying can be activated and deactivated using FIFO commands.

More about the new communication protocol between this module and pdb_server can be found in utils/pdbt/docs/network_protocol.txt. The current version is 1.

## Dependencies

### &kamailio; Modules

The module depends on the following modules (in other words the listed modules must be loaded before this module):

- none

### External Libraries or Applications

The following libraries or applications must be installed before running &kamailio; with this module loaded:

- The PDB server

## Parameters

### `timeout` (integer)

This is the timeout in milliseconds for the pdb_query function.

Default value is 50.

#### Set `timeout` parameter

    ...
    modparam("pdb", "timeout", 10)
    ...

### `server` (string)

This is the list of servers to be used by the pdb_query function. Queries will be sent in parallel to all servers configured in this list. This parameter is mandatory.

#### Set `server` parameter

    ...
    modparam("pdb", "server", "localhost:10001,host.name:10001,192.168.1.7:10002")
    ...

### `ll_info` (int)

Local log level (per module) for specific INFO messages. It has to be a valid log level value (see xlog() function from xlog module for more details).

Default value is 2.

#### Set `ll_info` parameter

    ...
    modparam("pdb", "ll_info", 3)
    ...

## Functions

### `pdb_query (string query, string dstpv)`

Sends the query string to all configured servers and stores the answer in dstvp. If it takes more than the configured timeout, false is returned. In addition to a string, any pseudo-variable can be used as query. The answer must consist of the null terminated query string followed by a two byte integer value in network byte order. The integer value will be stored in the given pseudo-variable dstvp.

#### `pdb_query` usage

    ...
    # query external service for routing information
    if (!pdb_query("$rU", "$avp(routing)"))
      $avp(routing) = 0; # default routing
    }
    cr_route("$avp(routing)", "$rd", "$rU", "$rU", "call_id");
    ...

## RPC Commands

### pdb.status

Prints the status of the module. This can either be "active" or "deactivated".

#### `pdb.status` usage

    ...
    &kamctl; rpc pdb.status
    ...

### pdb.timeout

Prints the current PDB query timeout value. This can also be used to set the PDB query timeout.

#### `pdb.timeout` usage

    ...
    # get the PDB query timeout
    &kamctl; rpc pdb.timeout
    # set the PDB query timeout to 10ms
    &kamctl; rpc pdb.timeout 10
    ...

### pdb.activate

Activates the module. This is the default after loading the module.

#### `pdb.activate` usage

    ...
    &kamctl; rpc pdb.activate
    ...

### `pdb.deactivate`

Deactivates the module. No more queries are performed until it is activated again. As long as the module is deactivated, the pdb_query function will return -1.

#### `pdb.deactivate` usage

    ...
    &kamctl; rpc pdb.deactivate
    ...