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.
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 |
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.
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:
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 264 and in a partitioned table is 244. |
object revision level |
Revision number. This value is incremented automatically each time the object is updated. You cannot change this value directly. |
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.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.
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.
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. |
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.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.
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.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_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_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 |