A 2 ZEE :- Test Nap erros and debugging

--------------------------------------------------------------------------------


About this document

About adding new client applications

Ways to add custom applications

Using existing system opcodes

Using custom opcodes

Using a custom Data Manager (DM)

Handling transactions

Configuring your custom application

Creating a client application in C

Compiling and linking your programs

Guidelines for developing applications in C on Windows

Guidelines for developing applications in C on UNIX platforms

Using the sample applications

Sample applications

Policy FM source files

Adding Branded Service Management to your application

The brand as an independent virtual workspace

Data scoping

Pointing a base level object to a brand account

Defining a brand account

Providing access to brands

Branding access permissions

Providing access to pricing information

Billing groups

Providing billing group access with an Access Control List (ACL)

Managing custom applications

Creating brands programmatically

Writing brand-aware applications

Displaying a list of user authorized brands

Setting the current connection scope

About adding multidatabase support to your applications

About working with multiple databases

Creating accounts

Maintaining transactional integrity

Working with replicated objects

Searching for accounts across databases

Searching for a single account

Searching for multiple accounts (global search)

Finding out how many databases you have with testnap

Bill numbering


--------------------------------------------------------------------------------

About this document



This section describes how to add new client applications and how these applications function within the Infranet® system. It includes general information about writing client applications in all supported languages as well as specific information about writing applications in C. The section also contains links to sample applications and their corresponding Makefiles.

To create a custom application that communicates with Infranet, you need to understand the following Infranet components:


Storable classes and storable objects
See Understanding Infranet Flists and Storable Classes.


Portal Object ID (POID) management routines
See Portal object ID (POID).


Flists and flist routines
See About flists.


PCM opcodes and the PIN library routines
See Understanding the PCM API and the PIN Library.


Error-handling routines
See Understanding API Error Handling and Logging.

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 storable objects, which in turn implement a business policy.

The base Infranet system comes with a set of client applications that manipulate storable objects within the database. You may, however, require custom applications. The most common custom application captures external events of some type. These events are then submitted to Infranet, details of the event stored, and the event charges assessed if necessary.

For example, a Web hosting application needs to track the number of bytes downloaded and disk space used. This requires an application to analyze disk-space usage and send it to the Rating EM at the end of each month. This also requires a new event type and new policy code that picks the rate category or quantity for the event.

Web servers don't provide an API to display the web usage automatically, so you might want to write an application that looks at the Web log files and generates events in Infranet. Because of the potential number of records in the Web logs, you can aggregate the data externally, and then send the summary to Infranet as events daily or monthly.

Infranet includes a set of client libraries that make it easier to create custom applications. Existing Infranet applications use these client libraries. These libraries are supported on Solaris, AIX, HP-UX, Windows 95, Windows 98, Windows 2000, and Windows NT. For more information about the libraries, see About the Infranet client access libraries.

For guidelines on writing Windows applications, see Guidelines for developing applications in C on Windows.

Ways to add custom applications



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


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 storable 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.

For more information on the different categories of opcodes and how they are used, see Understanding the PCM API and the PIN Library.

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

In your application, you can call any of the Infranet opcodes without changing the Infranet 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 don't need to include it unless your application uses only base opcodes.

For a list of opcodes and their corresponding header files, see Header files.

Using custom opcodes
If the system opcodes don't 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.

For information on how to create a custom FM and link it to a CM, see Writing a Custom Facilities Module.

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 pcm_ops.h in the Infranet_home/include directory.

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 Infranet.


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.

For information on creating and implementing a custom DM, see Writing a Custom Data Manager.

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

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


Handling transactions



Infranet provides three basic transaction opcodes:


PCM_OP_TRANS_OPEN()

PCM_OP_TRANS_ABORT()

PCM_OP_TRANS_COMMIT()
In your application, you can call PCM_OP_TRANS_OPEN() before calling an opcode and PCM_OP_TRANS_ABORT() or PCM_OP_TRANS_COMMIT() after the opcode calls. However, by default, all opcodes except the password opcodes are surrounded by transactions if transactions are not open when they are called.

Configuring your custom application



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


The client application

At least one CM

At least one DM
The client application makes the connection by using the Infranet 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. Once the system is installed, you can't change this number because it is encoded in every storable object in the database.

The client application must use POIDs with the correct database number. The system routes storable 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 Infranet 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. For information on header files and a list of opcodes and their corresponding header files, see Header files.

You use the PCM_OP() macro to pass PCM opcodes and flists to Infranet. 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 don't have to follow any special precompilation or other steps to compile and link applications. Both static and dynamic versions of Infranet libraries are provided.

UNIX client libraries are multi-thread safe. For special instructions on writing Infranet applications in a multi-threaded Windows environment, see Managing memory in a multithreaded Windows environment

To compile and link your application:


Compile using the include files in the Infranet_SDK_home/include directory.

Link to the libraries in Infranet_SDK_home/lib.
See the sample applications and their make files for more information.

The following compilers are supported:


Solaris: Standard SUNPro C compiler, default mode (-Xa).
Infranet is compiled with -xcg92
Note gcc is not supported. Use the -munaligned-doubles option to ensure proper linking.



AIX: cc or xlC for C; xlC for C++

HP-UX: Standard HP C compiler

Windows: Microsoft Visual C or C++ compiler
Guidelines for developing applications in C on Windows
Follow these guidelines to develop custom applications in C on Windows:


Use Microsoft Developer Studio 5.0 or 6.0.

Always build your applications with the multi-threaded DLL or debug multi-threaded DLL (even when producing an .exe file).

Include portal.dll at link time.

Do not mix debug and release versions of library directives. Debug libraries are appended with the letter d. For example the debug version of portal.dll is for example, portald.dll.

Add Infranet_SDK_home/include to the list of include file directories to search.

In the preprocessor directives, be sure to include the following symbols:
WIN32,PIN_USE_ANSI_HDRS

Be extremely careful when running multiple versions of Infranet clients on the same computer. One version of portal.dll does not necessarily work for all versions of Infranet. If an application picks up the wrong DLL (or the wrong DLL is already loaded by another application), you might see abnormal program terminations. For information on sharing memory objects across threads, see Managing memory in a multithreaded Windows environment.
Guidelines for developing applications in C on UNIX platforms
Follow these guidelines to develop custom applications in C on Solaris, AIX, and HP-UX:


Include libportal.so or libportal.sl at link time.

Add Infranet_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



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

Sample applications
Infranet SDK includes sample applications and code in C, C++, Java, PCM COM, and Perl. For a complete list of the sample applications, see Sample Programs.

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

Caution! Don't run the sample programs on a production system. Some programs fill the database with test storable objects. Remove the test storable objects before building your production system.


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

For more information, see the Transaction Handling section on each opcode reference page and Context management opcodes.

Adding Branded Service Management to your application



Branded Service Management allows a single hosting Infranet site to support multiple virtual Infranet sites. Each virtual ISP is known as a brand and requires a secured view of its own data. At the same time, the hosting site maintains administrative oversight of the entire system, which may include many independent Infranet sites.

The brand as an independent virtual workspace
Two kinds of accounts exist in a branded service management setting: standard accounts and brand accounts. The brand account is a special entity that serves as a complete miniature Infranet system. Each brand accesses the database according to its own rules. To effectively implement brands, "data scoping" is required.

Data scoping
Data scoping is the ability to restrict database access so that only authorized users can access data and services. The concept of an account is essential to effective data scoping. Most objects are account-centric. For example, services and profiles are designed to be associated with an account. Events and pricing objects also "belong" to an account. Therefore, to implement data scoping in a Branded Service Management environment, all objects must be associated with an account.

Pointing a base level object to a brand account
To enforce scoping restrictions, the system associates all objects with an account. This association is done via the PIN_FLD_ACCOUNT_OBJ reference in the every base level object.

! Account object to which data belongsfield PIN_FLD_ACCOUNT_OBJ ( type = PIN_FLDT_POID, perms = MW,

Defining a brand account
There are two account types: standard accounts and brands. The following tag specifies the account type.

! Brand object or normal objectfield PIN_FLD_ACCOUNT_TYPE ( type = PIN_FLDT_ENUM

This flag is set when the account is created, and cannot be modified later. The flag can have one of two values:


For brand accounts: PIN_ACCOUNT_TYPE_BRAND

For standard accounts: PIN_ACCOUNT_TYPE_STANDARD
Providing access to brands
In a Branded Service Management environment, it's often necessary for an object to have distinct read and write access rules. For example, all members of a brand account may have read access to a pricing object while write access may be much more restricted. To meet this requirement two new fields have been added to each account object that define read and write access rules for the object. These fields are controlled by the system and filled in by the Data Manager with values specified in the data dictionary. These are:


PIN_FLD_READ ACCESS: describes who has permission to read data

PIN_FLD_WRITE_ACCESS: describes who has permission to modify data
Branding access permissions
The following table defines the permissions that can be assigned for read and write access:

Permission Description
Global
Any user can read or write the object. Many /config objects are globally readable.

Brand
Any user with brand access can read or write the object. For example, pricing objects, such as products and deals, are brand-readable.

Self
Only the brand owner can read or write the data. Pricing objects are self-writeable and brand-specific to prevent unauthorized changes to the price list.

Ancestral Lineage
The brand owner or any superior billing group leader can read or write the data. For example, /device objects have Ancestral Lineage write permissions.

Brand Lineage
The owner, or any superior billing group leader within the brand, can read or write the data. Used with many objects, including services, profiles, and events to ensure brand segregation and data privacy.



Providing access to pricing information
All pricing related objects available for system use are associated at the brand level. Therefore, Pricing FM opcodes only look for pricing objects associated with the brand.

Read access to pricing data
Each brand in an Infranet system maintains its own pricing data. Because everyone who accesses the brand should be able to read pricing information, objects related to pricing have read access set to the Brand Group Scope level. Thus objects of the following types are all of the type PIN_FLD_READ_ACCESS = B (brand): /product, /rate, /fold, /plan_list.

Write access to pricing data
Since the ability to modify pricing information is generally much more restricted, write access to pricing objects are set locally. This ensures that only the owner of the pricing object can modify pricing data.

Billing groups
Billing groups act as containers for grouping accounts. A billing group leader has access to all account data owned by the billing group, as well as information owned by any of the billing group members. Thus a group leader can look down an entire tree of billing groups and its associated accounts within the brand. In this way, billing groups are used as the primary mechanism for categorizing scoping classes.

Providing billing group access with an Access Control List (ACL)
A new group object, /group/acl, has been created to define access for the billing group. The group acl includes a list of group members along with a pointer to the brand account or accounts to which group members have access.

Managing custom applications
A host ISP may manage many brand accounts. Each brand may in turn have access to a variety of multi-brand applications. Infranet's client interface simplifies an administrator's task. Once a user enters an authorized login and password, Infranet displays a list of available brands. A user can then set the current connection scope by selecting a brand to customize.

Creating brands programmatically
Use the PCM_OP_CUST_COMMIT_CUSTOMER opcode to create a new brand account. This opcode creates and initializes /account and /service storable objects. Once the account has been created, the account type flag must be set:

! Brand object or normal objectfield PIN_FLD_ACCOUNT_TYPE ( type = PIN_FLDT_ENUM

This flag is set when the account is created, and cannot be modified later. The flag can have one of two values:


For brand accounts: PIN_ACCOUNT_TYPE_BRAND

For standard accounts: PIN_ACCOUNT_TYPE_STANDARD
Set the flag to PIN_ACCOUNT_TYPE_BRAND to specify this account as a brand.

Writing brand-aware applications
Applications can be customized to meet the requirements of a brand. To do this, the administrator must first retrieve a list of available brands and then set the connection scope to the specific brand to be customized.

Displaying a list of user authorized brands
Use the PCM_OP_PERM_GET_CREDENTIALS opcode to display a list of the brands which have access to an application. Usually this opcode is called at start-up time. After the user enters an authorized login and password, the system displays a list of brands which have access to the application along with the currently active brand and billing group.

Setting the current connection scope
Because each brand represents an independent virtual workspace with its own data and access rules, a user must select a single brand (or billing subgroup) with which to work. Use the PCM_OP_PERM_SET_CREDENTIALS opcode to set the current connection scope.

About adding multidatabase support to your applications



Infranet supports the ability to add multiple databases for the purpose of scaling your Infranet system. This document explains the programming considerations of creating an application to work with an Infranet system using multiple databases.

For instructions on installing a multidatabase system, see:


Installing a Multidatabase Infranet System on Windows

Installing a Multidatabase Infranet System on UNIX
For instructions on maintaining a multidatabase system, see Managing a Multidatabase Infranet System.

This section explains the topics you need to know before you design a new application, or enhance an existing program to take advantage of the Infranet multidatabase feature.

About working with multiple databases
Generally, making applications work with multiple databases isn't all that different from making them work with a single database.

Accounts are distributed across databases, but applications log in to the correct database for an account based on the login name and service type. When an application logs in to Infranet, it gets the database context for the account it logged in as. An event for the login session for that application is created in the database that hosts the account.

After the application has logged in, it has access to the entire Infranet database for reads and writes on all classes that are modifiable. In most cases, after an account context is established, all subsequent operations for the account are performed in the single database where the context was opened.

Creating accounts
The PCM_OP_CUST_COMMIT_CUSTOMER opcode has been enhanced to work with multiple databases. Use that opcode to create accounts just as you would for a single database system. This opcode uses the /config/distribution object created by using the load_config_dist utility to determine which database your account is created in.

You can specify which database new accounts should be created in by editing the multidatabase configuration file. For more information, see Setting database priorities.

Important Billing groups, including all accounts with the same brand, must reside in the same database.


Maintaining transactional integrity
Important Remember, once you find an account to modify data in, confine all operations possible to that database.


Although an application can connect to multiple databases and manipulate data in any database, a transaction can only manipulate data in a single database. To perform a transaction on more than one database, you must close the existing transaction, open a context to the other database, and open another transaction. An application that needs to perform the same operation on all accounts (such as billing or invoicing), should be run as a separate instance on each database.

You must use the database number returned by PCM_CONNECT or PCM_CONTEXT_OPEN for all transactions within the context you open. These opcodes pass in an account's username and return the database number for that account. To prevent losing transactional integrity, avoid opening contexts to multiple databases whenever possible.

The exception to this rule is the rare occasion when you need to access information in any of the pricing storable classes. Embedded in these classes is the account information (including database number) of the person who changed that information. All account references are exact references. Dealing with this information can require you to switch contexts to another database with a new call to PCM_CONNECT or PCM_CONTEXT_OPEN.

Working with replicated objects
In multidatabase systems, some objects are replicated in all databases to improve performance. Replicating objects allows applications to access information in the database where the context is opened. Replicated objects are read-only except in the primary database.

Many frequently accessed objects, such as /config objects, are replicated. You can obtain a list of the replicated database tables by running a SQL query against the primary database.

Note The SQL query returns a list of table names. Table names generally correspond closely to storable class and class and field names. You can find detailed SQL mapping information for storable classes by following the links in Storable Class Definitions.


To generate a list of replicated tables for Oracle and SQL Server:


Log into the primary database as pin.
% sqlplus pin/password@DatabaseAlias

Enter the following SQL command to generate a list of replicated tables:
SQL> select distinct table_name from md_static_objects_t;

Searching for accounts across databases
Searching for a single account
There are two opcodes you can use to locate a single account:


Use the PCM_OP_ACT_FIND opcode to locate an account based on the login and service type. This opcode finds and returns the account POID (including the correct database number) of a single account.

Use the PCM_OP_GLOBAL_SEARCH opcode to locate an account based on other account attributes. This opcode returns any fields that you specify on the input flist.
Searching for multiple accounts (global search)
Use the PCM_OP_GLOBAL_SEARCH opcodes to find and return the POIDs of multiple accounts across multiple databases at the same time. The global search opcodes can also be used to search for a set of objects that live in multiple databases. For example, all events from a particular day. See Searching for Objects in Infranet Databases for a complete discussion of searching for accounts across multiple databases.

Important Remember to use non-global searches for better performance whenever possible. After you get the results of a global search, you can improve your application's overall performance by dividing the database read and write operations among databases.


Finding out how many databases you have with testnap
Use the testnap testing utility to find out the number of databases that are connected to your Infranet system. The example below shows testnap being started, and then displaying the contents of an flist named 1. This flist is designed to match all root accounts. In the next step, this flist is passed into PCM_OP_GLOBAL_SEARCH (Opcode number 25) which searches all databases. In this final step, testnap searches all databases for their root accounts. There is only one root account (in the /service class) in each database, so the result of this search is a listing of all the databases currently connected to your Infranet system. In this case there are two: 0.0.0.1 and 0.0.0.2.

testnapinput flist:nap(10238)> d 10 PIN_FLD_POID POID [0] 0.0.0.1 /search -1 00 PIN_FLD_FLAGS INT [0] 00 PIN_FLD_TEMPLATE STR [0] "select X from /service where F1 like V1 and F2 = V2 "0 PIN_FLD_ARGS ARRAY [1]1 PIN_FLD_LOGIN STR [0] "root.0.0.0%"0 PIN_FLD_ARGS ARRAY [2]1 PIN_FLD_POID POID [0] 0.0.0.0 /service/pcm_client -1 00 PIN_FLD_RESULTS ARRAY [0]1 PIN_FLD_POID POID [0] NULL1 PIN_FLD_LOGIN STR [0] ""result:nap(10238)> XOP PCM_OP_GLOBAL_SEARCH 0 1XOP: opcode 25, flags 0# number of field entries allocated 3, used 30 PIN_FLD_POID POID [0] 0.0.0.1 /search -1 00 PIN_FLD_RESULTS ARRAY [0] allocated 2, used 21 PIN_FLD_POID POID [0] 0.0.0.2 /service/pcm_client 1 11 PIN_FLD_LOGIN STR [0] "root.0.0.0.2"0 PIN_FLD_RESULTS ARRAY [1] allocated 2, used 21 PIN_FLD_POID POID [0] 0.0.0.1 /service/pcm_client 1 11 PIN_FLD_LOGIN STR [0] "root.0.0.0.1"

Bill numbering
Applications must now avoid hard-coding billing numbers. Bill numbers are now coded to the database they were created in and Infranet relies on the new numbering scheme. The /data/sequence class still keeps track of billing numbers to ensure that they are all unique. This class has been enhanced to make sure that database numbers are unique across databases.



--------------------------------------------------------------------------------