BRM Errors

Title: pcm_dyn_attach_mmap() issue

Issue: Following error observed while starting cm or in the cm.pinlog while executing any application connected to CM
mmap failed for pcm_dyn_attach_mmap(): Invalid argument

Cause: This error usually comes when you use reference to some mapping parameter/file in the CM or application's pin.conf and that is invalid or empty. E.g. if the entry file for ops_fields_extension_file is empty or invalid, we can get the error:
mmap failed for pcm_dyn_attach_mmap(): Invalid argument

Title: Resource Credit Limit Issue

Issue:
2:SACJOSHI-US:CustomerCenter:0:AWT-EventQueue-0:108:1476427204:0:root.0.0.0.1:::
        Credit limit exceeded
        <location=PIN_ERRLOC_FM:5 class=PIN_ERRCLASS_SYSTEM_DETERMINATE:1 errno=PIN_ERR_CREDIT_LIMIT_EXCEEDED:81>
        <field num=0:0,0 recid=0 reserved=0 reserved2=0 time(sec:usec)=0:0>
        <facility=0 msg_id=0 version=0>

Cause: This error usually comes when you use NCR (non-currency resource) to have a +ve balance impact. By default the credit limit for NCRs is 0 in BRM. In case, you need to have a positive balance impact on NCR, you need to update the credit limit.

0 PIN_FLD_POID                                   POID [0] 0.0.0.1 /config/credit_profile 201 0
0 PIN_FLD_PROFILES                      ARRAY [2] allocated 2, used 2
1     PIN_FLD_CREDIT_FLOOR   DECIMAL [0] NULL
1     PIN_FLD_CREDIT_LIMIT     DECIMAL [0] NULL


Title: AMT procedure errors

Issue:
ORA-29280: invalid directory path
ORA-06512: at "WK33_PIN03.AMT_MV", line 347
ORA-06512: at line 1

Cause: The directory mentioned in Infranet.properties of pin_amt application is not created or if it is created you are using the name in lowercase, change it to upper case.

Issue:
ORA-29289: directory access denied
ORA-06512: at "WK33_PIN03.AMT_MV", line 347
ORA-06512: at line 1

Cause: Good news is that the directory exists but the db user with which pin_amt is being executed is not having read/write permission.

Issue:
ORA-02055: distributed update operation failed; rollback required
ORA-54013: INSERT operation disallowed on virtual columns
ORA-06512: at "WK33_PIN03.AMT_MV", line 722
ORA-06512: at line 1

Cause: Some table in the AMT_METADATA is having virtual column, check what are the custom tables added and check which one has virtual columns.


Title: Cache entry not found

E Mon Apr  8 16:13:58 2013  <<hostname>>  cm:18233  fm_bill_utils_billing.c(49):1039 1:<<hostname>>:testnap:18231:-136099600:100001:1365405238:1
        Could not find cache entry: "PIN_SEQUENCE_TYPE_PACKAGE_ID"
E Mon Apr  8 16:13:58 2013  <<hostname>>  cm:18233  fm_subscription_purchase_deal.c:805 1:<<hostname>>:testnap:18231:-136099600:100001:1365405238:1
        op_subscription_purchase_deal error
        <location=PIN_ERRLOC_FM:5 class=PIN_ERRCLASS_SYSTEM_DETERMINATE:1 errno=PIN_ERR_NOT_FOUND:3>
        <field num=^Aopsflds:0,0 recid=0 reserved=3 reserved2=0 time(sec:usec)=0:0>
        <facility=0 msg_id=0 version=0>

Resolution: As the cache entry is missing, it means CM could not load few variable, restart cm to fix this.


Title: pricing_admin.pl failed in initializing


-bash-3.2$ ./pricing_admin.pl -init
EBUF: errno=<PIN_ERR_BAD_CRYPT:15> location=<PIN_ERRLOC_DM:4> class=<UNKNOWN:0> field num=<0:0,0> recid=<0> reserved=<0>
0 PIN_FLD_POID                   POID [0] 0.0.0.1 /config/pricing_admin -1 0
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] "config_pricing_admin"
0 PIN_FLD_PROGRAM_NAME            STR [0] "-"
0 PIN_FLD_CONFIG_INFO       SUBSTRUCT [0] allocated 6, used 6
1     PIN_FLD_HOSTNAME            STR [0] "sacjoshi-linux"
1     PIN_FLD_LOGIN               STR [0] "INTEGRATE"
1     PIN_FLD_NAME                STR [0] "brm11gdb"
1     PIN_FLD_PASSWD              STR [0] "integrate"
1     PIN_FLD_PORT                INT [0] 1521
1     PIN_FLD_SERVER_TYPE         STR [0] "oracle"
call_opcode: PCM_OP_CREATE_OBJ failed. at ./pricing_admin.pl line 504.
Initializing config object for pricing admin failed.

Resolution: - crypt md5 entry is not enabled, enable this entry in dm_oracle's pin.conf


Another issue that can sometimes occur due to installation issues is:

-bash-3.2$ ./pricing_admin.pl -set <admins.txt
EBUF: errno=<PIN_ERR_BAD_ARG:4> location=<PIN_ERRLOC_DM:4> class=<UNKNOWN:0> field num=<PIN_FLD_POID:7,16> recid=<0> reserved=<0>
0 PIN_FLD_RESULTS                  ARRAY [*] NULL
0 PIN_FLD_POID                      POID [0] 0.0.0.1 /search -1 0
0 PIN_FLD_ARGS                     ARRAY [1] allocated 1, used 1
1     PIN_FLD_POID                  POID [0] 0.0.0.1 /config/pricing_admin -1 0
0 PIN_FLD_TEMPLATE                   STR [0] "select X from /config/pricing_admin where F1 = V1 "
0 PIN_FLD_FLAGS                      INT [0] 0
call_opcode: PCM_OP_GLOBAL_SEARCH failed. at ./pricing_admin.pl line 504.
Search failed for /config/pricing_admin object.

Storable class to XML representation

I recently noticed this application that converts the storable class representation in database to XML format. Its syntax is:

storableclasstoxml [-h] [-r <filename> [-o <objectname>]]

-h : display help information

-r <filename> : retrieves storable class for

      1. /service and its sub classes

      2. /event and its sub classes

      3. /account class

      and write it to <filename>

-r <filename> -o <objectname> : retrieves storable class for

      <objectname> and write it to <filename>.

      <objectname> can be /service, /event, /account,

      /service/xyz or /event/xyz where xyz is a sub class

      of either /service or /event.  Multiple object types

      can be passed with comma(',') separated.

I'm not sure in which all scenarios this XML representation will be useful. If anyone get a chance to explore this or if someone has already explored, please share with me.

Some useful BRM flists

Here are some useful flists which will be useful for the POCs during development of Oracle BRM based applications.
1). Search flist to find the service and account objects (or POIDS) using the login field value when login is available in the the service


0 PIN_FLD_POID                      POID [0] 0.0.0.1 /search -1 0
0 PIN_FLD_FLAGS                      INT [0] 256
0 PIN_FLD_INDEX_NAME                 STR [0] "service_login_i"
0 PIN_FLD_PARAMETERS                 STR [0] "telco/voice"
0 PIN_FLD_TEMPLATE                   STR [0] "select X from /service/$1 where F1 = V1 and  F2 = V2 "
0 PIN_FLD_RESULTS                  ARRAY [0] allocated 7, used 7
1     PIN_FLD_POID                  POID [0] NULL
1     PIN_FLD_ACCOUNT_OBJ           POID [0] NULL
1     PIN_FLD_LOGIN                  STR [0] NULL
1     PIN_FLD_PASSWD                 STR [0] NULL
1     PIN_FLD_PASSWD_EXPIRATION_T TSTAMP [0] (0) 01/01/1970 05:30:00:000 AM
1     PIN_FLD_PASSWD_STATUS         ENUM [0] 0
1     PIN_FLD_STATUS                ENUM [0] 0
0 PIN_FLD_ARGS                     ARRAY [1] allocated 1, used 1
1     PIN_FLD_POID                  POID [0] 0.0.0.1 /service/ip -1 0
0 PIN_FLD_ARGS                     ARRAY [2] allocated 1, used 1
1     PIN_FLD_LOGIN                  STR [0] "your-login"

2). Search flist to find the service and account objects (or POIDS) using the alias field value when login is not  available in the the service

0 PIN_FLD_POID                      POID [0] 0.0.0.1 /search -1 0

0 PIN_FLD_FLAGS                      INT [0] 256

0 PIN_FLD_INDEX_NAME                 STR [0] "service_alias_list_name_i"

0 PIN_FLD_PARAMETERS                 STR [0] "telco/voice"

0 PIN_FLD_TEMPLATE                   STR [0] "select X from /service/$1 where F1 = V1 and  F2 = V2 "

0 PIN_FLD_RESULTS                  ARRAY [0] allocated 7, used 7

1     PIN_FLD_POID                  POID [0] NULL

1     PIN_FLD_ACCOUNT_OBJ           POID [0] NULL

1     PIN_FLD_LOGIN                  STR [0] NULL

1     PIN_FLD_PASSWD                 STR [0] NULL

1     PIN_FLD_PASSWD_EXPIRATION_T TSTAMP [0] (0) 01/01/1970 05:30:00:000 AM

1     PIN_FLD_PASSWD_STATUS         ENUM [0] 0

1     PIN_FLD_STATUS                ENUM [0] 0

0 PIN_FLD_ARGS                     ARRAY [1] allocated 1, used 1

1     PIN_FLD_POID                  POID [0] 0.0.0.1 /service/telco/gsm/telephony -1 0

0 PIN_FLD_ARGS                     ARRAY [2] allocated 1, used 1

1     PIN_FLD_ALIAS_LIST           ARRAY [*] allocated 1, used 1

2         PIN_FLD_NAME               STR [0] "9830000011"

3). Flist to create customer without plan/deals/products (PCM_OP_CUST_COMMIT_CUSTOMER)

0 PIN_FLD_POID POID [0]  0.0.0.1 /plan 9198 0

0 PIN_FLD_ACCTINFO ARRAY [0]  

1 PIN_FLD_POID POID [0] 0.0.0.1 /account -1 0

0 PIN_FLD_PAYINFO ARRAY [0]  

1 PIN_FLD_POID POID [0] 0.0.0.1 /payinfo/invoice -1 0

1 PIN_FLD_PAY_TYPE ENUM [0] 10001

1 PIN_FLD_INHERITED_INFO      SUBSTRUCT [0]

2 PIN_FLD_INV_INFO ARRAY [0]

3 PIN_FLD_ADDRESS   STR [0] "Castro Street"

3 PIN_FLD_CITY   STR [0] "San Fransisco"

3 PIN_FLD_COUNTRY   STR [0] "US"

0 PIN_FLD_NAMEINFO ARRAY [1]  

1 PIN_FLD_LAST_NAME STR [0] "LastN"

1 PIN_FLD_FIRST_NAME STR [0] "FirstN"

1 PIN_FLD_ADDRESS STR [0] "113, Castro Street"

1 PIN_FLD_CITY STR [0] "San Fransisco"

1 PIN_FLD_STATE STR [0] "CA"

1 PIN_FLD_COUNTRY STR [0] "US"

1 PIN_FLD_ZIP STR [0] "53038"

1 PIN_FLD_COMPANY STR [0] "ABC"

1 PIN_FLD_EMAIL_ADDR STR [0] "test@test.com"

0 PIN_FLD_SERVICES ARRAY [0]  

1 PIN_FLD_SERVICE_OBJ POID [0] 0.0.0.1 /service/telco/gsm/telephony -1 0

Enabling pin_virtual_time first time after BRM 7.4 installation

During development many times we need pin_virtual_time utility to move the BRM time forward to test many scenarios like billing, invoicing, dunning et.c.
After installing the BRM 7.4 components in the server, generally the pin_virtual_time_file is not created and also the entry is commented in almost all the component's pin.conf file.
Here are some tips to enable the pin_virtual_time (may be useful to novice BRM developers/testers)

1). Uncomment pin_virtual_time entry in all the components' pin.conf file. You may run the following command :
find  $PIN_HOME/ -name "pin.conf" | xargs sed -i 's/# - - pin_virtual_time/- - pin_virtual_time/g'
2). Restart the BRM server
3). Goto the $PIN_HOME/sys/test directory and execute
    $> pin_virtual_time
    This will create the pin_virtual_time_file and from now on you can move the time.

PIN_VIRTUAL_TIME USAGE
usage: pin_virtual_time [-h|-H|-?] [-f filename] [-m mode [value]]|[-i interval]
    -h, -H, -? print this message.
    -m ... set pin_virtual_time to mode, nothing or -i query pin_virtual_time
    mode is 0 (regular), 1 (fixed) or 2 (running)
    value as [mmdd]HHMM[[cc]yy][.SS]
    interval is time between queries in seconds

Search flist to find billinfo and account poid using account_no

Following is a complex search flist for finding BILLINFO poid and ACCOUNT poid using the ACCOUNT_NO field. As such this is used while running the bill utility during test runs but consider it as a sample for searching and extracting field values from two different storable class in single search. Generally, using a simple flist this is not achievable.

0 PIN_FLD_POID                      POID [0] 0.0.0.1 /search -1 0
0 PIN_FLD_FLAGS                      INT [0] 768
0 PIN_FLD_TEMPLATE                   STR [0] " select X from /account 1, /billinfo 2 where 1.F1 = 2.F2 and 1.F3 = V3 "
0 PIN_FLD_RESULTS                  ARRAY [*] allocated 2, used 2
1     PIN_FLD_POID                  POID [0] NULL
1     PIN_FLD_LINKED_OBJ           ARRAY [2] allocated 3, used 3
2         PIN_FLD_ACCOUNT_OBJ       POID [0] NULL
2         PIN_FLD_LINK_DIRECTION    ENUM [0] 1
2         PIN_FLD_EXTRA_RESULTS    ARRAY [*] allocated 1, used 1
3             PIN_FLD_POID          POID [0] NULL
0 PIN_FLD_ARGS                     ARRAY [1] allocated 1, used 1
1     PIN_FLD_POID                  POID [0] NULL
0 PIN_FLD_ARGS                     ARRAY [2] allocated 1, used 1
1     PIN_FLD_ACCOUNT_OBJ           POID [0] NULL
0 PIN_FLD_ARGS                     ARRAY [3] allocated 1, used 1
1     PIN_FLD_ACCOUNT_NO             STR [0] "0.0.0.1-90356"

I will provide the explaination shortly.

Utility to move pin_virtual_time(mode 1) and execute pin_bill_day

It sounds like huh, why should I need a script for changing virtual time or executing pin_bill_day but it has utility. Specially for BRM testing, there are scenarios where the movement of time followed by execution of pin_bill_day and pin_ledger_report are required, e.g.
   - Testing of invalid (soft declined/hard declined) credit cards
   - Checking the monthly bill for a certain period of time
   - Accounting validation by looking at General Ledger(GL) reports of certain months
   - Checking the expiration of the non-currency date based resources valid for a year
   - and so on

So this script has the following modes of operation when you will execute it :

$> perl tbill.pl
Current time is : mode 1  1367341200  Tue Apr 30 10:00:00 2013
mode 1  1367341200  Tue Apr 30 10:00:00 2013
Select from the following :
        1. Increment time to next day
        2. Increment time to a date
        3. Move time to a date by incrementing one day at a time
        4. Move time to a date by incrementing one month at a time :
        5. Move time to a date by incrementing 15 days at a time
        Your Selection(1|2|3|4|5) :

 Option1 : Increment time to next day and execute pin_bill_day and pin_ledger_report
Option2 : Increment time to a particular date in future like some date after few months in the same year or next year
Option3 : Increment time to a date in future by executing pin_bill_day and pin_ledger_report on each day of that period
Option4 : Increment time to few months by moving one month at a time and executing pin_bill_day and pin_ledger_report each month
Option5 : Increment time to a date by moving 15 day at once and executing pin_bill_day and pin_ledger_report



Here is the link of the script :

Guidelines to write a new FM in BRM

Creating a new FM

Steps to create a new FM in a CM :

1. Define new opcodes
2. Write a function to implement the new opcode
3. Write a program to map opcodes to functions
4. Create a shared library on UNIX i.e. ".so" file
5. Configure the new FM as part of the CM

1. Defining new opcodes

You must define your custom opcodes, with their numbers, in a header file and execute parse_custom_ops_fields.pl on the file. parse_custom_ops_fields.pl creates an extension to the pcm_tbls.c file. Client applications use pcm_tbls.c to map a field or opcode to its number.

Portal opcodes and their numbers are defined in the ops/*.h files in the <BRM_HOME>/include directory.
To pass new opcodes from a client application to a new FM, use the PCM_OP macro.

To define a new opcode:
  a). Create a header file and define your new opcodes by using this format:
      #define    opcode_name_1    opcode_number_1

      For example, you might create a header file named my_opcodes.h with these definitions :

      #define MY_OP_SET_AGE     100001
      #define MY_OP_SET_LANGUAGE  100002

       Important: Numbers upto 100000 are reserved for use by BRM.


  b). Run the parse_custom_ops_fields.pl perl script by using this syntax:

       parse_custom_ops_fields.pl -L language -I input -O output -P java_package

 c). For the applications written in PCM C or PCM COM, create an entry using the following format in the pin.conf each application :
      - - ops_fields_extension_file ops_flds_ext

      Where ops_flds_ext is the file name and location of the memory-mapped extension file that was created by the parse_custom_ops_fields.pl script.
       Make sure that you included your header file both in the application that is calling the opcode and in the custom FM.


2. Writing a function to implement a new opcode 

     To implement a new opcode in BRM, you have to write a new function that calls the base system opcodes to access the DM. The new function then becomes part of the new FM shared library in UNIX.

     The new function you are implementing should conform to the PCM_OP calling convention.
     Use the PCM_OP_* reference pages as checklists and templates to determine what your custom function must implement. Pay particular attention to the input and output flists.

Important If you are adding a new function in the fm_utils module that can be called outside the module, add a prototype of that function in the fm_utils.h

3. Creating an opcode-to-function mapping file 

    You create a configuration program fm_*_config.c to map an opcode name to the function that implements it. This configuration file is read when a dynamic library is created, and the mapping information is stored in it.  When a parent CM is inititalized, it configures the opcode-function pairs into itself, and each child CM inherits the same configuration as its parent CM.

   The configuration program contains an array of struct cm_fm_config for each opcode and its corresponding function and the config function at the end.
   For a definition of this struct (cm_fm_config), see the cm_fm.h file in the BRM_SDK_HOME/include directory.
   The following example shows an opcode-to-function configuration file.

Important Include you ".h" file with your new custom opcodes

#ifndef lint
static  char    Sccs_id[] = "@(#) fm_custom_config.c 1.0 24 May 2011 %";
#endif
#include <stdio.h> /* for FILE * in pcm.h */
#include "ops/base.h"
#include "pcm.h"
#include "cm_fm.h"
#include "ops/my_header.h"

/*******************************************************************
* Opcodes handled by this FM.
*******************************************************************/
struct cm_fm_config my_config[] = {
/* opcode as a u_int, function name (as a string) */
{ MY_FIRST_OPCODE , "op_my_opcode" },
{ 0, (char *)0 }
};

void * my_config_func()
{
return ((void *) (my_config));
}


When the CM gets a MY_FIRST_OPCODE opcode through the PCM_OP call from a client application, the CM looks up at this table and calls the op_cust_create_acct() function.


4. Adding a new FM module to the CM configuration file 

The configuration file contain the names of the shared libraries that implement the base and custom opcodes. It also contains the names of the corresponding configuration files that contain the opcode-to-function mappings.

Use the entries for the system FMs in the default CM configuration file pin.conf in the BRM_HOME/sys/cm as an example to add your custom FM entries. For example, the typical entries for custom FMs look like:

- cm fm_module BRM_HOME/lib/my_fm.so my_config - pin

In this example, I'm assuming that the new dynamic library that implements the new custom FM my_fm.so is copied to BRM_HOME/lib directory. "my_config" is the name of the configuration implementation that contains the name-to-function mapping of the new custom OpCode.

5. Compiling and linking a custom FM

Use the libraries in the Portal_SDK_home/lib for linking.
Each custom FM must be created as a shared library on UNIX