37 Adding New Client Applications

Learn how to add new client applications and how those applications function within the Oracle Communications Billing and Revenue Management (BRM) system.

Topics in this document:

• About Adding New Client Applications

• Implementing Timeout for Requests in Your Application

• Configuring Your Custom Application

• Creating a Client Application in C

• Using the Sample Applications

• About Adding Virtual Column Support to Your Applications

About Adding New Client Applications

Client applications can be virtually any type of program, including GUI-based tools, Web-based tools, network-enabled applications, batch jobs, cron jobs, and so on. You can write custom application programs to create, manipulate, delete, and display custom objects, which in turn implement a business policy.

The most common custom application captures external events of some type; for example, number of bytes downloaded from a web page. These events are then submitted to BRM, details of the event stored, and the event charges assessed if necessary.

BRM includes a set of client libraries that make it easier to create custom applications. Existing BRM applications use these client libraries. For more information about the libraries, see "About the BRM Client Access Libraries".

You can use the following options when you add custom applications to BRM:

• Using Existing System Opcodes

• Using Custom Opcodes

• Using a Custom Data Manager (DM)

Using Existing System Opcodes

You use the base opcodes to create, read, write, delete, and search objects. The base opcodes also provide programmatic access to transaction commands. More complex opcodes are implemented by the Facilities Modules (FMs). You use the policy opcodes to implement business decisions. These higher-level opcodes are translated by the FMs to base opcodes and sent to Data Managers (DMs) for processing.

In a client application, you use opcodes to record events such as purchasing a charge offer, changing a credit limit, creating an account or service, changing customer information, verifying a password, and looking up names and addresses.

In your application, you can call any of the BRM opcodes without changing the BRM system. You need to determine when to use a particular system opcode, what constitutes an event, and then call the appropriate opcode in your application.

Your application must include the header files corresponding to the opcodes you use. All FM opcodes include the header file for base opcodes, so you do not need to include it unless your application uses only base opcodes.

Using Custom Opcodes

If the system opcodes do not provide the required functionality, you can create custom opcodes. However, you must implement your new opcodes in a custom FM and configure the custom FM with each Connection Manager (CM).

For the application to communicate with the custom FM, the application and the FM have to agree on the opcodes to pass and the contents of their input and output flists, error buffers, and flags. The custom FM translates the new opcodes into base opcodes. Then, it can send the opcodes directly to a DM, or it can call other opcodes implemented by the standard FMs.

You call the custom opcodes in the same way with the same API by using PCM_OP() as the system opcode. Therefore, you must supply all the parameters, just as in the case of a system opcode.

Create a header file in which you define your custom opcodes. Include the header file in both the application and the custom FM source files. Compile the application and the custom FM with the new header file.

For examples of including opcodes in the header file, see the header files (.h) in the BRM_home/include directory, where BRM_home is the directory in which the BRM server software is installed.

Tip:

Defining your custom opcodes in a separate .h file helps you avoid updating FM header files when you upgrade to a new release of BRM.

Using a Custom Data Manager (DM)

Your application can communicate with a custom DM if the custom DM and the application agree on the semantics of the input and return flists.

You attach fields to the input flist that have meaning to the custom DM. These new fields act as opcodes to the custom DM. The return flist is the mirror image of the input flist in the sense that the application and custom storage manager agree on the meaning of the field-value pairs returned by the storage manager. The storage manager is responsible for setting error buffer values.

You create new fields with the PIN_MAKE_FLD macro. For information on the PIN_MAKE_FLD macro, see pcm.h in the BRM_home/include directory for field value ranges and examples of PIN_MAKE_FLD.

Tip:

To avoid updating the Portal .h files every time you upgrade BRM, define your custom fields in a separate header file and include that file in your application.

Implementing Timeout for Requests in Your Application

You can specify a timeout value for each connection to the CM. This enables you to set different timeout values for different operations. For example, you can set different timeout values for authorization and stop-accounting requests, or you can dynamically increase or decrease the timeout value for different operations based on the system load.

To specify a timeout value in milliseconds for a connection, pass the PIN_FLD_TIMEOUT_IN_MS field in the input flist to the PCM_CONTEXT_OPEN function. The PIN_FLD_TIMEOUT_IN_MS value is applicable after the client connects to the server. Before the connection occurs, this setting is not effective. It does not report a timeout if the client cannot connect to the server at all.

The timeout value you specify applies to all the opcodes called during that open session and overrides the value in the client configuration file. You must ensure that your client application handles the timeout, closes its connection to the CM by calling PCM_CONTEXT_CLOSE, and cleans up the transaction context.

Note:

When the timeout occurs, the CM does not provide any feedback about the success or failure of the request it received. When the CM detects the closed connection, it rolls back the ongoing transaction and shuts down.

Configuring Your Custom Application

You must set up the following applications to access the same database schema:

• The client application

• At least one CM

• At least one DM

The client application makes the connection by using the BRM database number in all three configuration files: the application's, the CM's, and the DM's. The database number is arbitrary, but it is determined before the system is installed. After the system is installed, you cannot change this number because it is encoded in every object in the database schema.

The client application must use POIDs with the correct database number. The system routes object requests on the basis of POIDs, which include the database number.

In your custom application, use the database number returned by PCM_CONNECT(). If you are using PCM_CONTEXT_OPEN(), call PCM_GET_USERID() and then PIN_POID_GET_DB() on the POID.

Caution:

Do not get the database number or the userid POID from the configuration file by calling pin_conf() in your application.

Creating a Client Application in C

You write client applications by using the PCM opcodes, which send and receive flists to the BRM database. Each opcode has a corresponding input and return flist.

Flists are used to hold return values for two important reasons:

• The macro call itself does not return a value.

• An flist can contain an arbitrary number of fields and values that is frequently not known in advance.

Your custom applications must include the header files that correspond to the FM opcodes you use. Which file to include depends on which opcodes you use. The header file for base opcodes needs to be included if you are using only base opcodes, which is unlikely.

You use the PCM_OP() macro to pass PCM opcodes and flists to BRM. The system returns an flist. You create input flists for the call to PCM_OP() and routine returns the results in an flist. You use the return flists and then destroy them.

The following pseudo-code shows the format of most client programs:

#include "pcm.h"
/* header file corresponding to the FM opcode you're using */
#include "ops/file.h" 
#include "pin_errs.h"
    main()
     .
     .
     .
         /* open a database context */
         PCM_CONTEXT_OPEN()
  
        /* clear error buffer */
         PIN_ERRBUF_CLEAR(&ebuf);
  
        /* send opcode to system, based on user activity or application
            function. */
  
PCM_OP(input_flist, opcode, return_flist, &ebuf)
  
        /* check for errors */
         if (PIN_ERRBUF_IS_ERR(&ebuf)) {
             /* handle error */
         } else {
             /* ok - no errors */
         }
         .
         .
         .
  
        /* close database context */
         PCM_CONTEXT_CLOSE()
     .
     .
     .
     exit(0);

Compiling and Linking Your Programs

You do not have to follow any special precompilation or other steps to compile and link applications. Both static and dynamic versions of BRM libraries are provided.

Linux client libraries are multi-thread safe.

To compile and link your application:

1. Compile using the include files in the BRM_SDK_home/include directory.

2. Link to the libraries in BRM_SDK_home/lib.

   See the sample applications and their make files for more information.

Table 37-1 lists the supported compilers:

Table 37-1 Supported Compilers

Operating System	Compiler
Linux	gcc compiler

Guidelines for Developing Applications in C on Linux Platforms

Follow these guidelines to develop custom applications in C on Linux:

• Include the appropriate library file at link time: libportal.so for Linux

• Add BRM_SDK_home/include to the list of include file directories to search.

• In the preprocessor directives, be sure to include the following symbol:

  PIN_USE_ANSI_HDRS.

Using the Sample Applications

BRM SDK includes sample applications and code and source code for policy FMs that you can refer to for coding examples.

Sample Applications

BRM SDK includes sample applications and code in C, C++, Java, and Perl. For a complete list of the sample applications, see "Sample Applications" in BRM Developer's Reference.

Before you write your program, try compiling and linking copies of these programs to familiarize yourself with the system. These programs are located in BRM_SDK_home/source/samples. This directory also includes a sample application configuration file.

Caution:

Do not run the sample programs on a production system. Some programs fill the database with test objects. Remove the test objects before building your production system.

Policy FM Source Files

BRM SDK includes the source code for all the policy opcodes. You can refer to them for BRM coding examples. You can find the Customer Policy FM opcode source files in BRM_SDK_home/source/sys. Each policy FM has its own directory containing the source files for the included opcodes and a make file and other support files.

About Adding Virtual Column Support to Your Applications

This section explains the programming considerations of creating an application to work with BRM virtual columns and applies to custom applications that interact with the BRM database directly. For information about using virtual columns in the BRM database, see the discussion on generating virtual columns in BRM System Administrator's Guide.

Caution:

• Always use the BRM API to manipulate data. Changing data in the database without using the API can corrupt the data.

• Do not use SQL commands to change data in the database. Always use the API.

Custom applications can perform read operations on virtual columns but cannot perform update or insert operations. The values of virtual columns are computed dynamically, and attempts to modify them directly result in an error.

BRM creates virtual columns for the POID field_name_type columns on event tables in the BRM database. If your custom applications must update or insert data in these physical columns after they have been converted to virtual columns, you must make your applications interact with the virtual columns' respective supporting column.

Each BRM virtual column is associated with a supporting column that stores the storable class ID. The supporting columns can be modified and use the suffix field_name_type_id (the virtual columns use the suffix field_name_type).

The following examples demonstrate how custom applications can perform update and insert operations on the supporting columns of physical columns that have become virtual-column enabled.

Note:

The get_object_id function shown in the examples is available in the PIN_VIRTUAL_COLUMNS package.

Consider a table event_t with virtual column session_obj_type. The virtual column has a session_obj_type_id supporting column, which stores the ID corresponding to the type value of the virtual column.

• Update operation example

  Any custom application/PL/SQL updating the column session_obj_type using SQL

  update event_t set session_obj_type = ‘/service/telco';
  

  will have to be modified to

  update event_t set session_obj_type_id = pin_virtual_column.get_object_id(‘/service/telco');
  

• Insert operation example

  Any custom application/PL/SQL inserting values into column session_obj_type with SQL

  insert into event_t (poid_type) values (pin_virtual_columns.get_object_id('/event'));
  

  will have to be modified to

  insert into event_t (poid_type_id) values (pin_virtual_columns.get_object_id('/event'));