This chapter provides instructions for creating custom fields and storable classes using the Oracle Communications Billing and Revenue Management (BRM) Software Development Kit (SDK) opcodes and Storable Class Editor, part of Developer Center. It also provides information about some utilities you might need to use with Storable Class Editor.
This chapter provides instructions for:
Creating and deploying custom storable classes and fields.
Exporting storable classes to and from the BRM database.
BRM includes a large number of default fields and classes. You can create custom fields and storable classes to add new features and functionality. You can create subclasses of existing base classes as well as new base classes.
You create, modify, and delete storable classes by using the following:
Storable Class Editor, a part of Developer Center. See "About Storable Class Editor".
BRM SDK opcodes. See "About BRM SDK Opcodes".
For a description of the storable class structure and a list of predefined classes, see "Understanding Flists and Storable Classes".
You can create subclasses and fields by using Storable Class Editor. Storable Class Editor is part of Developer Center, a suite of applications for BRM developers. For Developer Center system requirements and installation instructions, see "About Developer Center".
Use Storable Class Editor to:
Define new base classes and add fields to them.
Create new subclasses and add fields to them.
Modify custom classes.
Add fields to custom classes.
Caution:
Do not modify or add fields to default classes, because it makes BRM behavior unpredictable. Instead, create a new subclass of a system-defined class. The new subclass inherits all the fields of its parent and can be modified to meet your needs.Storable Class Editor compiles field and class definitions as you define them, helping to prevent syntax errors in your data. In addition, Storable Class Editor updates your database table definitions and modifies SQL mapping information for the classes you create.
To start Storable Class Editor:
Start Developer Center and log in to the database you want to use.
See "About Developer Center" for instructions.
Click the Storable Class Editor toolbar button or choose Tools - Storable Class Editor.
To create, edit, and delete fields and custom storable classes, first determine the data that you want them to contain. You then enter the information into Storable Class Editor, using BRM conventions for naming and formatting.
To manage field and storable class specifications in Storable Class Editor:
Enable changes to the data dictionary. See "Modifying the pin.conf File to Enable Changes".
Create your custom fields. See "Creating Custom Fields".
Create your custom storable classes. See "Creating Custom Storable Classes".
Make your custom fields and storable classes available to BRM by generating source and header files. See "Making Custom Fields Available to Your Applications".
For more information, see "About Defining Storable Classes" and "Class Naming and Formatting Conventions".
Before you can add or change fields and storable classes, you must make the data dictionary writable by editing the Data Manager (DM) configuration (pin.conf) file.
To make the data dictionary writable, perform the following for each database in your system:
Open the Oracle DM configuration file (BRM_Home/sys/dm_oracle/pin.conf) in a text editor. (BRM_Home is the directory in which you installed BRM components.)
To enable field creation in the data dictionary, set the following entry to 1:
- dm dd_write_enable_fields 1
To enable the creation, editing, or deletion of custom storable classes in the data dictionary, set the following entry to 1:
- dm dd_write_enable_objects 1
If your data dictionary contains a lot of data, you might need to increase the space allocated to it in the CM cache.
To increase the size of the CM cache for the data dictionary:
Open the Connection Manager (CM) configuration file (BRM_Home/sys/cm/pin.conf).
Increase the cache_size in the following entries:
- cm_cache cm_data_dictionary_cache number_of_entries, cache_size, hash_size - cm_cache fm_utils_data_dictionary_cache number_of_entries, cache_size, hash_size
Save the file.
Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
You can configure the DM to execute Data Definition Language (DDL) when updating object types in the data dictionary tables. This ensures that database objects are mapped to the correct tables.
To specify whether DDL is used when updating the data dictionary tables:
Open the Oracle DM configuration file (BRM_Home/sys/dm_oracle/pin.conf) in a text editor.
Set the sm_oracle_ddl entry to one of the following:
0 to not execute DDLs when updating object types in the data dictionary.
1 to execute DDLs when updating object types in the data dictionary.
- dm sm_oracle_ddl 1
Save and close the file.
When you create a new field in Storable Class Editor, it is committed to the data dictionary when you click OK in the New Field dialog box. You can't delete a field after it has been committed. For more information, see Storable Class Editor Help.
In Storable Class Editor, choose File - New - Field.
In the Field Name box, enter a unique name for the new field.
In the Type list, choose a field type in the list.
(Optional) In the Description box, enter text to define the purpose of the field.
(Optional) In the Field ID field, change the automatically assigned ID number.
The following table lists the field ID ranges for Oracle-only use and for customer use:
Click OK to add the field to the data dictionary.
You can create custom base classes and subclasses. Classes are not saved to the data dictionary until you commit them. For more information, see Storable Class Editor Help.
Caution:
When you create a subclass, the total number of tables for the parent class and its subclasses cannot be greater than 64. For example, if you create tables for storable class /a and its subclasses /a/b and /a/b/c, the total number of tables for all three storable classes must be less than or equal to 64:/a tables + /a/b tables + /a/b/c tables <= 64 tables
In Storable Class Editor, choose File - New - Class.
In the Class Name field, enter the class name in the format /classname for base classes and /classname/subclass for subclasses.
(Optional) In the Label field, enter a name for the storable class.
(Optional) In the Description field, enter text to define the purpose of the storable class.
(Optional; base classes only) In the Sequence Start field, enter a number to designate how objects in this class should be numbered.
(Optional; base classes only) In the Table Name field, optionally change the default SQL table name suggested by Storable Class Editor. You should accept the default table name unless your business logic requires you to change it.
(Optional; base classes only) In the Storage Specifications field, enter storage specifications for the database you are using.
For Oracle databases, parameters include tablespace, and initial extent size. See "Database Configuration and Tuning" in BRM Installation Guide.
Click OK.
The storable class opens in a Class Definition window. The class name appears in the title bar.
Select the root icon of the new class.
In the Properties window, choose values for the Read Access and Write Access properties.
Add fields to the class by dragging field icons from the Class Browser or Field Browser.
Note:
Each storable class must have the PIN_FLD_ACCOUNT_OBJ field. If you do not include this field, it is automatically inserted when the storable class is created.Choose File - Commit New Class to commit the class to the data dictionary.
If you created a new subclass and if the base class is partitioned, you must run the partition_utils script with the -n parameter to ensure that the new subclass uses the same partitioning layout as its base class.
See "Partitioning Tables" in BRM System Administrator's Guide.
After you create custom fields and classes, you must make them available to applications. The first step is to use Storable Class Editor to create Java source files and a C header file. The steps that follow depend on whether your applications are written in C or Java. For more information about using custom fields in Java applications, see "Using Custom Fields in Java Applications".
Note:
Developer Center is a Java application. To ensure that custom fields are displayed properly in flists in Object Browser and Opcode Workbench, you must follow the procedures for making fields available to Java applications.In Storable Class Editor, choose File - Generate Custom Fields Source to create source files for your custom fields. See the Storable Class Editor Help system for detailed instructions.
Storable Class Editor creates a C header file called cust_flds.h, a Java properties file called InfranetPropertiesAdditions.properties, and a Java source file for each custom field.
For applications written in PCM C or PCM C++, perform these steps:
Run the parse_custom_ops_fields.pl Perl script on the cust_flds.h file created by Storable Class Editor. Use this syntax:
parse_custom_ops_fields -L language -I input -O output
For information on the parameters of parse_custom_ops_fields and their valid values, see "parse_custom_ops_fields".
In the pin.conf file for applications that need to access these fields, including testnap and other utilities, create an entry using the format shown below. Replace cust_flds with the file name and location of the memory-mapped extension file that the parse_custom_ops_fields script created.
- - ops_fields_extension_file cust_flds
Note:
Do not add more than one ops_fields_extension_file entry. The custom fields source file and the extension file that results from it contain information about all the custom fields in the data dictionary, so a single reference to that file is sufficient.Include the cust_flds.h header file in the applications and in the FMs that use the fields.
Note:
Default BRM fields are defined with their numbers in the pin_flds.h file in the BRM_Home/include directory. While it is possible to add custom fields directly to pin_flds.h, you should not do so. Placing custom field definitions in the separate cust_flds.h file allows you to upgrade to new releases without having to edit pin_flds.h.For applications written using Java PCM, including Developer Center, perform these steps:
Copy the contents of the InfranetPropertiesAdditions.properties file and paste it in the Infranet.properties file for your application.
Compile the source files you created in step 1.
(Optional) Jar the compiled classes.
In the CLASSPATH, add the location of the JAR files or compiled Java classes.
The BRM SDK opcodes allows you to create, modify, delete, or retrieve storable class and field specifications without the use of BRM Storable Class Editor.
For information about BRM SDK, see "About BRM SDK".
To manage field and storable class specifications with BRM SDK opcodes:
Enable changes to the data dictionary. See "Modifying the pin.conf File to Enable Changes".
Create, edit, or delete your custom fields. See "Using BRM SDK Opcodes to Manage Storable Classes".
Create, edit, or delete your custom storable classes. See "Using BRM SDK Opcodes to Manage Field Specifications".
Make your custom fields and storable classes available to BRM by generating source and header files. See "Making Custom Fields Available to Your Applications".
Use the following BRM SDK opcodes to manage storable class specifications:
To create or modify a storable class specification, use PCM_OP_SDK_SET_OBJ_SPECS. See "Creating and Modifying Storable Classes".
To retrieve a storable class specification, use PCM_OP_SDK_GET_OBJ_SPECS. See "Retrieving Storable Class Specifications".
To delete a storable class specification, use PCM_OP_SDK_DEL_OBJ_SPECS. See "Deleting Storable Class Specifications".
Use the PCM_OP_SDK_SET_OBJ_SPECS opcode to create or modify a storable class. This opcode creates or modifies storable classes in the data dictionary of all databases in your BRM system.
Caution:
If you change a storable class after it has been instanced and populated with data, you will corrupt your database.Important:
Instead of using this opcode, it's safer and more reliable to create or modify storable class specifications by using the Storable Class Editor in Developer Center.PCM_OP_SDK_SET_OBJ_SPECS takes the following as input:
POID
Class name
Class type
Note:
The Portal object ID (POID) is the only mandatory field on the input flist. However, to create a class specification, you must at least specify the class name and type. To specify fields for the storable class, add a PIN_FLD_OBJ_ELEM array for each field.If the transaction is successful, PCM_OP_SDK_SET_OBJ_SPECS returns these values:
The POID of the newly created or modified storable class.
A results array containing an SQL description of any table changes, with one array for each change.
Use the PCM_OP_SDK_GET_OBJ_SPECS opcode to retrieve one or more storable class specifications. This opcode retrieves all class specifications specified on the input flist. When no classes are specified, this opcode returns all class specifications in the BRM database.
Note:
You can retrieve specific levels or types of objects by using the * wildcard character.PCM_OP_SDK_GET_OBJ_SPECS returns the following, depending on the success of the transaction:
When successful, this opcode returns specifications for the specified storable classes, or all class specifications if the input flist doesn't specify a class.
When the opcode doesn't exist in the database, the opcode returns PIN_ERR_BAD_ARG.
Use the PCM_OP_SDK_DEL_OBJ_SPECS opcode to delete storable class specifications from the data dictionary of all databases in your BRM system.
Note:
The opcode deletes data from the data dictionary only. To drop the actual table that was created by PCM_OP_SDK_SET_OBJ_SPECS, you must drop it manually.Caution:
If you delete a storable class that has already been instantiated, you will corrupt your database. For example, never delete the /account object. Because of this danger, we recommend that you do not use this opcode on a production system.PCM_OP_SDK_DEL_OBJ_SPECS returns the following, depending on the success of the transaction:
When the storable class doesn't exist, the opcode returns PIN_ERR_BAD_ARG_EBUF.
When successful, the opcode returns these values:
The POID of the deleted object.
A results array containing an SQL description of any table changes; one array for each change.
Use the following BRM SDK opcodes to manage field specifications:
To create or modify a field specification, use PCM_OP_SDK_SET_FLD_SPECS. See "Creating and Modifying Field Specifications".
To retrieve a field specification, use PCM_OP_SDK_GET_FLD_SPECS. See "Retrieving Field Specifications".
To delete a field specification, use PCM_OP_SDK_DEL_FLD_SPECS. See "Deleting Field Specifications".
Use the PCM_OP_SDK_SET_FLD_SPECS opcode to create or modify field specifications. This opcode creates or modifies the specified field specifications in the data dictionary of all databases in your BRM system.
Caution:
If you change specifications for fields that have already been instantiated, you will corrupt your database.PCM_OP_SDK_SET_FLD_SPECS takes the following as input:
Partial POID (database number plus /dd/fields)
Field name
Field type
Note:
The POID is the only mandatory field on the input flist. However, to implement the field, you must at least specify the field name and type.PCM_OP_SDK_SET_FLD_SPECS returns the following, depending on the success of the transaction:
If successful, the opcode returns the POID of the created or modified data dictionary field.
If the opcode cannot create or modify the field, the opcode returns the field's POID, along with the PIN_FLD_ACTION field set to NOOP.
Use the PCM_OP_SDK_GET_FLD_SPECS opcode to retrieve one or more field specifications. This opcode retrieves all field specifications specified on the input flist. When no fields are specified, this opcode returns all field specifications in the BRM database.
Important:
Returning all field specifications can take a long time.Use the PCM_OP_SDK_DEL_FLD_SPECS opcode to delete field specifications. This opcode deletes the specified field specification from the data dictionary of all databases in your BRM system.
Caution:
If you delete specifications for fields that have already been instantiated, you will corrupt your database. For example, never delete PIN_FLD_POID from a base BRM system. Because of this danger, we recommend that you do not use this opcode on a production system.PCM_OP_SDK_DEL_FLD_SPECS takes the following as input:
Partial POID (database number plus /dd/fields)
Name of the field to delete
If successful, this opcode returns the POID of the deleted field specification.
If you used Developer Workshop in the past to create storable classes, you may have saved storable class definitions as files in .PSC format. If you want to use these files in Storable Class Editor, you must convert them to .SCE format before you can open them. (See Storable Class Editor Help for instructions about opening storable class files.)
You use the PSC Converter application to convert files. This application is installed along with the rest of Developer Center. See "Installing Developer Center".
From the start options, choose PSC to SCE Converter, which is under Portal.
Click the Select File button and navigate to the .PSC file you want to convert.
The Save As field automatically fills in the with the same path. The filename is changed to include the .SCE extension. (If a .SCE file of that name already exists, the Save As field is left blank. Enter a different path and filename or click New File to choose an existing file to overwrite.)
Click Convert.
A dialog box confirms the creation of the new .SCE file.
You deploy your custom fields and storable classes by using the pin_deploy command-line utility. The pin_deploy utility exports and imports field and storable class definitions from one BRM database to another, such as from your development environment to your production environment.
The pin_deploy utility is available on all BRM platforms, can be scripted, and can use stdin and stdout. It has several modes of operation to ensure atomic operations and consistency. pin_deploy provides the following advantages:
Streamlines the process of putting all storable class and field definitions into source code management
Enables you to print out a storable class or field definition for review
Reduces the possibility of damaging the BRM production database data dictionary
The pin_deploy utility uses PODL (Portal Object Definition Language) to export and import field and storable class definitions. PODL is a text-based definition language that represents fields and storable classes. Using this language, pin_deploy can:
Extract storable class and field definitions from any BRM database on any platform and produce a human-readable PODL file.
Read PODL files and use the files to load storable class and field definitions into any BRM server on any platform.
You can use the following command-line options in pin_deploy:
field extracts field definitions.
class extracts storable class definitions.
verify connects to BRM database, accepts PODL commands, determines what changes would be made, and reports back any conflicts.
create connects to a BRM database, attempts to create storable classes and fields according to PODL, succeeds if there are no conflicts, or reports conflicts.
replace connects to a BRM server; attempts to create storable classes and fields according to PODL, and succeeds even if there are conflicts. It overwrites and replaces any classes that are already present.
In all cases, the entire PODL file is imported. If the entire file cannot be loaded correctly, nothing from the file is loaded. For example, if a storable class is loaded that includes custom fields, those custom fields must exist in the data dictionary or in the PODL file for the class to load.
Important:
Before you deploy your custom classes and fields, verify that you have enough space in the BRM database for the new storable classes. If you run out of space during deployment, the new storable classes might be in an inconsistent state.See the pin_deploy description for more information and a complete list of options.
To extract field definitions, enter a command with the following syntax:
% pin_deploy field [-cp] [field_name1] [field_name2]
To extract storable class definitions, use the following syntax:
% pin_deploy class [-smncp] [class_name1] [class_name2]
To import storable class definitions into a BRM database, you must use PODL files that include the interface and corresponding implementation definitions.
Important:
The pin_deploy utility cannot determine the space requirement in the BRM database. If you run out of disk space before the deployment is complete, you need to manually drop the tables that were created, make more space, and try again.Add up the implementation definitions (for example, initial clause) of the PODL files you want to import to verify that you have enough disk space.
These lines start with this text:
SQL_STORAGE =
Run pin_deploy in the verify mode to determine the changes that will be caused by importing new field and storable class definitions and to verify that there are no conflicts.
% pin_deploy verify [file_name1] [file_name2]
To commit new definitions to BRM, run pin_deploy in one of the following modes.
create – preserves old storable class and field definitions that conflict with new ones
replace – copies all storable class and field definitions, including those that conflict with old definitions
% pin_deploy replace [file_name1][file_name2]
Many BRM features use /config objects to store business configuration information in the database. For example, /config/paymenttool defines the batch types and optional fields displayed in the Payment Tool while /config/device_permit_map maps relationships between device types and services.
In some cases, you may to need to add or replace fields in /config objects. For example, you may need to add or replace events in the /config/adjustment/event object to add to the list of events you can adjust in the Event Browser.
You can use either Developer Center or testnap to make changes to /config objects. The general procedure is to display the current contents of the object, write an flist that contains the fields you want to add, and then write the flist to the object.
The following two sections provide examples for both Developer Center and testnap. Depending on the nature of the /config object, the exact procedure you use may be different from the examples.
This example demonstrates adding a new event field to /config/adjustment/event using Developer Center. See "About Developer Center" for general instructions and information.
Start Developer Center.
Open the Object Browser.
Enter or choose /config/adjustment/event in the Objects field, then click Browse.
The /config/adjustment/event object is displayed in the Objects area and the contents of the object are displayed in the Output Flist area.
Select and copy the last element in the PIN_FLD_EVENTS array, located at the end of the output flist. It should be similar to the following:
0 PIN_FLD_EVENTS ARRAY [9] allocated 20, used 1 1 PIN_FLD_TYPE_STR STR [0] "/event/session"
Switch to Opcode Workbench.
Enter or choose PCM_OP_WRITE_FIELDS in the Opcode field.
Enter 32 in the Flags field to specify the PCM_OPFLG_ADD_ENTRY flag. This flag makes it possible to add a new element to the array.
In the Input Flist area, enter the first line of the input flist as shown below. If necessary, modify the database number.
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/adjustment/event 301
Paste the text you copied in Object Browser onto the next line. The result should be similar to the following:
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/adjustment/event 301 0 PIN_FLD_EVENTS ARRAY [9] allocated 20, used 1 1 PIN_FLD_TYPE_STR STR [0] "/event/session"
Increment the element number by one. For example, if the element number you pasted is [9], change it to [10].
Change the event class name in the PIN_FLD_TYPE_STR field to that of the event type you are adding. For example, if the event type you pasted was /event/session, you could change it to /event/session/call/telephony.
Click Run.
The Output Flist area displays the object POID to confirm that the opcode ran successfully.
Switch to Object Browser, then repeat step 3 to confirm that the new event type has been added.
Stop and restart the CM.
This example demonstrates replacing an event field in /config/adjust/event using testnap. See "Using testnap" for general instructions and examples for testnap.
Start testnap.
% testnap
Use the robj command to view the contents of the /config object you want to modify.
This robj command reads the contents of the /config/adjust/event object.
robj - 0.0.0.1 /config/adjustment/event 301
When the object is displayed, note the element ID of the field that you want to replace in the PIN_FLD_EVENTS array.
Create a text file that contains an flist with the field that you want to add. The field must contain the complete POID of the /config object as well as the element you are adding. Set the element ID to the number of the element you are replacing.
For example, this flist replaces element [5] in the PIN_FLD_EVENTS array in /config/adjustment/event.
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/adjustment/event 301 0 0 PIN_FLD_EVENTS ARRAY [5] allocated 20, used 1 1 PIN_FLD_TYPE_STR STR [0] "/event/session"
Save this file.
Read the file into buffer 1. In this example, the file is called config.
r config1 1
Display the contents of the buffer to verify that it is correct.
d 1
Write the contents of the buffer to the /config object.
wflds 1
Read the object again to verify that your change was made.
robj - 0.0.0.1 /config/adjustment/event 301
Stop and restart the CM.