5 Understanding the BRM Data Types

This chapter describes the data types that Oracle Communications Billing and Revenue Management (BRM) supports. The data types described here are defined in the pcm.h file.

About the BRM Data Types

BRM supports a set of data types that you use to define fields in a storable class or in field lists (flists). For information on flists and storable classes, see "Understanding Flists and Storable Classes".

Table 5-1 lists the data types that BRM supports. Some of the BRM data types are simple data types, which map to data types in programming languages such as C and C++. The others hold more complex data and point to C structures as their value. The complex data types that are specific to BRM or used in a special way in BRM, such as the Portal object ID (POID), arrays, and substructs, are explained in detail in the following sections. See "Flist Field Data Types" for a list of the data type abbreviations used in flists.

Table 5-1 BRM Supported Data Types

Data Type	Description	C Value
PIN_FLDT_INT	Signed 32-bit integer. Contains four bytes of data represented by a number. BRM considers an integer value that begins with 0 as octal, and an integer value that begins with 0x as hexadecimal and converts the value into decimal.	int32
PIN_FLDT_ENUM	Enumerated value. Contains a list of well-known values.	enum
PIN_FLDT_DECIMAL	Decimal data type, number of decimal places determined by MAX.	pin_decimal_t
PIN_FLDT_STR(len)	ASCII character string terminated with a \0 (NULL). len = max length in bytes, not including \0. It uses UTF-8 encoding.	char *
PIN_FLDT_BINSTR(len)	A string of binary data. len = max length in bytes.	pin_binstr_t
PIN_FLDT_TSTAMP	UNIX timestamp with one second accuracy. Contains integer data. This number is interpreted as the number of seconds past January 1, 1970.	time_t
PIN_FLDT_POID	Portal object identifier. See "Portal Object ID (POID)".	poid_t *
PIN_FLDT_ARRAY	Array element. See "Arrays".	pin_flist_t *
PIN_FLDT_SUBSTRUCT	Embedded substructure. See "Substructure".	pin_flist_t *
PIN_FLDT_BUF	Buffer with an arbitrary size of any large data such as text, image, or any other kind of data.	pin_buf_t
PIN_FLDT_ERRBUF	Structure for error holding error information.	pin_errbuf_t

Simple Data Types

BRM supports the following simple data types that map to data types in the C programming language:

PIN_FLDT_INT
PIN_FLDT_ENUM
PIN_FLDT_DECIMAL
PIN_FLDT_STR(len)
PIN_FLDT_BINSTR(len)
PIN_FLDT_TSTAMP

See Table 5-1 for the C values.

Portal Object ID (POID)

The POID data type identifies a storable object in the BRM database. Each storable object has a unique POID in BRM. You use the POID to locate a storable object in the database.

Use the POID management macros in the PIN Library to manipulate the POIDs.

The POID contains the following information:

database_number   object_type   object_id   object_revision_level

Example:

0.0.0.1 /account 1234 0

You can specify a type-only POID when you want to perform an action on all objects of a particular type. For example, if you want to search for all /device/sim objects, the input flist for the search opcode would contain the following field:

1     PIN_FLD_POID           POID [0] 0.0.0.1 /device/sim -1 0

Table 5-2 describes each entry in the POID:

Table 5-2 POID Entries

Entry	Description
database number	An arbitrary 64-bit number assigned to a particular BRM database by the BRM system administrator. Each database has a unique database number that is stored in each object in that database. This number must be used by all programs, CMs, and DMs accessing that database. Decimal dotted notation is used for the database number: 0.0.0.x, where x is the database number, such as 1057. See the dm_pointer entry in the CM pin.conf file for an example.
object type	The class to which the object belongs, for example, /event and /service. Null poid has only /.
object id	A unique 64-bit number assigned to each object. Once assigned, the ID is never changed or re-used. The ID is a 64-bit number to accommodate the large number of objects that can exist within a single database. The ID is guaranteed to be unique within a given database, not across databases. The maximum value allowed for the ID in a nonpartitioned table is 2⁶⁴ and in a partitioned table is 2⁴⁴.
object revision level	Revision number. This value is incremented automatically each time the object is updated. You cannot change this value directly.

Decimal Data Type

The decimal data type, PIN_FLDT_DECIMAL is an opaque data type that you use to represent values precisely to a specified number of decimal places.

You cannot perform arithmetic operations on a void pointer and C has no operator overloading. Therefore, the API provides a set of functions to perform arithmetic operations on pin_decimal_t.

The BRM C API uses pin_decimal_t, and it is defined in BRM_Home/include/pin.h file, where BRM_Home is the directory in which you installed BRM components.

You manipulate the decimal data type, by using the decimal functions in the PIN libraries. You can perform the following arithmetic operations by using the decimal data type functions:

Convert string to decimal and decimal to string
Add, subtract, multiply, and divide two decimals
Compare two decimals
Scale or round a number
Negate a decimal
Output to a string
Output to a double

For detailed descriptions of the functions, see "Decimal Data Type Manipulation Functions" in BRM Developer's Reference.

Note:

PIN_FLDT_DECIMAL replaces the data type PIN_FLDT_NUM from earlier releases.

Arrays

Use the array data type PIN_FLDT_ARRAY to store a defined structure of information. An array contains a recurring set of data structures called elements. Each element in an array can contain multiple fields, including other nested arrays. Each element in an array must contain the same number and type of fields as all the other elements in the array.

For example, the /account class contains an array called PIN_FLD_NAMEINFO. Each element in this array has fields for first name, last name, street address, and other address information. There can be any number of elements in the array to describe the different types of account addresses.

Each field in an array element has an element ID, which specifies the element of the array to which the field belongs. This element ID, in addition to the field name of the array, uniquely identifies the field in a storable object.

Arrays in BRM are sparse arrays and not C language style arrays. The elements in the array are not in any sequential order. Unlike C, the array element a[24] does not mean that there are 23 elements preceding it.You can add an element in any order with an arbitrary element ID.

The elements of a BRM array are not pre-allocated; they are assigned by applications as needed. Therefore, the missing elements in the sequence of element IDs do not use any memory or disk space.

You can add and delete elements from an array using the flist field manipulation macros. When you add an element to an array by using PIN_FLIST_ELEM_ADD, an array is automatically created. You do not have to create an array before adding elements to it.

For information on how to use the macros, see "Flist Field-Handling Macros" in BRM Developer's Reference.

Substructure

Use the substruct data type PIN_FLDT_SUBSTRUCT to group several data types. You use substructs to define a field that contains several fields of different data types. Substructs can contain any of the BRM supported data types, including arrays, and they can be nested to any level.

Note:

Use substructs to create subclasses of the default classes included with BRM.

Because there is only one element, substructs are fully identified by the field name in the object class. Unlike the arrays, they do not require element IDs.

Use the Flist field-handling macros to create and manipulate substructs.

Buffer Data

The buffer type flist field (PIN_FLDT_BUF) is used for large text files or binary data as an array of bytes.

xbuf stands for external buffer. The buf data is not in memory but is written directly from a file to the wire or from the wire to a file. The most common use for xbufs are for systems with limited or slow virtual memory. xbufs can only be used from an application.

A buffer (buf) field represented by the pin_buf_t has the following structure:

/* 
      * data buffer. 
      */
     typedef struct pin_buf {
            int32    flag;        /* if XBUF, ... */
            int32    size;        /* size of data */
            int32    offset;      /* offset (for read) */
            caddr_t  data;        /* pointer to data (BUF) */
            char     *xbuf_file;  /* ptr to filename for XBUF */
    } pin_buf_t;

xbuf values are defined for the flag field. These can be bit-wise-ORed together.

/* users want data from/to a file...*/
  
#define PCM_BUF_FLAG_XBUF       0x0001
  
/* if XBUF, encode filename, not data*/
  
#define PCM_BUF_FLAG_XBUF_READ  0x0002

Table 5-3 describes the pin_buf_t.flag values.

Table 5-3 Values for pin_buf_t.flag

Flag	Description
pin_buf_t.flag = 0x0	Buffer data is assumed to be available in pin_buf_t.data field in memory. The pin_buf_t.xbuf_file field is ignored.
pin_buf_t.flag = 0x1 (PCM_BUF_FLAG_XBUF)	Use this to write data to a buf field in an object. The buffer data is assumed to be available in the file pointed to by the pin_buf_t.xbuf_file field. The data is read from the file only when the flist is shipped on the wire.
pin_buf_t.flag = 0x3 (PCM_BUF_FLAG_XBUF \| PCM_BUF_FLAG_XBUF_READ)	Use this to read data from a buf field in an object. The buffer data is written directly to the file pointed to by the pin_buf_t.xbuf_file field.

Setting Buffer Data Fields in an Flist

The following example shows how to set a buffer field in an flist:

pin_buf_t buft;
buft.flag       = 0;
buft.size       = 26;
buft.offset     = 0; /* not used */
buft.data       = "abcdefghijklmnopqrstuvwxyz";
buft.xbuf_file  = NULL; /* not used */
  
PIN_FLIST_FLD_SET(flistp, PIN_FLD_BUFFER, &buft, &ebuf);

To avoid reallocating memory and copying the buffers in large buffers, use PIN_FLIST_FLD_PUT.

Important:

When you use PUT instead of SET, allocate memory on the heap for both the pin_buf_t data structure and the buffer data.

Getting Buffer Fields From an Flist

When accessing buffer fields from an flist, you set a pointer to a pin_buf_t data structure.

If you use TAKE() instead of GET(), make sure you free up the pin_buf_t structure, the data pointer, and the xbuf_file members in it.

Specifying Buffer Data Fields in Flist Converted to Strings

You can specify buffer fields in flist. For example, you might want to load an flist with a buf field into testnap. The following example provides the buffer data in place:

0 PIN_FLD_POID POID [0] $DB /xx 1
0 PIN_FLD_BUFFER BUF [0] flag/size/offset 0x2 26 0 data:
     0x000000 6162636465666768696a6b6c6d6e6f70 
     0x000010 7172737475767778797a

You can specify xbuf data as in the following example, where the file ./xxx is read and the contents sent to the wire:

>testnap
 ===> database 0.0.0.1 from pin.conf "userid"
> r xxx 1
> d 1
0   PIN_FLD_POID POID [0] $DB /xx 1
0   PIN_FLD_BUFFER BUF [0] flag/size/offset/xbuf_file 0x1 26 0 ./xxx

To read buffer data into a file (for example, ./yyy from an /account object PIN_FLD_INTERNAL_NOTES field), do the following. The flist is stored in the rd.flist file:

>testnap
 ===> database 0.0.0.1 from pin.conf "userid"
> r rd.flist 1
> d 1
0   PIN_FLD_POID POID [0] $DB /account 1
0   PIN_FLD_INTERNAL_NOTES BUF [0] flag/size/offset/xbuf_file 0x3 26 0 ./yyy
>r flds 1

The contents of the PIN_FLD_INTERNAL_NOTES field is put into the file ./yyy.

Note:

You cannot specify file offsets when reading from or writing to files.

Error Buffer

The PIN_FLDT_ERRBUF data type is used to record errors by the Portal Communication Module (PCM) opcodes and Portal Information Network (PIN) library macros. You call the error- or message-logging macros in the PIN library to detect the errors and to record the details of the error in a standard format.

For information on error handling in BRM, see "Understanding API Error Handling and Logging". For descriptions of all the macros available for logging messages and errors, see "Error-Handling Macros" in BRM Developer's Reference.

For a complete list of the errors and values discussed in this section, see BRM_Home/include/pin.errs.h.

pin_errbuf_t has the following structure:

typedef struct {
             int32            location;
             int32            pin_errclass;
             int32            pin_err;
             pin_fld_num_t    field;
             int32            rec_id;
             int32            reserved;
             int32            line_no;
             char            *filename;
             int             facility;
             int             msg_id;
             int             err_time_sec;
             int             err_time_usec;
             int             version;
             pin_flist_t     *argsp;
             pin_errbuf_t    *nextp;
             int             reserved2
} pin_errbuf_t;

Table 5-4 contains the definitions of each field in the pin_errbuf structure.

Table 5-4 Field Definitions in pin_errbuf

Field	Possible Values
location	Specifies the BRM module that encountered the error. Possible values are: PIN_ERRLOC_APP The error occurred within an application. Use this value to specify that the problem originated in your application as opposed to a part of BRM. PIN_ERRLOC_FLIST The error occurred within an flist manipulation routine local to the application. Common causes include illegal parameters and low system memory. PIN_ERRLOC_POID The error occurred within a POID manipulation routine local to the application. Common causes include illegal parameters and low system memory. PIN_ERRLOC_PCM The error occurred within a PCM routine local to the application. Common causes include illegal parameters. PIN_ERRLOC_PCP The error occurred within the internal PCP library. This library provides communication support between the modules of the BRM. Common causes include network connection failures. This value indicates a system problem that requires immediate attention. PIN_ERRLOC_CM The error occurred within the Connection Manager. Common causes include an unknown opcode or an input flist missing the required POID field. PIN_ERRLOC_FM The error occurred within a Facilities Module. Common causes include an input flist that does not conform to the required specification. PIN_ERRLOC_DM The error occurred within a Data Manager. Common causes include an input flist that does not meet the required specifications or a problem communicating with the BRM database.
pin_errclass	Describes the class of error that occurred. Error class is used by an application to determine the appropriate type of error recovery. Possible values are: PIN_ERRCLASS_APPLICATION The error was caused by the application passing illegal data or a system failure within the client application. The error was detected before the requested operation was performed, so no data in the database has changed. After the error is fixed, you can retry the operation. PIN_ERRCLASS_SYSTEM_RETRYABLE The error was probably caused by a transient condition. You can try the operation again. Common causes include a possibly temporary shortage of system resources or failure of a network connection that you can route around. The error was detected before any data was committed to the database; no data has changed. PIN_ERRCLASS_SYSTEM_DETERMINATE The error was caused by a system failure during the operation. Retrying the operation is unlikely to succeed, and the system failure should be investigated immediately. The error was detected before any data was committed to the database; no data has changed. After the error is fixed, you can retry the operation. PIN_ERRCLASS_SYSTEM_INDETERMINATE The error was caused by a system failure during the commit phase of an operation. There is a small window during the commit where a network failure can leave the system unsure of whether the commit occurred or not. This means it is up to the application to determine whether system data has been changed. This class of error is extremely rare, but you must deal with it carefully to avoid corrupting the data in the database. If you determine that no changes were made, you can resolve the system failure problem and then retry the operation.
pin_err	Describes the exact error that was encountered. If an API call was successful, pin_err is set to PIN_ERR_NONE and all other fields in the ebuf are left undefined. If an API call results in an error, one or more of the fields are defined with error information.
field	Identifies the field number of the input parameter that caused the error.
rec_id	Specifies the element ID of an array element that caused the error.
reserved	Designates an internal system state used by Oracle Technical Support for debugging. Contains no useful information for the application developer.
line_no	Specifies the line number within the application source file where the error was detected. The logging routines print the filename and line number from the ebuf, which you can use to locate the exact call to the BRM API that caused the error. Contains no useful information for the application developer except when working with Oracle Technical Support
filename	Specifies the name of the application source file where the error was detected. This can be used in conjunction with the line_no to quickly locate the source of an error. This information is useful for application developers only when they work with Oracle Technical Support.
facility	Specifies the code of a facility associated with BRM internationalization (I18N) features. Used with the msg_id value to create a localized error message.
msg_id	Specifies a unique ID number for each message within the facility identified by the facility code. Used with the facility value to create a localized error message.
err_time_sec	Outputs time in seconds when the error occurred.
err_time_usec	Outputs time in microseconds when the error occurred.
version	Designates the version of the arguments.
pin_flist_t \| *argsp	Used as an optional arguments flist.
pin_errbuf_t *nextp	Used an one or more optional chained errbufs.
reserved2	Reserved for internal use