Creating Applications that Run on Multischema Systems

About Working with Multiple Schemas

Generally, making applications work with multiple database schemas is not all that different from making them work with a single schema.

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

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

Creating Accounts in a Multischema System

Use the PCM_OP_CUST_COMMIT_CUSTOMER opcode to create accounts just as you would for a single-schema system. The opcode uses the /config/distribution object created by using the load_config_dist utility to determine which schema your account is created in.

You can specify which schema new accounts should be created in by editing the config_dist.conf configuration file. For more information, see "Setting Database Priorities" in BRM System Administrator's Guide.

Note:

Billing groups must reside in the same schema.

Maintaining Transactional Integrity

Note:

Remember, after you find an account to modify data in, confine all operations possible to that schema.

Although an application can connect to multiple database schemas and manipulate data in any schema, a transaction can only manipulate data in a single schema. To perform a transaction on more than one schema, you must close the existing transaction, open a context to the other schema, 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 in each schema.

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 user name and return the database number for that account. To prevent losing transactional integrity, avoid opening contexts to multiple schemas 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 storable classes is the account information (including database number) of the person who changed that information. All account references are exact references. Managing this information can require you to switch contexts to another schema with a new call to PCM_CONNECT or PCM_CONTEXT_OPEN.

Searching for Accounts across Database Schemas

This section describes how to search for accounts across database schemas.

You can use the following opcodes to find a single account:

Use the PCM_OP_ACT_FIND opcode to find 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 find an account based on other account attributes. This opcode returns any fields that you specify on the input flist.

To find POIDS of multiple accounts across multiple database schemas, use the PCM_OP_GLOBAL_SEARCH opcodes . The global search opcodes can also be used to search for a set of objects that reside in multiple database schemas (for example, all events from a particular day). See "Searching for Objects in the BRM Database" for a complete discussion of searching for accounts across multiple database schemas.

Note:

Remember to use nonglobal 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 database schemas.

Finding How Many Database Schemas You Have

Use the testnap utility to find the number of database schemas connected to your BRM system. The following example shows testnap being started and then displays the contents of an flist named 1. This flist is designed to match all root accounts. In the next step, this flist is passed to PCM_OP_GLOBAL_SEARCH (opcode number 25), which searches all database schemas. In the final step, testnap searches all database schemas for their root accounts. Each database schema has only one root account (in the /service storable class), so the result of this search is a listing of all the database schemas currently connected to your BRM system. In this example, there are two: 0.0.0.1 and 0.0.0.2.

testnap
input flist:
  
d 1
0 PIN_FLD_POID           POID [0] 0.0.0.1 /search -1 0
0 PIN_FLD_FLAGS           INT [0] 0
0 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 0
0 PIN_FLD_RESULTS       ARRAY [0]
1     PIN_FLD_POID           POID [0] NULL
1 PIN_FLD_LOGIN           STR [0] ""
  
result:
  
XOP PCM_OP_GLOBAL_SEARCH 0 1
XOP: opcode 25, flags 0
# number of field entries allocated 3, used 3
0 PIN_FLD_POID           POID [0] 0.0.0.1 /search -1 0
0 PIN_FLD_RESULTS       ARRAY [0] allocated 2, used 2
1     PIN_FLD_POID           POID [0] 0.0.0.2 /service/pcm_client 1 1
1     PIN_FLD_LOGIN           STR [0] "root.0.0.0.2"
0 PIN_FLD_RESULTS       ARRAY [1] allocated 2, used 2
1     PIN_FLD_POID           POID [0] 0.0.0.1 /service/pcm_client 1 1
1     PIN_FLD_LOGIN            STR [0] "root.0.0.0.1"

Bill Numbering

Applications must avoid hard-coding bill numbers. Bill numbers are coded to the database schema they were created in, and BRM relies on the numbering scheme. The /data/sequence storable class tracks bill numbers to ensure that they are unique. This storable class makes sure that bill numbers are unique across database schemas.