Understanding the PCM API

About the PCM API

All access to the data in the BRM database is through the PCM API. Client applications and custom Facilities Modules (FMs) use this library to manipulate objects in the database.

The API consists of three classes of functions:

Context management. You use context management opcodes to control communication channels to the database.
Basic object manipulation. You use base opcodes to create, search for, delete, and modify objects in the database.
FM object manipulation. You use FM opcodes to implement business policies and processes.

You make BRM API calls by using a macro interface instead of directly through functions. When an API macro is called, the macro records the file name and line number of the source code where the API was called. If an error occurs, the macro logs a message including the file name and source code line number, making it easy to locate and correct the error.

For details on the return status of PCM functions and the error messages returned, see "Finding Errors in Your Code".

The API definitions are independent of the underlying storage model. The C data structures are opaque, and the opcodes are designed to appear much like object methods.

Context Management Opcodes

The context management opcodes open and close a communication channel to the BRM database by opening and closing a context to the Connection Manager (CM). The context structure is opaque to the application. It contains state data used by the PCM library to manage the communication channel.

The context management opcodes include functions for synchronous and asynchronous transactions. All transactions must follow these rules:

Each application can connect to only one CM at a time.
Only one connection can be open to a DM at a time.
All object manipulation functions performed within a transaction must apply to the same BRM database schema.

When a context is opened, you can call additional functions to open, close, and commit or cancel transactions within the open context.

When you open a PCM context, a connection is established between your application and the BRM server. This connection adds significant overhead to the system because of the security and auditing checks performed by BRM. Therefore, to maximize performance, make sure your application keeps the context open until all the operations are performed. If your application opens and closes contexts frequently, performance will be affected.

If you are writing applications, such as Web-based Active Server Pages or CGI scripts, that cannot maintain an open context for a long time, use CM Proxy. CM Proxy allows your application to access the database with a pre-authorized connection and avoid the system overhead of a login for each connection.

For more information on CM Proxy, see "Using CM Proxy to Allow Unauthenticated Log On" in BRM System Administrator's Guide.

For more information on context management opcodes, see "Context Management Opcodes" in BRM Opcode Guide.

Base Opcodes

You use base opcodes to perform operations such as creating and manipulating objects, searching, and transaction handling. Base opcodes are implemented in the Data Manager, unlike the other opcodes, which are implemented in the Connection Manager.

Base opcodes require an open communication context and an input flist as parameters. The input flist specifies the input field arguments, and is not modified during execution.

You call the object manipulation opcodes with PCM_OP. The opcode you want to call is an input parameter.

Base opcodes pass back a return flist as a parameter. The return flist contains the result field arguments. The memory for the return flist is dynamically allocated.

You can run basic object manipulation macros in any combination within a transaction, depending on the resources available.

Search and Global Search Opcodes

Some base opcodes are used for searching in BRM. "Searching" in this context means looking in your BRM database for objects that meet a criteria that you specify. That is, you want the POIDs of all the objects that share certain characteristics. The PCM_OP_SEARCH_* and PCM_OP_GLOBAL_SEARCH_* opcodes are designed for this purpose. They search single or multiple database schemas for accounts that match the criteria you specify and return the POIDs of those accounts.

After you know the POIDs of accounts, you can call other base opcodes designed to read or change data, such as PCM_OP_READ_OBJ, PCM_OP_WRITE_OBJ, or PCM_OP_DELETE_OBJ.

See "Searching for Objects in the BRM Database" for a discussion of searching and a list of the SEARCH opcodes. This document explains the BRM searching strategy, including the types of searching that BRM does by default and what you must know to write custom applications to use on the BRM database.

When you write a custom DM, depending on your needs, you implement opcodes from the following set:

Base opcodes for LDAP DM. See "LDAP Base Opcodes" in BRM Opcode Guide.
Base opcodes for Email DM. See "Email Data Manager Opcodes" in BRM Opcode Guide.

FM Opcodes

FMs (Facilities Modules) are shared libraries that implement higher-level opcodes. Each FM implements a set of opcodes to perform operations specific to that module. FMs create online accounts, manage customer-related information, charge customers for usage, and allow third-party systems to be integrated with BRM. In the billing FM, for example, opcodes perform advanced billing-related operations on user accounts.

You call the FM opcodes using PCM_OP, with the FM opcode you are calling as the input parameter.

FM opcodes are divided into the following types:

Standard FM opcodes perform specific BRM operations. You cannot change the standard opcodes. However, to add new functionality, you can write new opcodes.

For more information, see "Writing a Custom Facilities Module".
Policy FM opcodes contain the BRM business logic. You can modify the default behavior of policy opcodes to suit your business needs. BRM includes the source code for all the policy opcodes.

For example, you can bill customers on their anniversary date or on the first day of each month by modifying the default implementation of the PCM_OP_CUST_POL_PREP_ACTINFO policy opcode.

For more information on customizing policy opcodes, see "About System and Policy Opcodes".

BRM includes a set of policy opcodes, including source code, as hooks for you to add your code. These opcodes do not have a default implementation.

Standard FMs that use business logic to process requests have policy FMs associated with them. A few FMs, such as the SDK FM and the Group FM, which are internal to BRM and do not need business logic for processing data, do not have associated policy FMs.

Each of the BRM optional managers has its own FM. See the appropriate optional manager documentation for more information.

About the PREP and VALID Opcodes

Many opcodes, for example, PCM_OP_CUST_SET_LOGIN and PCM_OP_CUST_PREP_CUSTOMER, call policy PREP and VALID opcodes, such as PCM_OP_CUST_POL_PREP_PASSWD and PCM_OP_CUST_POL_VALID_PASSWD. You can use PREP and VALID opcodes to customize how data is processed.

Use the PREP opcodes to process data before it is validated. Typical processing includes adding missing fields whose values are derived or generated by the PREP operation, and forcing fields to predefined values independent of what the customer specified. PREP opcodes are given a set of customer-specified fields on the input flist, and return the processed version of the same data on the output flist.

If a PREP opcode cannot derive all the necessary fields because the customer-specified values used in the derivation are incorrect, no error is returned. Instead, the derived fields are put on the output flist with a default value, and the corresponding VALID call detects the incorrect data and returns the validation error to the calling application. This approach allows the calling application to see the details of the validation error rather than receiving a less precise ebuf error passed up from the PREP opcode.

If a PREP opcode cannot generate a necessary field or some other internal problem is encountered, an ebuf error is returned.
Use the VALID opcodes to validate field values. Typical checks include formatting tests for data integrity, tests for illegal values and tests for required information that is missing. VALID opcodes are given a set of related fields and values on the input flist, and return a list of fields that failed the validation tests on the output flist. The VALID opcodes cannot alter the value of a field that is not suitable, that is the purpose of the PREP opcodes.

If one or more fields fail the validation tests, they are returned using the PIN_FLD_FIELDS array on the output flist. This array is structured to allow fields nested within arrays or substructs to be accurately represented. All fields that failed validation are returned by the operation, so the caller can correct all errors at once and retry the operation.

Validating Fields by Using Field Validation Editor

To validate the fields that you specify in the Field Validation Editor, use PCM_OP_CUST_VALID_FLD.

Header Files

Each set of related opcodes has a corresponding header file. Your custom code and applications must include the header files that correspond to the opcodes you use.

Context management opcodes use the pcm.h header file. Always include this file in your applications.

Header files for base opcodes and Facilities Module (FM) opcodes are located in the include/ops directory. To include one of these header files, use this syntax:

#include "ops/file.h"

Where file is the name of the header file.

For example, if your application calls PCM_OP_CUST_COMMMIT_CUSTOMER, you must include the ops/cust.h header file.

About Opcode Usage

Recommended: opcodes are designed specifically for you to call from your custom applications. They are not expected to change from release to release.

Limited: opcodes should only be called in special cases. They may change from release to release.

Last Resort: opcodes should only be called if absolutely necessary. Calling these opcodes means that you are either on the wrong track or rewriting major portions of code. BRM will change these opcodes as necessary.

About Transaction Usage

A transaction is a connection that requires that the data being read or written must not change during the connection. A transaction adheres to the “ACID" properties, which means the transaction is:

Atomic: Either the entire transaction completes successfully, or none of it does.
Consistent: The transaction takes the database from one consistent state to another.
Isolated: Only the process that opened the transaction can see the intermediate results of the transaction.
Durable: After the transaction is committed to the database, the changes are permanent and cannot be changed except by another transaction.

Each opcode uses one of the following types of transaction handling:

Transaction Handling: Required

The transaction for this opcode can be wrapped in a transaction opened by another opcode.

If a read-write transaction is already open when this opcode is run, all data modifications take place within the open transaction. The modifications are committed or cancelled along with all other changes when the transaction is committed or cancelled.

If no transaction is open when the opcode is called, a read-write transaction is opened. All actions are performed within this transaction, ensuring that the entire operation is performed atomically. If an error occurs during the execution of the opcode, all changes are cancelled when the transaction is cancelled. If no error occurs, the transaction is committed at the end of the operation.

This opcode requires a read-write transaction. It is therefore an error to have a read-only transaction open when this opcode is called.

Transaction Handling: Requires New

This opcode manages transactions internally to ensure absolute integrity of the database. A transaction for this opcode cannot be wrapped in another transaction.

If no transaction is open when the opcode is called, a read-write transaction is automatically opened and all actions are performed within this transaction.

If a transaction is already open when the opcode is called, an error occurs.

Transaction Handling: Supports

This opcode does not modify object data. If it is called while a transaction is not already open, the operation is run without transactional control.

If a read-write or read-only transaction is already open when this opcode is called, the opcode is run as part of the transaction and reads the in-process state of the data.

If the opcode is called when a separate, unrelated transaction is taking place, it reads the last saved state of the database.

Calling PCM Opcodes

You call the base and FM opcodes by using PCM_OP(). You pass the opcode you want to call as one of the input parameters. PCM_OP() runs the opcode in its input parameters list in an open communication channel or a context.

You use the following parameters and flags with PCM_OP():

pcm_ctxp

Pointer to an open PCM context.

opcode

Name of the opcode you want to call.

flags

(int32)NULL

No flags specified. Use only when there are no flags defined for this operation.
PCM_OPFLG_READ_RESULT

Returns all the fields in the object from the output flist, not just the POID. Valid only for opcodes that create objects.
PCM_OPFLG_CALC_ONLY

Calculate only. Valid only for opcodes that create objects. No fields in the database are changed and the object is not actually created. Instead, fields that would have been used to create the object are returned to the caller on the output flist.

in_flistp

An input flist specification for the opcode defining the required and optional input fields for the opcode to function properly. Each opcode has an input flist specification that you must use to create the input. See the input flist specification in an individual opcode description for details.

ret_flistpp

An output flist specification defining what you expect the opcode to return. Each opcode has an output flist specification that you must use to create the input. You must explicitly destroy the return flist to free memory. See the output flist specification in an individual opcode description for details.

ebufp

Pointer to an error buffer. Used to pass status information back to the caller.

The following example shows how to call the policy opcode PCM_OP_CUST_POL_GET_PLANS to get packages:

/*Declarations*/
pin_errbuf_t *ebufp
input_flistp = PIN_FLIST_CREATE(ebufp); 
return_flistp = PIN_FLIST_CREATE(ebufp); 
  
PCM_OP(ctxp, PCM_OP_CUST_POL_GET_PLANS, 0, input_flistp, &return_flistp, ebufp);

Manipulating Objects in Custom Applications

There are three basic steps to manipulating objects in a custom application or module:

Open a context by calling PCM_CONTEXT_OPEN or PCM_CONNECT in an application.
Call opcodes with PCM_OP.
Close the context by using PCM_CONTEXT_CLOSE.

Supporting an Older Version of BRM

The PIN_FLD_VERSION flag on the PCM_OP_CUST_COMMIT_CUSTOMER input flist specifies whether the flist complies with the current version of BRM. If it doesn't, new BRM objects are created. This supports backward compatibility. The current version is this version of BRM.

Possible flag values are:

PIN_PORTAL_VERSION_CURRENT (a value of 0) specifies this version of BRM.
PIN_PORTAL_VERSION_LEGACY (a value of 1) specifies a legacy version of BRM. This is the default. If PIN_PORTAL_VERSION_LEGACY is specified, the input flist is converted to the current version and all necessary objects, including the /billinfo, /balance_group, and /payinfo objects are created for the account.