Technical Overview 04 - BRM Data Model

BRM Technical Overview
BRM Data Model
CAGBU Enablement Team

Safe harbor statement
The following is intended to outline our general product direction. It is intended for information
purposes only, and may not be incorporated into any contract. It is not a commitment to deliver any
material, code, or functionality, and should not be relied upon in making purchasing decisions. The
development, release, timing, and pricing of any features or functionality described for Oracle’s
products may change and remains at the sole discretion of Oracle Corporation.
2 Copyright © 2020, Oracle and/or its affiliates

BRM Data Model
1 Storable classes
2 Flists
3 Fields
4 Database Mapping
5 Tools

Storable Class definition
• A storable class defines the structure for a set of data to be stored in the BRM database.
• The fields in a storable class can span more than one database table.
/account
PIN_FLD_POID
PIN_FLD_ACCOUNT_NO
PIN_FLD_NAMEINFO
PIN_FLD_LAST_NAME
PIN_FLD_ADDRESS

Storable Class Naming Conventions
• A class name begins with /service

a forward slash (/)
PIN_FLD_POID PIN_FLDT_POID
- Example: /service PIN_FLD_ACCOUNT_OBJ PIN_FLDT_POID
PIN_FLD_LOGIN PIN_FLDT_STR
• Subclasses are separated by another PIN_FLD_PASSWD PIN_FLDT_STR
slash (/)
- Example: /service/ip, /service/fax
/service/ip /service/fax
PIN_FLD_PROTOCOL PIN_FLDT_STR
Storable Class Extensions
/service
• A subclass inherits the parent class PIN_FLD_ACCOUNT_OBJ PIN_FLDT_POID
definition: PIN_FLD_LOGIN PIN_FLDT_STR

PIN_FLD_PASSWD PIN_FLDT_STR
- Unextended subclasses have no additional

data; their class definition is the same as
the parent class
/service/ip /service/fax
- Extended subclasses have Extended – Inherits from parent, Unextended – Inherits from
extended data in addition to the data plus additional data parent, no additional data
defined by their parent class PIN_FLD_SERVICE_INFO
PIN_FLD_IPADDR
PIN_FLD_PROTOCOL
PIN_FLD_COMPRESSION

Storable Object
A storable object is an instance of a storable class. It is the actual set of

data stored in the BRM database.
Storable Class Storable Object

/account
PIN_FLD_POID 0.0.0.1 /account 12345 1
PIN_FLD_ACCOUNT_NO 0.0.0.1-12345
PIN_FLD_NAMEINFO NAMEINFO[1]
PIN_FLD_LAST_NAME Smith
PIN_FLD_ADDRESS 123 Elm Street

Documentation
The data model is fully documented in the BRM documentation which is publicly available.

BRM Data Model
1 Storable classes
2 Flists
3 Fields
4 Database Mapping
5 Tools

What is an Flist?
• The Flist is the primary data representation used in BRM.

• Flists are containers that hold fields, each of which is a pair consisting of a data field
name and its value.
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/beid 10670 0

0 PIN_FLD_CREATED_T TSTAMP [0] (1162303292) Tue Oct 31 15:01:32 2006
0 PIN_FLD_NAME STR [0] "pin_beid"
0 PIN_FLD_PROGRAM_NAME STR [0] "-"
0 PIN_FLD_BALANCES ARRAY [36] allocated 20, used 10
1 PIN_FLD_BEID_STR_CODE STR [0] "A$"
1 PIN_FLD_NAME STR [0] "Australian Dollar"
1 PIN_FLD_STATUS ENUM [0] 1
1 PIN_FLD_SYMBOL STR [0] " $ "
1 PIN_FLD_RULES ARRAY [5] allocated 20, used 7
2 PIN_FLD_EVENT_TYPE STR [0] "*"
2 PIN_FLD_PROCESSING_STAGE ENUM [0] 0
2 PIN_FLD_ROUNDING INT [0] 2
2 PIN_FLD_ROUNDING_MODE ENUM [0] 0

What is an Flist?
• Attributes of an Flist:
- Nesting level 0 PIN_FLD_POID POID [0] 0.0.0.1 /config/beid 10670 0

- Field name 0
0
PIN_FLD_CREATED_T
PIN_FLD_NAME
TSTAMP [0] (1162303292) Tue Oct 31 15:01:32 2006
STR [0] "pin_beid"
- Data type 0 PIN_FLD_PROGRAM_NAME STR [0] "-"
- Field value 0
1
PIN_FLD_BALANCES ARRAY [36] allocated 20, used 10
PIN_FLD_BEID_STR_CODE STR [0] "A$"

Flists and BRM Functions
Flists are used to pass input data to and output from BRM functions (opcodes).
Input flist BRM Output flist

Opcode

Flists and Storable objects
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/beid 10670 0

Flists are used to represent 0 PIN_FLD_CREATED_T TSTAMP [0] (1162303292) Tue Oct 31 15:01:32 2006
storable objects.
0 PIN_FLD_MOD_T TSTAMP [0] (1162303292) Tue Oct 31 15:01:32 2006
0 PIN_FLD_ACCOUNT_OBJ POID [0] 0.0.0.1 /account 1 0
0 PIN_FLD_HOSTNAME STR [0] "-"
0 PIN_FLD_NAME STR [0] "pin_beid"
0 PIN_FLD_PROGRAM_NAME STR [0] "-"
0 PIN_FLD_BALANCES ARRAY [36] allocated 20, used 10
1 PIN_FLD_BEID_STR_CODE STR [0] "A$"
1 PIN_FLD_CONSUMPTION_RULE ENUM [0] 0
2 PIN_FLD_TOLERANCE_AMOUNT_MAX DECIMAL [0] 0.05
2 PIN_FLD_TOLERANCE_AMOUNT_MIN DECIMAL [0] 0.01
2 PIN_FLD_TOLERANCE_PERCENT DECIMAL [0] 0.04

Flist Specification Syntax
• Input and output data of BRM functions
Nesting Field Name Data Type Permissions

Level
0 NAME string M
0 ADDRESS string O

Flist Specification Syntax
• Storable classes
Nesting Field Name Field Data Permissions

Level Type creation/modify
0 POID string S Not W

0 NAME string R W
0 ADDRESS string O W
0 DOB string P Not W

Setting Permissions for news storable classes
There are two types of permissions for each field:
• Permissions used at the time an object is being created:

- P (prohibited): Field value can be set only after an object is created
- R (required): Field value must be provided when object is created
- O (optional): Field value is optional when object is created
- S (system): Reserved for fields whose values are set by BRM; for example,
PIN_FLD_CREATED_T, PIN_FLD_POID
• Permissions controlling whether the field is modifiable:

- Writeable: When selected, the field can be modified after a storable object
containing it has been created

BRM Data Model
1 Storable classes
2 Flists
3 Fields
4 Database Mapping
5 Tools

Field Names
• Field names are stored in BRM as numerical values

• Data types are defined in the header file
• Definition contains two pieces of information:
- Field ID number
- Data type (as a numerical value)
pin_flds.h
#define PIN_FLD_POID PIN_MAKE_FLD(PIN_FLDT_POID, 16)

BRM Field Data Types
BRM defines a set of data types used with Flist specifications:
• Simple data types generally correspond to C data types.
• The complex data types are specific to BRM.
Examples:
- POID ( Portal Object ID)
- Array
- Substruct
- Buffer

BRM Simple Data Types
Data Type Description

PIN_FLDT_INT Signed Integer
PIN_FLDT_ENUM Enumerated Integer
PIN_FLDT_DECIMAL Decimal Number
PIN_FLDT_STR Character String
PIN_FLDT_BINSTR Binary String
PIN_FLDT_TSTAMP Timestamp

Timestamps
A BRM timestamp is:
• a UNIX timestamp with 1 second accuracy
• represented as an integer interpreted as the number of seconds past January 1, 1970

at 00:00:00 UTC.

Timestamps
• Database value is always UTC

• Logs display human readable time based on system configuration.
[omsuser@cm test]$ export TZ='Australia/Tasmania'

[omsuser@cm test]$ testnap
===> database 0.0.0.1 from pin.conf "userid"
nap(19964)> robj - 0.0.0.1 /account 1
# number of field entries allocated 44, used 43
0 PIN_FLD_POID POID [0] 0.0.0.1 /account 1 1
0 PIN_FLD_CREATED_T TSTAMP [0] (1618317281) Tue Apr 13 22:34:41 2021
…
[omsuser@cm test]$ export TZ='Europe/Rome'
nap(20041)> robj - 0.0.0.1 /account 1

BRM Complex Data Types
Data Type Description

PIN_FLDT_POID Portal Object ID
PIN_FLDT_ARRAY Array (of nested flists)
PIN_FLDT_SUBSTRUCT Substructure (nested flist)
PIN_FLDT_BUF Arbitrary buffer of data

BRM Object ID (POID) Data Type
A POID:
• Uniquely identifies a set of data (storable object) in the BRM database
• Value contains four pieces of information:
- Database number
- Object type (storable class name)
- Object ID
- Revision level
0.0.0.1 /account 12345 0
Revision increments
Storable class name as object is modified
DB number identifies Object ID assigned by the DB

the external system (Oracle sequence #)

Using POIDs to Relate Objects
• Account storable class flist specification

POID data type
PIN_FLD_BILL_OBJ PIN_FLDT_POID
•
• Example: Account object
PIN_FLD_POID 0.0.0.1 /account 5678 23
PIN_FLD_BILL_OBJ 0.0.0.1 /bill 1234 0
• Example: Bill object

PIN_FLD_POID 0.0.0.1 /bill 1234 3
PIN_FLD_DUE 19.95

Partial POIDS
A partial or type-only poid is:
• a poid with the object identifier set to -1

• used when creating or search for objects when the poid id not (yet) known
0 PIN_FLD_POID POID [0] 0.0.0.1 /device/sim -1 0

PIN_FLDT_SUBSTRUCT Data Type
A substruct is:
• A reference to a nested flist

• Typically used with storable subclasses to define the extended set of
data
- For performance reasons, Oracle recommends that nested flists be limited to
three levels but there is no technical limit to nesting level
• Used with input and output flist specs to segregate sets of data

Example: Substruct Data Type
PIN_FLD_ACCOUNT_OBJ PIN_FLDT_POID
PIN_FLD_SERVICE_IP PIN_FLDT_SUBSTRUCT
PIN_FLD_IPADDR PIN_FLDT_STR
PIN_FLD_PROTOCOL PIN_FLDT_STR
PIN_FLD_COMPRESSION PIN_FLDT_STR
PIN_FLDT_ARRAY Data Type
• An array data type references an array of nested flists.
• Each flist in the array is referenced by an element ID:

- These are sparse arrays; the element ID does not have to start with 0 or 1
- Element IDs do not have to be sequential
• Each element in the array shares the same flist specification:

- Field name, value, nesting level, permissions
- An array with only one element is functionally equivalent to a substruct (refers
to a single nested flist)

Example: Array Data Type
PIN_FLD_ACCOUNT_OBJ PIN_FLDT_POID
PIN_FLD_ARGS PIN_FLDT_ARRAY[element ID]
PIN_FLD_NAME PIN_FLDT_STR
PIN_FLD_VALUE PIN_FLDT_STR
Substruct Versus Array
PIN_FLD_POID PIN_FLDT_POID PIN_FLD_POID PIN_FLDT_POID
PIN_FLD_ACCOUNT_OBJ PIN_FLDT_POID PIN_FLD_ACCOUNT_OBJ PIN_FLDT_POID
PIN_FLD_LOGIN PIN_FLDT_STR PIN_FLD_LOGIN PIN_FLDT_STR
PIN_FLD_PASSWD PIN_FLDT_STR PIN_FLD_PASSWD PIN_FLDT_STR
PIN_FLD_SERVICE_IP PIN_FLDT_SUBSTRUCT PIN_FLD_ARGS PIN_FLDT_ARRAY[ ]
PIN_FLD_IPADDR PIN_FLDT_STR PIN_FLD_NAME PIN_FLDT_STR

PIN_FLD_PROTOCOL PIN_FLDT_STR PIN_FLD_VALUE PIN_FLDT_STR
PIN_FLD_COMPRESSION PIN_FLDT_STR
PIN_FLD_POID 0.0.0.1 /service 1234 3

PIN_FLD_POID 0.0.0.1 /service 1234 3 PIN_FLD_ACCOUNT_OBJ 0.0.0.1 /account 5678 0
PIN_FLD_ACCOUNT_OBJ 0.0.0.1 /account 5678 0 PIN_FLD_LOGIN “test”
PIN_FLD_LOGIN “test” PIN_FLD_PASSWD “test”
PIN_FLD_PASSWD “test” PIN_FLD_ARGS [100]
PIN_FLD_SERVICE_IP PIN_FLD_ARGS [200]
PIN_FLD_ARGS [300]
PIN_FLD_IPADDR “156.151.1.1”
PIN_FLD_NAME “third”
PIN_FLD_PROTOCOL “PPP”
PIN_FLD_NAME “second”
PIN_FLD_COMPRESSION “OFF”
PIN_FLD_NAME “first”
PIN_FLD_VALUE “one”
Example: Buffer Data Type
PIN_FLD_BILL_OBJ PIN_FLDT_POID
PIN_FLD_STATUS PIN_FLDT_ENUM
PIN_FLD_ACCOUNT_NO PIN_FLDT_STR
PIN_FLD_INTERNAL_NOTES PIN_FLDT_BUF
BLOB

BRM Data Model
1 Storable classes
2 Flists
3 Fields
4 Database Mapping
5 Tools

Flist-to-Database Mapping Rules
• DM translates each flist of data to database tables

- Base flists, substructs, arrays, and buffers
• Most fields translate to one column name except for the following data
types:
- POIDs translate to four columns
- A substruct table has an extra column for the object ID from the POID
- An array table has two extra columns for the object ID from the POID and the
element ID

Flist-to-Database Mapping
/service/ip service_t
PIN_FLD_POID 0.0.0.1 /service 1234 3 poid_db poid_type poid_id0 poid_rev login passwd
PIN_FLD_ACCOUNT_OBJ 0.0.0.1 /account 9876 0
0.0.0.1 /service/ip 1234 3 “test” “test”
PIN_FLD_LOGIN “test”
0.0.0.1 /service/ip 5678 6 “joe” “joe”
PIN_FLD_PASSWD “test”
PIN_FLD_SERVICE_IP service_ip_t
PIN_FLD_ARGS [100] obj_id0 ipaddr protocol compression
PIN_FLD_ARGS [200] 1234 “156.151.1.1” “PPP” “OFF”
PIN_FLD_ARGS [300] 5678 “156.151.1.2” “SLIP” “ON”
service_ip_args_t
PIN_FLD_IPADDR “156.151.1.1”
obj_id0 rec_id name value
PIN_FLD_PROTOCOL “PPP”
PIN_FLD_COMPRESSION “OFF” 1234 100 “first” “one”
1234 200 “second” “two”
1234 300 “third” “three”
[300] PIN_FLD_NAME “third”
PIN_FLD_NAME “second” 5678 100 “pop” “timbuktu”
PIN_FLD_VALUE “tyioew”
[200] PIN_FLD_NAME “first”
PIN_FLD_VALUE “tyioew” 5678 200 “speed” “28.8K”
[100] PIN_FLD_VALUE “one”
5678 300 “drop line credit” “no”
Database Storage Model
account_t
• The storage model in the BRM database consists
of the relational tables and the data dictionary. POID_DB POID_TYPE POID_ID0 REV AccNum
1 /account 123 12 123
1 /account 456 21 456

• Each storable class maps to one or many
database tables. account_nameinfo_t
OBJ_ID0 Lname Address
• Data Dictionary: 123 Doe 123 Wilson Street
- Field definitions: Field name, data type, and field ID 456 Smith 456 Blarney Ct
number /account
- Storable class definitions: Specification and mapping PIN_FLD_POID

PIN_FLD_ACCOUNT_NO
POID
STR
to Oracle tables and columns PIN_FLD_NAMEINFO ARRAY
PIN_FLD_LAST_NAME STR
PIN_FLD_ADDRESS STR

BRM Data Model
1 Storable classes
2 Flists
3 Fields
4 Database Mapping
5 Tools

Creating class definitions – pin_deploy
• Use the pin_deploy utility to create, read and export storable class
definitions.
• Extract class and field definitions from the BRM database, as in the
following examples:
> pin_deploy field –c > fields.txt
> pin_deploy class –mn /service/webhosting > class.txt
• Deploy custom fields and classes into another server (production

server), as in the following examples:
> pin_deploy create fields.podl
> pin_deploy create class.podl

Reading storable objects – testnap
Use the testnap utility to read storable objects.

nap(3926)> robj - 0.0.0.1 /account 1
0 PIN_FLD_MOD_T TSTAMP [0] (1618317281) Tue Apr 13 12:34:41 2021
0 PIN_FLD_ACCOUNT_NO STR [0] "ROOT"
0 PIN_FLD_ACCOUNT_TAG STR [0] ""
0 PIN_FLD_ACCOUNT_TYPE ENUM [0] 2
0 PIN_FLD_NAME STR [0] "Brand Host"
0 PIN_FLD_NEXT_ITEM_POID_LIST STR [0] ""
0 PIN_FLD_OBJECT_CACHE_TYPE ENUM [0] 0
0 PIN_FLD_RESIDENCE_FLAG ENUM [0] 0
0 PIN_FLD_STATUS_FLAGS INT [0] 0

Technical Overview 04 - BRM Data Model

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Technical Overview 04 - BRM Data Model

Uploaded by

Copyright:

Available Formats

BRM Technical Overview

BRM Data Model

CAGBU Enablement Team

2 Copyright © 2020, Oracle and/or its affiliates

3 Copyright © 2020, Oracle and/or its affiliates

4 Copyright © 2020, Oracle and/or its affiliates

• A class name begins with /service

definition: PIN_FLD_LOGIN PIN_FLDT_STR

- Unextended subclasses have no additional

defined by their parent class PIN_FLD_SERVICE_INFO

6 Copyright © 2020, Oracle and/or its affiliates

A storable object is an instance of a storable class. It is the actual set of

Storable Class Storable Object

7 Copyright © 2020, Oracle and/or its affiliates

8 Copyright © 2020, Oracle and/or its affiliates

9 Copyright © 2020, Oracle and/or its affiliates

• The Flist is the primary data representation used in BRM.

0 PIN_FLD_POID POID [0] 0.0.0.1 /config/beid 10670 0

10 Copyright © 2020, Oracle and/or its affiliates

- Nesting level 0 PIN_FLD_POID POID [0] 0.0.0.1 /config/beid 10670 0

11 Copyright © 2020, Oracle and/or its affiliates

Input flist BRM Output flist

12 Copyright © 2020, Oracle and/or its affiliates

0 PIN_FLD_POID POID [0] 0.0.0.1 /config/beid 10670 0

13 Copyright © 2020, Oracle and/or its affiliates

• Input and output data of BRM functions

Nesting Field Name Data Type Permissions

14 Copyright © 2020, Oracle and/or its affiliates

Nesting Field Name Field Data Permissions

0 POID string S Not W

15 Copyright © 2020, Oracle and/or its affiliates

There are two types of permissions for each field:

• Permissions used at the time an object is being created:

• Permissions controlling whether the field is modifiable:

16 Copyright © 2020, Oracle and/or its affiliates

17 Copyright © 2020, Oracle and/or its affiliates

• Field names are stored in BRM as numerical values

18 Copyright © 2020, Oracle and/or its affiliates

BRM defines a set of data types used with Flist specifications:

• Simple data types generally correspond to C data types.

• The complex data types are specific to BRM.

19 Copyright © 2020, Oracle and/or its affiliates

Data Type Description

PIN_FLDT_ENUM Enumerated Integer

PIN_FLDT_DECIMAL Decimal Number

PIN_FLDT_STR Character String

PIN_FLDT_BINSTR Binary String

20 Copyright © 2020, Oracle and/or its affiliates

A BRM timestamp is:

• a UNIX timestamp with 1 second accuracy

• represented as an integer interpreted as the number of seconds past January 1, 1970

21 Copyright © 2020, Oracle and/or its affiliates

• Database value is always UTC

[omsuser@cm test]$ export TZ='Australia/Tasmania'

22 Copyright © 2020, Oracle and/or its affiliates

Data Type Description

PIN_FLDT_ARRAY Array (of nested flists)

PIN_FLDT_SUBSTRUCT Substructure (nested flist)

PIN_FLDT_BUF Arbitrary buffer of data

23 Copyright © 2020, Oracle and/or its affiliates

DB number identifies Object ID assigned by the DB

24 Copyright © 2020, Oracle and/or its affiliates

• Account storable class flist specification

• Example: Account object