ssg

Hey everyone.  SSG Blogs about a number of topics and this thread is about Oracle BRM.

Welcome.  My name is Allan Anderson. I started doing BRM/Portal Infranet implementations for SSG in 1998. Back then, we did many implementations on Infranet versions 4 and 5 (and, of course, upgrades). In the “oughts” we roughed the dot-bomb years working on Infranet release 6 implementations and are currently working on projects that include both versions 6 and 7. I personally have worked on 9 different BRM implementations over the past 12 years, including FlashNet, US West, Intel Online Services, InterAccess, TrivNet, ATX, T-Mobile USA, Iridium Sattelite,  and Savvis.

My co-workers at SSG have an even more impressive array of credentials, as many did not take “vacations” from consulting as I did to work full-time at any particular company.

Much of my BRM/Infranet knowledge is due to their expertise and help over the years. In a similar fashion i try to share my knowledge with my SSG colleagues whenever possible or when they need help. This really isnt anything special about me personally, but rather the SSG culture of knowledge and solution sharing responsible for much of our success.

Over the course of the past few weeks, I have given much thought to which blog topics would be most beneficial. The blog will cover both basic and obscure BRM functionality and “features”. As this list of features has evolved over the years, i ask you to bear with me when BRM functionality changes from release to release.

The initial list of blog topics include the following:

• De-Mystifying the FLIST
• Understanding the BRM Data Model and Database Mapping
• Writing a Simple Search Using testnap and C
• Scripting using SQL and testnap (loading objects, calling op-codes, etc.)
• Migrating Accounts from External Systems
• Rating Custom Events
• Billing and invoicing for Single Accounts
• Partitioning Overview & Common Tasks

I expect many more topics to be added as I or my SSG colleagues can think of new ones.

So welcome! Hopefully you (or someone out there) will find this blog useful.

Blog #1: De-Mystifying the FLIST

So when i was considering writing a blog about BRM, FLISTS jumped into my mind as a requirement for for any in-depth understanding of BRM and its workings, especially if one wants to do development or customizations of any kind. So having said that:

What the Heck is an FLIST??!?

FLIST is short for “Field List”, and its official definition is: A dynamically built structure of Field-Value pairs.

Since this description is pretty broad, a more detailed description of an FLIST is:
• A dynamically built data structure that is made up of one or more fields
• Made up of Fields which are identified by a unique name, ID, and data type (see $PIN_HOME/include/pin_flds.h for a list of the out-of-box fields)
• Used by BRM to represent objects defined in the data dictionary, and stored in the BRM database
• Used by BRM to define input and output to functional operations called op-codes
• May be converted to a string for logging purposes

FLIST Building Blocks: BRM Fields & Data Types:

The field data types are static and defined by BRM version you are running (you can view the types by looking in $PIN_HOME/include/pcm.h):

STRING (PIN_FLDT_STRING)

Your typical garden-variety null-terminated string. The length of the string is only limited when you want to store this to the BRM database, in which case the length is limited by the field length in the data dictionary and the database table.
Example:

0 PIN_FLD_DESCR STR [0] "Field Description"

INTEGER (PIN_FLDT_INT)

A signed Integer. Used by BRM to represent whole numbers.
Example:

0 PIN_FLD_RESOURCE_ID INT [0] 840

DECIMAL (PIN_FLD_DECIMAL)

Used by BRM to represent numbers with any level of required precision. Amounts, Quantities, etc. In C, represented by pin_decimal_t data type. BigDecimal used in Java applications.
Example:

0 PIN_FLD_TOTAL_DUE DECIMAL [0] 9813.2

ENUMERATION (PIN_FLDT_ENUM)

Used to represent natural numbers. Unsigned integer.
Example:

0 PIN_FLD_BILL_TYPE ENUM [0] 10001

BUFFER (PIN_FLDT_BUF)

Represents a sequence of bytes, typically used for strings of very long length. Stored as a blob when stored in the BRM database.
Example:

0 PIN_FLD_BUFFER BUF [0] flag/size/offset 0x0 109 0 data:
x000000 3c3f786d6c2076657273696f6e3d2231 .
x000040 3e0a093c42494c4c5f4e4f3e42312d35 >..B1-5
x000050 37393134363c2f42494c4c5f4e4f3e0a 79146.
x000060 3c2f696e766f6963653e0a0000 ...

POID (PIN_FLDT_POID)

The POID is a special BRM datatype, and is used to identify a specific instance of a BRM object. A POID contains 4 sub-elements:
Database: The database number for the database in which the object is stored. Unsigned Integer Value.
Type: String value representing the BRM object type represented by the POID. “/account” and “/bill” are examples.
ID: Unique value identifying this particular instance of the object type.
Revision: Unsigned Integer value. Incremented every time an objects data is updated.
Example:

0 PIN_FLD_ACCOUNT_OBJ POID [0] 0.0.0.1 /account 85273 3467

TIMESTAMP (PIN_FLDT_TSTAMP)

Timestamps in BRM are represented by the time_t C data structure. They represent a time in UTC. This is basically a number representing the number of seconds since the epoch.
Example:

0 PIN_FLD_START_T TSTAMP [0] (1267430401) Mon Mar 01 00:00:01 2010

SUBSTRUCT (PIN_FLDT_SUBSTR)

Represents a pointer to another single FLIST.
Note: When displayed as a string, sub-flists in SUBSTRUCTS and ARRAYS are indented and have an incremented “level” (the number before the field name) for each field in the flist.
Example:

0 PIN_FLD_PRODUCT SUBSTRUCT [0] allocated 2, used 2
1 PIN_FLD_NODE_LOCATION STR [0] "portala01#11522/1#20070720-090519.558:portala01#11522/1#20070720-090519.558"

ARRAY (PIN_FLDT_ARRAY)

Represents a pointer to an indexed array of FLISTS. Each array element has an integer index used to fetch individual flists out of the array.

Example:

0 PIN_FLD_ARGS ARRAY [1] allocated 20, used 1
1    PIN_FLD_AR_BILL_OBJ POID [0] 0.0.0.1 /bill 35677761 0
0 PIN_FLD_ARGS ARRAY [2] allocated 20, used 1
1    PIN_FLD_AR_ACCOUNT_OBJ POID [0] 0.0.0.1 /account 85273 3462
0 PIN_FLD_ARGS ARRAY [3] allocated 20, used 1
1    PIN_FLD_EFFECTIVE_T TSTAMP [0] (1267430401) Mon Mar 01 00:00:01 2010

It is important to note the difference between FLISTS that represent acutal BRM domain objects stored in the database and those representing Op-Code API request and response FLISTs.

FLISTs Representing Database Objects:

FLISTs representing objects in the BRM domain have a fixed structure, defined by the data dictionary. All of the FLISTS in this category contain the PIN_FLD_POID field, which identifies the data stucture (via the BRM data dictionary) for the class (identified in the type field of the poid). All objects of a particular class will have the exact same fields associated with them, for the most part (fields defined as optional may or may not be present in an instance of any particular class). The fields that make up a particular object can be modified, but thats a subject for a different blog.
For Example, an /bill object has different fields than an /account object:

/bill:

0 PIN_FLD_POID POID [0] 0.0.0.1 /bill 35677761 4
0 PIN_FLD_CREATED_T TSTAMP [0] (1267511488) Mon Mar 01 22:31:28 2010
0 PIN_FLD_MOD_T TSTAMP [0] (1270155627) Thu Apr 01 14:00:27 2010
0 PIN_FLD_READ_ACCESS STR [0] "L"
0 PIN_FLD_WRITE_ACCESS STR [0] "L"
0 PIN_FLD_ACCOUNT_OBJ POID [0] 0.0.0.1 /account 85273 3462
0 PIN_FLD_ADJUSTED DECIMAL [0] 0
0 PIN_FLD_BILL_NO STR [0] "B1-579146"
0 PIN_FLD_CURRENCY INT [0] 840
0 PIN_FLD_CURRENCY_OPERATOR ENUM [0] 0
0 PIN_FLD_CURRENCY_RATE DECIMAL [0] 0
0 PIN_FLD_CURRENCY_SECONDARY INT [0] 0
0 PIN_FLD_CURRENT_TOTAL DECIMAL [0] 9813.2
0 PIN_FLD_DISPUTED DECIMAL [0] 0
0 PIN_FLD_DUE DECIMAL [0] 9813.2
0 PIN_FLD_DUE_T TSTAMP [0] (1272697200) Sat May 01 00:00:00 2010
0 PIN_FLD_END_T TSTAMP [0] (1270105200) Thu Apr 01 00:00:00 2010
0 PIN_FLD_FLAGS INT [0] 0
0 PIN_FLD_INVOICE_OBJ POID [0] 0.0.0.1 /invoice 35944328 0
0 PIN_FLD_NAME STR [0] "PIN Bill"
0 PIN_FLD_PARENT POID [0] 0.0.0.0 0 0
0 PIN_FLD_PREVIOUS_TOTAL DECIMAL [0] 19735.4
0 PIN_FLD_RECVD DECIMAL [0] 0
0 PIN_FLD_START_T TSTAMP [0] (1267430400) Mon Mar 01 00:00:00 2010
0 PIN_FLD_SUBORDS_TOTAL DECIMAL [0] 0
0 PIN_FLD_TOTAL_DUE DECIMAL [0] 9813.2
0 PIN_FLD_TRANSFERED DECIMAL [0] 0
0 PIN_FLD_WRITEOFF DECIMAL [0] 0

/account:

# number of field entries allocated 107, used 107
0 PIN_FLD_POID POID [0] 0.0.0.1 /account 85273 3467
0 PIN_FLD_CREATED_T TSTAMP [0] (986025600) Sat Mar 31 00:00:00 2001
0 PIN_FLD_MOD_T TSTAMP [0] (1270154072) Thu Apr 01 13:34:32 2010
0 PIN_FLD_READ_ACCESS STR [0] “L”
0 PIN_FLD_WRITE_ACCESS STR [0] “L”
0 PIN_FLD_AAC_ACCESS STR [0] “”
0 PIN_FLD_AAC_PACKAGE STR [0] “”
0 PIN_FLD_AAC_PROMO_CODE STR [0] “”
0 PIN_FLD_AAC_SERIAL_NUM STR [0] “”
0 PIN_FLD_AAC_SOURCE STR [0] “”
0 PIN_FLD_AAC_VENDOR STR [0] “”
0 PIN_FLD_ACCESS_CODE1 STR [0] “”
0 PIN_FLD_ACCESS_CODE2 STR [0] “”
0 PIN_FLD_ACCOUNT_NO STR [0] “084363″
0 PIN_FLD_ACCOUNT_TAG STR [0] “”
0 PIN_FLD_ACCOUNT_TYPE ENUM [0] 1
0 PIN_FLD_ACTG_CYCLE_DOM INT [0] 1
0 PIN_FLD_ACTG_FUTURE_T TSTAMP [0] (1275375600) Tue Jun 01 00:00:00 2010
0 PIN_FLD_ACTG_LAST_T TSTAMP [0] (1270105200) Thu Apr 01 00:00:00 2010
0 PIN_FLD_ACTG_NEXT_T TSTAMP [0] (1272697200) Sat May 01 00:00:00 2010
0 PIN_FLD_ACTG_TYPE ENUM [0] 1
0 PIN_FLD_ATTRIBUTE INT [0] 0
0 PIN_FLD_BILLING_STATE ENUM [0] 0
0 PIN_FLD_BILLING_STATUS ENUM [0] 0
0 PIN_FLD_BILLING_STATUS_FLAGS INT [0] 0
0 PIN_FLD_BILL_ACTGCYCLES_LEFT INT [0] 1
0 PIN_FLD_BILL_MODE STR [0] “”
0 PIN_FLD_BILL_OBJ POID [0] 0.0.0.1 /bill 35847949 0
0 PIN_FLD_BILL_TYPE ENUM [0] 10001
0 PIN_FLD_BILL_WHEN INT [0] 1
0 PIN_FLD_BRAND_OBJ POID [0] 0.0.0.1 /account 1 1000
0 PIN_FLD_BUSINESS_TYPE ENUM [0] 0
0 PIN_FLD_CLOSE_WHEN_T TSTAMP [0] (0)
0 PIN_FLD_CURRENCY INT [0] 840
0 PIN_FLD_CURRENCY_SECONDARY INT [0] 0
0 PIN_FLD_EFFECTIVE_T TSTAMP [0] (1257877737) Tue Nov 10 10:28:57 2009
0 PIN_FLD_EXEMPT_FROM_COLLECTIONS INT [0] 0
0 PIN_FLD_GL_SEGMENT STR [0] “.”
0 PIN_FLD_GROUP_OBJ POID [0] 0.0.0.0 0 0
0 PIN_FLD_INCORPORATED_FLAG ENUM [0] 0
0 PIN_FLD_INTERNAL_NOTES BUF [0] flag/size/offset 0×0 403 0 data:
x000140 3a30383a323720504d0d0a4361746567 :08:27 PM..Categ
x000150 6f72793a20412f522043726564697420 ory: A/R Credit
x000160 4163636f756e740d0a5b437573746f6d Account..[Custom
x000170 6572206e6f7420736174697366696564 er not satisfied
x000180 207769746820736572766963655d2039 with service] 9
x000190 390d0a 9..
0 PIN_FLD_ITEM_POID_LIST STR [0] “0.0.0.1|/item/misc 35844939 0″
0 PIN_FLD_LASTSTAT_CMNT STR [0] “”
0 PIN_FLD_LAST_BILL_OBJ POID [0] 0.0.0.1 /bill 35677761 0
0 PIN_FLD_LAST_BILL_T TSTAMP [0] (1270105200) Thu Apr 01 00:00:00 2010
0 PIN_FLD_LAST_STATUS_T TSTAMP [0] (1001339927) Mon Sep 24 06:58:47 2001
0 PIN_FLD_LINEAGE STR [0] “/0.0.0.1:85273/”
0 PIN_FLD_LOCALE STR [0] “en_US”
0 PIN_FLD_MERCHANT STR [0] “N/A”
0 PIN_FLD_NAME STR [0] “PIN Account Object”
0 PIN_FLD_NEXT_BILL_OBJ POID [0] 0.0.0.0 0 0
0 PIN_FLD_NEXT_BILL_T TSTAMP [0] (1272697200) Sat May 01 00:00:00 2010
0 PIN_FLD_NEXT_ITEM_POID_LIST STR [0] “”
0 PIN_FLD_PARENT POID [0] 0.0.0.0 0 0
0 PIN_FLD_PAYINFO_OBJ POID [0] 0.0.0.1 /payinfo/invoice 26198422 0
0 PIN_FLD_PENDING_RECV DECIMAL [0] 9813.2
0 PIN_FLD_RESIDENCE_FLAG ENUM [0] 1
0 PIN_FLD_SCENARIO_OBJ POID [0] 0.0.0.0 0 0
0 PIN_FLD_STATUS ENUM [0] 10100
0 PIN_FLD_STATUS_FLAGS INT [0] 0
0 PIN_FLD_TIMEZONE_ID STR [0] “”
0 PIN_FLD_VAT_CERT STR [0] “”
0 PIN_FLD_BALANCES ARRAY [840] allocated 8, used 8
1 PIN_FLD_CREDIT_FLOOR DECIMAL [0] NULL
1 PIN_FLD_CREDIT_LIMIT DECIMAL [0] NULL
1 PIN_FLD_CREDIT_THRESHOLDS INT [0] 0
1 PIN_FLD_CURRENT_BAL DECIMAL [0] 17530.08
1 PIN_FLD_FLAGS INT [0] 0
1 PIN_FLD_NEXT_BAL DECIMAL [0] 0
1 PIN_FLD_OPEN_BAL DECIMAL [0] 17530.08
1 PIN_FLD_RESERVED_AMOUNT DECIMAL [0] 0
0 PIN_FLD_NAMEINFO ARRAY [1] allocated 21, used 21
1 PIN_FLD_ADDRESS STR [0] “1475 Military Blvd”
1 PIN_FLD_CANON_COMPANY STR [0] “Xprint”
1 PIN_FLD_CANON_COUNTRY STR [0] “US”
1 PIN_FLD_CITY STR [0] “REDWOOD CITY”
1 PIN_FLD_COMPANY STR [0] “Company Name”
1 PIN_FLD_CONTACT_TYPE STR [0] “Billing”
1 PIN_FLD_COUNTRY STR [0] “USA”
1 PIN_FLD_EMAIL_ADDR STR [0] “nobody@nowhere.com”
1 PIN_FLD_FIRST_CANON STR [0] “accounts”
1 PIN_FLD_FIRST_NAME STR [0] “Accounts”
1 PIN_FLD_LAST_CANON STR [0] “payable”
1 PIN_FLD_LAST_NAME STR [0] “Payable”
1 PIN_FLD_MIDDLE_CANON STR [0] “”
1 PIN_FLD_MIDDLE_NAME STR [0] “”
1 PIN_FLD_SALUTATION STR [0] “”
1 PIN_FLD_SERVICE_OBJ POID [0] 0.0.0.0 0 0
1 PIN_FLD_STATE STR [0] “CA”
1 PIN_FLD_TITLE STR [0] “”
1 PIN_FLD_ZIP STR [0] “94063″
1 PIN_FLD_PHONES ARRAY [0] allocated 2, used 2
2 PIN_FLD_PHONE STR [0] “2145551212″
2 PIN_FLD_TYPE ENUM [0] 2
1 PIN_FLD_PHONES ARRAY [2] allocated 2, used 2
2 PIN_FLD_PHONE STR [0] “N/A”
2 PIN_FLD_TYPE ENUM [0] 2
0 PIN_FLD_PRODUCTS ARRAY [13] allocated 32, used 32
1 PIN_FLD_CREATED_T TSTAMP [0] (986112000) Sun Apr 01 00:00:00 2001
1 PIN_FLD_CYCLE_DISCOUNT DECIMAL [0] 0
1 PIN_FLD_CYCLE_DISC_AMT DECIMAL [0] 0
1 PIN_FLD_CYCLE_END_T TSTAMP [0] (0)
1 PIN_FLD_CYCLE_FEE_AMT DECIMAL [0] 0
1 PIN_FLD_CYCLE_FEE_FLAGS INT [0] 3
1 PIN_FLD_CYCLE_START_T TSTAMP [0] (986112000) Sun Apr 01 00:00:00 2001
1 PIN_FLD_DEAL_OBJ POID [0] 0.0.0.1 /deal 142006 2
1 PIN_FLD_DESCR STR [0] “1-BMX323″
1 PIN_FLD_FLAGS INT [0] 3
1 PIN_FLD_LAST_MODIFIED_T TSTAMP [0] (0)
1 PIN_FLD_MMC_END_T TSTAMP [0] (992835668) Sun Jun 17 20:41:08 2001
1 PIN_FLD_MMC_START_T TSTAMP [0] (992835668) Sun Jun 17 20:41:08 2001
1 PIN_FLD_MMC_TYPE INT [0] 0
1 PIN_FLD_NODE_LOCATION STR [0] “10333199:10330639″
1 PIN_FLD_PLAN_OBJ POID [0] 0.0.0.0 0 0
1 PIN_FLD_PRODUCT_OBJ POID [0] 0.0.0.1 /product 142012 6
1 PIN_FLD_PURCHASE_DISCOUNT DECIMAL [0] 0
1 PIN_FLD_PURCHASE_DISC_AMT DECIMAL [0] 0
1 PIN_FLD_PURCHASE_END_T TSTAMP [0] (0)
1 PIN_FLD_PURCHASE_FEE_AMT DECIMAL [0] 0
1 PIN_FLD_PURCHASE_START_T TSTAMP [0] (986112000) Sun Apr 01 00:00:00 2001
1 PIN_FLD_QUANTITY DECIMAL [0] 1
1 PIN_FLD_SERVICE_OBJ POID [0] 0.0.0.1 /service/evolve 10332791 0
1 PIN_FLD_SMC_END_T TSTAMP [0] (1275375600) Tue Jun 01 00:00:00 2010
1 PIN_FLD_SMC_START_T TSTAMP [0] (1272697200) Sat May 01 00:00:00 2010
1 PIN_FLD_SPONSOR_OBJ POID [0] 0.0.0.0 0 0
1 PIN_FLD_STATUS ENUM [0] 1
1 PIN_FLD_STATUS_FLAGS INT [0] 55599999
1 PIN_FLD_USAGE_DISCOUNT DECIMAL [0] 0
1 PIN_FLD_USAGE_END_T TSTAMP [0] (0)
1 PIN_FLD_USAGE_START_T TSTAMP [0] (986112000) Sun Apr 01 00:00:00 2001

FLISTS Representing Op-Code Calls:

FLISTs are also used as a method of representing input and output to BRM Op-Codes. A given op-code will have a specific FLIST format (i.e. set of fields) defined for both input and output. Here are some examples of FLISTS used for Op-Code Calls:

Example:
PCM_OP_FIND_PROFILE Op-Code:
Input:

# number of field entries allocated 20, used 3
0 PIN_FLD_POID POID [0] 0.0.0.1 /account 85273 3467
0 PIN_FLD_ACCOUNT_OBJ POID [0] 0.0.0.1 /account 85273 3467
0 PIN_FLD_RESULTS ARRAY [0] allocated 20, used 1
1    MDS_FLD_CUST_INFO SUBSTRUCT [0] allocated 20, used 0

Output:

# number of field entries allocated 2, used 2
0 PIN_FLD_POID POID [0] 0.0.0.1 /account 85273 3467
0 PIN_FLD_RESULTS ARRAY [0] allocated 9, used 9
1    PIN_FLD_POID POID [0] 0.0.0.1 /profile/misc/customer_info 85273 1028
1    PIN_FLD_CREATED_T TSTAMP [0] (988756868) Tue May 01 15:41:08 2001
1    PIN_FLD_MOD_T TSTAMP [0] (1150839440) Tue Jun 20 14:37:20 2006
1    PIN_FLD_READ_ACCESS STR [0] "G"
1    PIN_FLD_WRITE_ACCESS STR [0] "S"
1    PIN_FLD_ACCOUNT_OBJ POID [0] 0.0.0.1 /account 85273 1000
1    PIN_FLD_NAME STR [0] "Converted Profile"
1    PIN_FLD_SERVICE_OBJ POID [0] 0.0.0.0 0 0
1    MDS_FLD_CUST_INFO SUBSTRUCT [0] allocated 33, used 33
2       PIN_FLD_EFFECTIVE_T TSTAMP [0] (0)
2       PIN_FLD_GEOCODE STR [0] ""
2       MVS_FLD_FINANCIAL_COMPANY_OBJ POID [0] 0.0.0.0 0 0
2       MDS_FLD_ACCT_ORG_ID STR [0] "MSC US"
2       MDS_FLD_ACCT_ROW_ID STR [0] "1+6CN+411"
2       MDS_FLD_ACCT_SALES_TYPE STR [0] "Web Hosting"
2       MDS_FLD_ACCT_TYPE STR [0] "00"
2       MDS_FLD_BILLING_ADDRESS_ID STR [0] "X1-1-1LB9"
2       MDS_FLD_BILLING_CONTACT_ROW_ID STR [0] "X5-1+7+0"
2       MDS_FLD_BILL_HANDLING_TYPE STR [0] "Normal Billing"
2       MDS_FLD_CUST_CLASS STR [0] ""
2       MDS_FLD_CUTOFF_T TSTAMP [0] (0)
2       MDS_FLD_DELIVERY_DEST STR [0] ""
2       MDS_FLD_DELIVERY_OPT STR [0] ""
2       MDS_FLD_DISC_GROUP STR [0] ""
2       MDS_FLD_DOM_RT_TBL STR [0] ""
2       MDS_FLD_EBILL_MEDIA STR [0] ""
2       MDS_FLD_EBILL_ROLL STR [0] ""
2       MDS_FLD_EVENT_RT_TBL STR [0] ""
2       MDS_FLD_IMG_RT_TBL STR [0] ""
2       MDS_FLD_IMG_RT_TBL_OLD STR [0] ""
2       MDS_FLD_INTL_RT_TBL STR [0] ""
2       MDS_FLD_INVOICE_COMMENTS STR [0] ""
2       MDS_FLD_INVOICE_TYPE STR [0] ""
2       MDS_FLD_INV_HOLD INT [0] 0
2       MDS_FLD_LATE_PAYMENT INT [0] 0
2       MDS_FLD_PRIMARY_ADDRESS_ROW_ID STR [0] "X5-1-1LB9"
2       MDS_FLD_PRINT_OPT STR [0] ""
2       MDS_FLD_REPORT_FREQ STR [0] ""
2       MDS_FLD_REPORT_ID STR [0] ""
2       MDS_FLD_SLSREP_FIRST_NAME STR [0] "ADMINISTRATOR"
2       MDS_FLD_SLSREP_LAST_NAME STR [0] "ADMINISTRATOR"
2       MDS_FLD_SLSREP_LOGIN STR [0] "SADMIN"

FLIST Manipulation using C:

We will start with C manipulation because BRM is written in C. Here are just a few examples of how to manipulate FLISTs and associated fields.

Some Local Variables for our examples:

/* Local Variables */
pin_flist_t *pFlist = NULL;
pin_flist_t *pSubFlist = NULL;
pin_flist_t *pSubAFlist = NULL;
pin_flist_t *pSubBFlist = NULL;

poid_t *pDummyPoid = NULL;
poid_t *pGetPoid = NULL;

char szMsg[256];
char *szGetMsg;

int iResourceId = 0;
int *pResourceId = NULL;
/* End Local Variables */

Creating an empty FLIST:

/* Create the FLIST using the PIN_FLIST_CREATE macro */
pFlist = PIN_FLIST_CREATE( pErrorBuffer );

Most FLIST manipulation macros will require the use of an pin error buffer (pin_errbuf_t *). This error buffer is set if problems occur during the operation.

Adding a POID field to an FLIST:

/* add POID to our newly created FLIST. Create a dummy poid to use. */
pDummyPoid = PIN_POID_CREATE( 1, "/search", (int64) -1, pErrorBuffer );
PIN_FLIST_FLD_SET( pFlist, PIN_FLD_POID, pDummyPOID, pErrorBuffer );

/* Now get the POID off of the FLIST for Logging */
pGetPoid = PIN_FLIST_FLD_GET( pFlist, PIN_FLD_POID, 0, pErrorBuffer );
PIN_ERR_LOG_POID( PIN_ERR_LEVEL_DEBUG, "The Poid Value is:", pGetPoid );

Adding a STRING field to an FLIST:

/* Add a string field to our FLIST */
sprintf( szMsg, "Hello, World!" );
PIN_FLIST_FLD_SET( pFlist, PIN_FLD_DESCR, szMsg, pErrorBuffer );

/* Now get the string off of the FLIST again */
szGetMsg = PIN_FLIST_FLD_GET( pFlist, PIN_FLD_DESCR, 0, pErrorBuffer );
PIN_ERR_LOG_MSG( PIN_ERR_LEVEL_DEBUG, szGetMsg );

Adding an INT field to an FLIST:

/* Add an integer field to our FLIST */
iResourceId = 840;
PIN_FLIST_FLD_SET( pFlist, PIN_FLD_RESOURCE_ID, &iResourceId, pErrorBuffer );

/* Now get the String and Print it. Always check pointers before de-referencing */
pResourceId = PIN_FLIST_FLD_GET( pFlist, PIN_FLD_RESOURCE_ID, 0, pErrorBuffer );
if( NULL != pResourceId ) {
sprintf( szMsg, "The Int Value Is: [%d]", *pResourceId );
PIN_ERR_LOG_MSG( PIN_ERR_LEVEL_DEBUG, szMsg );
}

Adding a SUBSTRUCT sub-flist to an FLIST:

/* Create an FLIST that we will store in the SUBSTRUCT */
pSubFlist = PIN_FLIST_CREATE( pErrorBuffer );
PIN_FLIST_FLD_SET( pSubFlist, PIN_FLD_RESOURCE_ID, &iResourceId, pErrorBuffer );

/* Put the SubFlist in the PIN_FLD_PRODUCT substruct */
/* By using the PUT we transfer the memory management of pSubFlist to pFlist */
/* We could have avoided the PUT by using the PIN_FLIST_SUBSTR_ADD() macro. Similar to the array example below */
pFlist = PIN_FLIST_CREATE( pErrorBuffer );
PIN_FLIST_SUBSTR_PUT( pFlist, pSubFlist, PIN_FLD_PRODUCT, pErrorBuffer );

PIN_ERR_LOG_FLIST( PIN_ERR_LEVEL_DEBUG, "FLIST With a SUBSTRUCT:", pFlist );

/* Frees the memory for both pSubFlist and pFlist */
PIN_FLIST_DESTROY_EX( &pFlist, NULL );

Adding Multiple Sub-FLISTs to an FLIST using an Array Field:

/* Create the top-level FLIST */
pFlist = PIN_FLIST_CREATE( pErrorBuffer );

/* Create an FLIST that we will store in the ARRAY */
/* Here we will use the PIN_FLIST_ELEM_ADD(), which keeps us from having to use PIN_FLIST_CREATE() and PIN_FLIST_ELEM_PUT() */
/* Put SubAFlist in Array Element 1, and SubBFlist in Array Element 2 */
iResourceId = 840;
pSubAFlist = PIN_FLIST_ELEM_ADD( pFlist, PIN_FLD_ARGS, 1, pErrorBuffer );
PIN_FLIST_FLD_SET( pSubAFlist, PIN_FLD_RESOURCE_ID, &iResourceId, pErrorBuffer );

iResourceId = 124;
pSubBFlist = PIN_FLIST_ELEM_ADD( pFlist, PIN_FLD_ARGS, 2, pErrorBuffer );
PIN_FLIST_FLD_SET( pSubBFlist, PIN_FLD_RESOURCE_ID, &iResourceId, pErrorBuffer );

PIN_ERR_LOG_FLIST( PIN_ERR_LEVEL_DEBUG, "FLIST with 2 Sub-Array Elements:", pFlist );

These are the most commonly used field types. If you need to use the others, there are out-of-box examples in policy code to look at ($PIN_HOME/src).