Context Management Opcodes

2 Context Management Opcodes

Learn about the Oracle Communications Billing and Revenue Management (BRM) context management opcodes.

Topics in this document:

Context Management Opcodes

The context management opcodes manage the communication between a client application and the BRM database.

Include the pcm.h header file in all applications that call these opcodes. See the discussion on header files in BRM Developer'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.

Table 2-1 Context Management Opcodes

Opcode	Description
PCM_CONNECT	Opens a PCM context in a BRM application.
PCM_CONTEXT_CLOSE	Closes a PCM context.
PCM_CONTEXT_OPEN	Opens a PCM context.
PCM_OP	Runs a PCM opcode by passing a copy of the input flist.
PCM_OPREF	Runs a PCM opcode by passing a reference to the input flist.

PCM_CONNECT

PCM_CONNECT simplifies opening a PCM context in a BRM application program. Instead of having to manually create an input flist for PCM_CONTEXT_OPEN, you can put all information necessary for opening a context in the application's pin.conf file. PCM_CONNECT reads those entries from the application's pin.conf file, creates an input flist with that information, and then calls PCM_CONTEXT_OPEN to open the context.

PCM_CONNECT first looks in the application's pin.conf file for the userid and login_type entries. If login_type is 0 (no login and password required), PCM_CONNECT calls PCM_CONTEXT_OPEN with a NULL input flist. The POID from the userid entry is used to route the context open request to the desired database schema. See "PCM_CONTEXT_OPEN" for details on userid values.

If login_type is 1, PCM_CONNECT also reads the login_name and login_pw entries. It then calls PCM_CONTEXT_OPEN with an input flist containing values for PIN_FLD_POID, PIN_FLD_TYPE, PIN_FLD_LOGIN, and PIN_FLD_PASSWD_CLEAR, which it got from the userid, login_type, login_name, and login_pw pin.conf entries, respectively.

Note:

In your application, when you open a context and connect to the BRM server, run all the opcodes before closing the context. Connections add a significant overhead to the system, which affects performance. Therefore, to improve performance, run all the opcodes in an open context instead of opening and closing contexts frequently. Use CM proxy for applications that cannot maintain an open context for a long time. See the discussion on using cm_proxy to allow unauthenticated logins in BRM System Administrator's Guide.

See "PCM_CONTEXT_OPEN" for a full description of opening contexts.

Syntax

#include "pcm.h"
void 
PCM_CONNECT(
               pcm_context_t     **ctxp,
               int64              *db_no,
               pin_errbuf_t       *ebufp);

Parameters

pcm_ctxp: A pointer to an open PCM context, which is returned by a successful call.
db_no: If 0 is passed in by using (int64) 0, 0 is returned. Otherwise, the number of the database schema to which this context has been opened is returned. The database number comes from the userid entry in the calling application's pin.conf file.
ebufp: A pointer to an error buffer. Used to pass status information back to the caller.

Return Values

See "PCM_CONTEXT_OPEN".

Error-Handling

See "PCM_CONTEXT_OPEN".

Examples

The sample_app.c file and the accompanying makefile illustrate how to use this opcode when setting up a generic BRM account and service. The files are located in BRM_SDK_home/source/samples/app/c.

Here is an additional example of how to use PCM_CONNECT:

PIN_ERR_CLEAR_ERR(&ebuf);

PCM_CONNECT(&ctxp, &db_no, &ebuf);

if (PIN_ERR_IS_ERR(&ebuf)) {

...

}

PCM_CONTEXT_CLOSE

PCM_CONTEXT_CLOSE closes a context to the BRM system. The context should be closed after it is no longer needed by an application. This opcode breaks the connection to the BRM system and frees all memory associated with the context.

If an application exits, all open contexts are automatically closed by the BRM system.

See the discussion on the PCM API in BRM Developer's Guide for more information on contexts.

Syntax

#include "pcm.h"
void 
PCM_CONTEXT_CLOSE(
               pcm_context_t     *pcm_ctxp,
               int32              how,
               pin_errbuf_t      *ebufp);

Parameters

pcm_ctxpp: A pointer to an open PCM context.
how: The how parameter tells how to close the connection. The normal choice is to completely close the connection by passing in a (int32) 0. However, if you fork a process, the process that does not continue making PCM calls (usually the child process) should at least close all open FDs. This can be done by passing PCM_CONTEXT_CLOSE_FD_ONLY as the value of how. This has the benefit of allowing the child process (in most cases) to close the FDs without closing the PCM connection in the parent that spawned it. If the child process wants to continue to make PCM calls, it should open another PCM connection.
ebufp: A pointer to an error buffer. Used to pass status information back to the caller.

Return Values

PCM_CONTEXT_CLOSE returns nothing.

Error status is passed back to the caller using the error buffer.

Error-Handling

PCM_CONTEXT_CLOSE uses individual-style ebuf error handling. This means the application must explicitly test for an error condition recorded in the error buffer before making other calls to the BRM API. See the discussion on understanding API error handling and logging for details on error handling algorithms in BRM Developer's Guide.

Examples

The sample_app.c file and the accompanying makefile illustrate how to use this opcode when setting up a generic BRM account and service. The files are located in BRM_SDK_home/source/samples/app/c.

PCM_CONTEXT_OPEN

PCM_CONTEXT_OPEN opens a context to the BRM database. All data in the BRM database is accessed using an open context. A dynamically allocated context structure is passed back and is used in subsequent PCM calls to identify the open context. The context structure is opaque to the application and is used only to identify the context for other calls.

Note:

In your application, when you open a context and connect to the BRM server, run all the opcodes before closing the context. Connections add a significant overhead to the system, which affects performance. To improve performance, run all the opcodes in an open context instead of opening and closing contexts frequently. If a context is opened from within a CM, it must remain open during the entire client life cycle. Use CM proxy for applications that cannot maintain an open context for a long time. See the discussion on using cm_proxy to allow unauthenticated logins in BRM System Administrator's Guide.
If you have client applications running on the same server as the CM or DM, you still must use a TCP/IP connection for invoking opcodes. You also must establish a PCM connection to obtain a context for invoking opcodes.

A context can only have one outstanding operation at a time. Even if the asynchronous routines are used to launch an operation, another one cannot be started until the outstanding one is either completed or canceled.

If parallel operations are required (in the same or a different database schema), the application can open multiple contexts to the BRM database. There is no limit to the number of contexts an application can open.

When a context is no longer needed, it should be closed using PCM_CONTEXT_CLOSE. The open context can survive any errors (except losing the socket), so it can still be used even after one operation has failed.

A single context is normally opened by a client to access a single database schema. The client application is responsible for including a POID in its PCM library calls. Each POID contains a database number. The CM uses this schema number to route the client's request (the operation) to the proper DM.

A single context can support access to many database schemas simultaneously, but the client is responsible for passing the correct database schema IDs. Furthermore, the CM handling requests for the client must be configured to access multiple database schemas. That is, it must have the schema numbers and IP addresses. This information is passed to the CM by using the dm_pointer entries in the CM's pin.conf file.

Only one transaction can be open at a time, and object manipulation functions performed while a transaction is open must apply to the same database schema. If a transaction is opened and you must access another schema, open another context and access it through the new context. See the discussion on the PCM API document in BRM Developer's Guide for more information on contexts.

For PCM_CONTEXT_OPEN inside an FM, always use (pin_flist_t*)NULL for in_flistp.

The BRM base database does not support transactions across database systems.

By default, CMs require a user login and password when requesting an open context using PCM_CONTEXT_OPEN. However, you can remove this authentication requirement by configuring the CM with a cm_login_module of cm_login_null.so. The cm_login_module entry in the CM's pin.conf file is explained in the comments in that file. When the CM is configured to require a password and login, the input flist (in_flistp) for PCM_CONTEXT_OPEN must be constructed as explained below.

Syntax

#include "pcm.h"
void 
PCM_CONTEXT_OPEN(
               pcm_context_t     **pcm_ctxpp,
               pin_flist_t        *in_flistp,
               pin_errbuf_t       *ebufp);

Parameters

pcm_ctxpp: A pointer to an open PCM context.
in_flistp: Two types of login are supported:

type = 0 base level security: verify the specified service by type and ID.
type = 1 login/password security: look up the specified service by login name and validate the password.

If in_flistp is NULL, type 0 login is attempted. Otherwise, the input flist can specify either type 0 or type 1 login.

For type 0 login, the following two fields are required:

PIN_FLD_POID

The portions of the POID that are used during login verification are database number, service, and ID. The specified service with the specified ID is looked up in the BRM database. If this service does not exist, the login is denied. The root account's /service/pcm_client service can be used for the service and its ID of 1 can be used for the ID.

Any valid service type and ID could be used instead of the root account's /service/pcm_client service.
PIN_FLD_TYPE

The login type is 0.

For type 1 login, the following four fields are required:

PIN_FLD_POID

The portions of the POID used during login verification are database number, service, and ID. In the case of type 1 login, the database number and service type are significant. The ID is required because the POID requires one, but any value can be used (usually 1). The BRM database is searched for a service object (matching the service type contained in PIN_FLD_POID) that has a login that matches the login value for the PIN_FLD_LOGIN field. If no service with the specified login exists, the login is denied. Otherwise, the password is checked.

The root account's /service/pcm_client service can be used for the service type, and its ID of 1 can be used for the ID. You are free to create other /service objects that can be used for login verification.
PIN_FLD_TYPE

The login type is 1.
PIN_FLD_LOGIN

A login name.

Note:

The login cannot contain the characters : and @. The / character is allowed.
PIN_FLD_PASSWD_CLEAR

The cleartext password for login.

Note:

The password cannot contain the characters : and @. The / character is allowed.

See PCM_CONTEXT_OPEN.input, the input flist specification, for more details on in_flistp.

ebufp: A pointer to an error buffer. Used to pass status information back to the caller.

Return Values

PCM_CONTEXT_OPEN returns nothing.

Error status is passed back to the caller using the error buffer.

The context structure used to identify the open context is passed back using pcm_ctxpp. If an error occurred, NULL is passed back.

Error-Handling

PCM_CONTEXT_OPEN uses individual-style ebuf error handling. This means the application must explicitly test for an error condition recorded in the error buffer before making other calls to the BRM API. See the discussion on understanding API error handling and logging for details on error handling algorithms in BRM Developer's Guide.

The following codes may be returned in ebufp->pin_err:

PIN_ERR_BAD_ARG

Indicates one of the following conditions:

The flags parameter was not set properly.
The PCM ctxpp or ebufp structures are NULL.
The configuration information does not point to a valid Connection Manager.
Unable to open a socket to the Connection Manager.
Too many sessions are open.

PIN_ERR_NONE

Opcode successful; operation is complete.

PIN_ERR_NO_MEM

A memory allocation failed.

PIN_ERR_BAD_LOGIN_RESULT

The login failed.

PCM_OP

PCM_OP is a wrapper function for all PCM opcodes. This opcode performs a PCM opcode operation on an open context. The operation is done synchronously, so the calling process waits until the operation is complete and has the return flist immediately available for inspection.

All PCM opcode operations can be performed using this opcode. The specific fields required and allowed on the input and return flists depend on the operation being performed.

If a PCM base opcode operation is run using PCM_OP when no transaction is open on the context, the operation is implicitly wrapped in a transaction so all effects of the operation occur atomically. If a PCM FM opcode operation is run when no transaction is open on the context, it may or may not implicitly wrap all changes in a transaction. This is dependent on the FM operation being performed.

Syntax

#include "pcm.h"
void
PCM_OP(
               pcm_context_t     *pcm_ctxp,
               int32              opcode,
               int32              flags,
               pin_flist_t       *in_flistp,
               pin_flist_t      **ret_flistpp,
               pin_errbuf_t      *ebufp);

Parameters

pcm_ctxp: A pointer to an open PCM context.
opcode: The opcode to call. See "Base Opcodes" for choices.
flags: The flags supported by the opcode being called. See the opcode descriptions for information on the flags they take. Most opcodes take no flags, which is input as (int32) 0.
in_flistp: A pointer to the input flist.
ret_flistpp: A pointer to a pointer for passing back the return flist. All opcodes produce a return flist with at least the PIN_FLD_POID field on it. Other fields on the return flist depend on the opcode being called. The return flist is passed back even if an error occurred during the operation. It is the responsibility of the caller to destroy the return flist when it is no longer needed.
ebufp: A pointer to an error buffer. Used to pass status information back to the caller.

Return Values

PCM_OP returns nothing.

Error status is passed back to the caller using the error buffer.

The return flist is passed back using ret_flistpp. A return flist is always passed back, even if an error occurs. It is the responsibility of the caller to destroy both the input and return flists.

The following codes may be returned:

PIN_ERR_NONE

Opcode successful; operation is complete.

other codes

Opcode failed; see the "Error-Handling" section.

Error-Handling

PCM_OP uses individual-style ebuf error handling. This means the application must explicitly test for an error condition recorded in the error buffer before making other calls to the BRM API. See the discussion on understanding API error handling and logging for details on error handling algorithms in BRM Developer's Guide.

The following error codes returned from PCM_OP indicate an error in the PCP transmission protocol:

PIN_ERR_BAD_XDR

PIN_ERR_STREAM_EOF

PIN_ERR_STREAM_IO

PIN_ERR_TRANS_LOST

PIN_ERR_CM_ADDRESS_LOOKUP_FAILED

If you see one of these errors, close the context on which the error occurred and open a new one. The output flist is undefined, but the input flist is still valid.

Examples

The sample_app.c file and the accompanying makefile illustrate how to use this opcode when setting up a generic BRM account and service. The files are located in BRM_SDK_home/source/samples/app/c.

PCM_OPREF

You use PCM_OPREF to call FM opcodes in the same way as PCM_OP. The opcode syntax and input parameters are the same as PCM_OP. The only difference between them is that PCM_OPREF passes a reference to the input flist whereas PCM_OP passes a copy of the input flist to the called opcode.

PCM_OPREF should be used to call opcodes that won't modify the input flist.

When you have large input flists (for example, invoice flists), using PCM_OPREF is a more efficient than PCM_OP because it passes the flist by reference and does not make a copy of the input flist, which saves memory.

Syntax

#include "pcm.h"
void
PCM_OPREF(
               pcm_context_t     *pcm_ctxp,
               int32              opcode,
               int32              flags,
               pin_flist_t        *in_flistp,
               pin_flist_t        **ret_flistpp,
                pin_errbuf_t         *ebufp);

Parameters

pcm_ctxp: A pointer to an open PCM context.
opcode: The opcode to be performed. See "Base Opcodes" for choices.
flags: The flags supported by the opcode being called. See the opcode descriptions for information on the flags they take. Most opcodes take no flags, which is input as (int32) 0.
in_flistp: A pointer to the input flist.
ret_flistpp: A pointer to a pointer for passing back the return flist. All opcodes produce a return flist with at least the PIN_FLD_POID field on it. Other fields on the return flist depend on the opcode being called. The return flist is passed back even if an error occurred during the operation. It is the responsibility of the caller to destroy the return flist when it is no longer needed.
ebufp: A pointer to an error buffer. Used to pass status information back to the caller.

Return Values

PCM_OPREF returns nothing.

The return flist is passed back using ret_flistpp. A return flist is always passed back, even if an error occurs. It is the responsibility of the caller to destroy both the input and return flists.

Error status is passed back to the caller using the error buffer.

The following codes may be returned:

PIN_ERR_NONE

Opcode successful; operation is complete.
other codes

Opcode failed; see the "Error-Handling" section.

Error-Handling

PCM_OPREF uses individual-style ebuf error handling. This means the application must explicitly test for an error condition recorded in the error buffer before making other calls to the BRM API. See the discussion on understanding API error handling and logging for details on error handling algorithms in BRM Developer's Guide.

The following error codes returned from PCM_OPREF indicate an error in the PCP transmission protocol:

PIN_ERR_BAD_XDR

PIN_ERR_STREAM_EOF

PIN_ERR_STREAM_IO

PIN_ERR_TRANS_LOST

PIN_ERR_CM_ADDRESS_LOOKUP_FAILED

If you see one of these errors, close the context on which the error occurred and open a new one. The output flist is undefined, but the input flist is still valid.