This chapter provides reference information for Oracle Communications Billing and Revenue Management (BRM) developer utilities.
Use this utility to load the contents of XML configuration files into configuration (/config/*) objects in the BRM database.
Important:
To connect to the BRM database, this utility needs a configuration (pin.conf) file in the directory from which it is run. For information about creating configuration files for BRM utilities, see "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.Before loading the contents of a file, the utility validates the contents against the file's XML schema definition (XSD). To do this, the utility needs the following entries in its pin.conf file:
Table 45-1 load_config pin.conf Entries Required for XML Validation
XML File to Validate | Required pin.conf Entry |
---|---|
config_lifecycle_states.xml |
- load_config validation_module libLoadValidSLM LoadValidSLM_init |
config_service_state_map.xml |
- load_config validation_module libLoadValidSLM LoadValidSLM_init |
config_subscriber_preferences_map.xml |
- load_config validation_module libLoadValidTCFAAA LoadValidTelcoAAA_init |
config_collections_scenario_params.xml |
- load_config validation_module libLoadValidCollections LoadValidCollections_init |
The location of the XSD must be specified in the XML file. If the contents do not conform to the XSD, the load operation fails.
After validating the XML contents against the XSD, the utility converts the XML file into one or more configuration objects, depending on the structure of the XML file.
If any syntax errors occur, the load operation fails.
Note:
You can load separate configuration objects for each brand by setting the user in the utility's pin.conf file to the appropriate brand.BRM_Home/apps/load_config
where BRM_Home is the directory in which you installed BRM components.
Creates a log file for debugging purposes. Use this parameter for debugging when the utility appears to have run with no errors but the configuration objects have not been loaded into the database.
Displays syntax and parameters for the utility.
Lists all validated configuration objects in the BRM database that are associated with config_file.
Creates a configuration object when a validation library is not loaded. Use this parameter to skip the validation and to load the contents of the XML file into the database schema when the corresponding validation library is not loaded. When the library is loaded, validation happens irrespective of whether this parameter is passed or not.In the absence of the validation library and this parameter, the utility returns an error and exits.
Deletes all instances of the specified class from the BRM database.
To specify the class, do not include /config/. For example, to specify the /config/lifecycle_states class, enter lifecycle_states.
Runs the utility in test mode to validate the XML file against its XML schema definition. This parameter does not load data into a configuration object or overwrite any existing data in the objects.
Tip:
To avoid load errors based on XML content problems, run the utility with this option before loading data into the object.Validates configuration objects in the BRM database that are associated with config_file.
Displays information about successful or failed processing as the utility runs.
Writes information from all objects of the specified class in the database to config_file.
To specify the class, do not include /config/. For example, to specify the /config/lifecycle_states class, enter lifecycle_states.
This parameter can be used to copy configuration data from one system to another. The generated XML does not conform to a particular XSD. Before loading the contents of config_file into another database schema, you must associate it with an XSD that defines the appropriate format.
The XML file for which the utility performs one of the following actions:
Loads the file's contents into the database schema
Loads information from objects in the database schema into the file
This must be the last parameter listed on the command line.
If the XML file is in the same directory from which you run the utility, specify only the file name. If it is in a different directory, include the entire path for the file.
If the utility does not notify you that it was successful, look in the default.pinlog file to find any errors. This log file is either in the directory from which the utility was run or in a directory specified in the utility's configuration file.
To verify that the configuration information was loaded, display the configuration objects by using one of the following features:
Object Browser
testnap utility's robj command
See "Reading an Object and Writing Its Contents to a File" for more information.
Important:
You must stop and restart the Connection Manager (CM) to make new service life cycle and service state mapping data available.See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
Use the load_config_provisioning_tags utility to load provisioning tags into the /config/provisioning_tag object in the BRM database. You define provisioning tags in the pin_config_provisioning_tags.xml file in BRM_Home/sys/data/config.
Use this utility when you create provisioning tags using the provisioning tag framework.
For information about creating provisioning tags, see "Working with Provisioning Tags" in BRM Setting Up Pricing and Rating.
For information about the syntax of the XML file, see "Configuring Provisioning Tags" in BRM Setting Up Pricing and Rating.
Caution:
The load_config_provisioning_tags utility overwrites existing instances of the /config/provisioning_tag object. If you are updating provisioning tags, you cannot load new or changed tags only. You must load the complete set of provisioning tags each time you run the load_config_provisioning_tags utility.When you run this utility, the pin_config_provisioning_tags.xml and business_configuration.xsd files must be in the same directory. By default, both files are in BRM_Home/sys/data/config.
Important:
To connect to the BRM database, the load_config_provisioning_tags utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.Creates a log file for debugging purposes. Use this parameter for debugging when the utility appears to have run with no errors, but the data has not been loaded into the database.
Displays information about successful or failed processing as the utility runs.
load_pin_config_provisioning_tags any_other_parameter –v > filename.log
Runs the utility in test mode to validate the XML file. This parameter does not create, modify, or delete any entries in the /config/provisioning_tag object.
Tip:
To avoid load errors based on XML content problems, run the utility with this option before loading data into the database.Displays help information for using this utility.
The name and location of the file that defines provisioning tags. The default pin_config_provisioning_tags.xml file is in BRM_Home/sys/data/config. The utility can take any XML file name as a parameter if the file's contents conform to the appropriate schema definition.
Important:
The file must be in the same directory as the business_configuration.xsd file.If you do not run the utility from the directory in which the file is located, you must include the complete path to the file, for example:
load_config_provisioning_tags BRM_Home/sys/data/config/pin_config_provisioning_tags.xml
The utility validates the XML file against rules defined in the business_configuration.xsd file. This file resides in the BRM_Home/sys/data/config directory.
The utility validates the following:
The service name length is from 1 to 1,023 characters.
The service names listed in the file are unique.
If load_config_provisioning_tags does not notify you that it was successful, look in the log file (normally default.pinlog) for error messages. The log file is located in the directory from which the utility was started or in a directory specified in the pin.conf configuration file.
To verify that the objects were loaded, you can display the /config/provisioning_tag object by using the Object Browser, or use the robj command with the testnap utility. See "Reading an Object and Fields".
Important:
You must restart the Connection Manager (CM) to make new provisioning tags available. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.Use this utility to load localized strings into the BRM database. This utility reads localized strings from various customizable files and stores them as /strings objects in the BRM database. These files include error code files, locale description files, reason code files, and a variety of other files.
Important:
Use only one locale for each type of file.For information on modifying and loading localized string files, see "Localizing and Customizing Strings".
Note:
You cannot load separate /config/map_glid objects for each brand. All brands use the same object.Caution:
When loading reason codes from the reasons.locale file, load_localized_strings also loads information from this file into the /config/map_glid object. If customized to specify services and event types for event-level adjustments, the utility also loads information into the /config/reason_code_scope object. While the utility doesn't overwrite existing strings in the /strings object unless you direct it to, it does overwrite the /config/reason_code_scope and /config/map_glid objects.Important:
To connect to the BRM database, the load_localized_strings utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.Displays information about successful or failed processing as the utility runs.
load_localized_strings any_other_parameter –v > filename.log
Forces strings to be stored in the BRM database, overwriting localized strings with the same IDs. If you do not use -f, string objects are not stored when localized strings with the same IDs already exist.
Note:
This parameter has no effect on either the /config/reason_code_scope or /config/map_glid object. These objects are always completely overwritten by the utility.Displays help about using the load_localized_strings utility.
The name and location of the file that contains the localized strings.
For sample BRM files errors, locale_desc, and reasons, see "Sample Files".
locale is the BRM locale, based on ISO-639 and ISO-3166 standards. See "Locale Names".
Tip:
If you copy the filename.locale file to the same directory from which you run the load_localized_strings utility, you do not have to specify the path or the file name.If the load_localized_strings utility doesn't notify you that it was successful, look in the load_localized_strings.log file to find any errors. The log file is either in the directory from which the utility was started, or in a directory specified in the configuration file.
Use the following American English files as examples of how to set up localized or customized error message, locale description, and reason code files. The following files are loaded into the BRM database when you install BRM:
errors.en_US in BRM_Home/sys/msgs/errorcodes
locale_descr.en_US in BRM_Home/sys/msgs/localedescr
reasons.en_US in BRM_Home/sys/msgs/reasoncodes
For information on other sample files you can localize or customize, see "Localizing and Customizing Strings".
Customer Center and Self-Care Manager use business type definitions to display the appropriate entry fields for an account. For example, when a CSR selects File – New – Consumer, the Account Creation wizard only displays entries appropriate for a consumer. The wizard would not display the Company or Job title entry fields.
Using the load_pin_config_business_type Utility
Use this utility to load updates to the business types defined in the BRM_Home/data/config/pin_config_business_type file into the/config/business_type storable object in the BRM database. When you load new business type definitions, you overwrite the old /config/business_type object.
You must restart the Connection Manager (CM) after running this utility.
If an account is created outside of Customer Center, the default value for "Unknown business type" is used.
Note:
You cannot load separate /config/business_type objects for each brand. All brands use the same object.Important:
If /config/business_type isn't loaded, the value for PIN_FLD_BUSINESS_TYPE included in the/account object at account creation must either be zero or not included in the input flist. Otherwise, PCM_OP_CUST_POL_VALID_BILLINFO returns a validation error.Examples of Business Type Definitions
You can append your own business type definitions to the end of the list of definitions provided in pin_config_business_type, or create a new definition file. The file must include a 0 "Unknown business type" entry. Keep the current entries of 1 "Consumer" and 2 "Business" in place and append your new entry after them.
The format for each entry is an integer value plus an associated quoted string with a semicolon at the end of the statement. The length of the string is limited to 1024 characters. Multi-line string entries are valid as long as there is a closing quote before the carriage return and an opening quote on the following line, for example:
0 "Unknown business type"; 1 "Consumer"; 2 "Business"; 3 "This is a valid quoted string entry " "that spans more than one line";
There can be only one quoted string associated with each integer. The string description is not used for validation, but provides a way to record the meaning of each integer value.
To add a business type definition, use a text editor to open the pin_config_business_type file and follow the guidelines provided in the comment section to add your new value to the end of the existing definitions. For example, for an employee account, you might want the Account Creation wizard to display a field for the CSR to enter an employee ID number. To add the new value to the/config/business_type object for an employee business type, add it to the end of the existing definitions in the pin_config_business_type file:
0 "Unknown business type";
1 "Consumer";
2 "Business";
3 "Employee";
Writes error information for debugging purposes to the utility log file. By default, the file is located in the same directory as the utility and is called default.pinlog. You can specify a different name and location in the Infranet.properties file.
Displays information about successful or failed processing as the utility runs.
Displays the syntax and parameters for this utility.
The file containing the business type definitions, typically, BRM_Home/data/config/pin_config_business_type.
Table 45-2 lists the possible completion values this utility returns. The returned value is saved in the default.pinlog file:
Table 45-2 load_pin_config_business_type Returned Values
Value | Description |
---|---|
0 |
success |
1 |
bad flag |
2 |
error parsing input file (default is pin_config_business_type) |
3 |
error opening PCM connection |
4 |
error opening transaction |
5 |
error deleting old /config/business_type object |
6 |
error creating new /config/business_type object |
7 |
error committing transaction |
Use this utility to load device-to-service mapping information into the BRM database.
You use a mapping file to define which service types can be associated with a particular device type. A sample file is provided as BRM_Home/sys/data/config/pin_device_permit_map. Each mapping file contains information about one device type in one brand.
Note:
This utility is brand-aware. You can load separate /config/device_permit_map objects for each brand.After defining device-to-service mappings, you use the load_pin_device_permit_map utility to load the mapping data into a /config/device_permit_map object. Each /config/device_permit_map object contains mapping information for all the device types in one brand.
Note:
You must load the mapping data into the database and restart the CM before you can use device management features. Because device management configuration data is always customized, it is not loaded during BRM installation.You must load device-to-service mapping information for each unique combination of device type and brand. For example, if the same device type exists in several different brands, you must load mapping information for that device type into the /config/device_permit_map object for each brand.
If the mapping definitions are the same for all brands or if you are not using branding, you can create a single /config/device_permit_map object by using the root login when you run load_pin_device_permit_map. The device management opcodes automatically check the /config/device_permit_map object associated with root if they can't find an object associated with a device's brand. See "Device Management and Brands" for more information.
The mapping information you load into a /config/device_permit_map object gets its brand association from the BRM login specified in the configuration file used with load_pin_device_permit_map. So when you load mapping information for a device type in a particular brand, you must edit the configuration file to use a login associated with that brand. See "Running Utilities with a Branded Database" in BRM Managing Customers.
The load_pin_device_permit_map utility shares a configuration file with the load_pin_device_state utility. This file is generated during installation and is located in BRM_Home/apps/device_management/Infranet.properties.
See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide for more information about configuration files.
Displays information about successful or failed processing as the utility runs.
Writes error information for debugging purposes to the utility log file. By default, the file is located in the same directory as the utility and is called default.pinlog. You can specify a different name and location in the Infranet.properties file.
The name and location of the file that contains the device-to-service mapping data. A sample file is supplied as BRM_Home/sys/data/config/pin_device_permit_map. You can modify this file or create a new one.
The file includes lines specifying the device type (such as /device/voucher) and the service types (such as /service/telco/gsm/telephony) that can be associated with it. In this example, four service types can be associated with /device/voucher.
/device/voucher :/service/telco/gsm/telephony :/service/telco/gsm/sms :/service/telco/gsm/fax :/service/telco/gsm/data
The sample file includes additional information about the correct syntax for entries.
If the load_pin_device_permit_map utility does not notify you that it was successful, look in the log file (normally default.pinlog) for error messages. The log file is located in the directory from which the utility was started, or in a directory specified in the Infranet.properties configuration file.
Use this utility to load state-change definitions for devices into the BRM database.
You use a state change definition file to define, which state changes are valid and which policy opcodes to call for each state change. A sample file is provided as BRM_Home/sys/data/config/pin_device_state.
Note:
This utility is brand-aware. You can load separate /config/device_state/apn objects for each brand.After defining the state changes, you run the load_pin_device_state utility to load the definitions into the database as a /config/device_state object.
Note:
You must load the state change definitions into the database and restart the Connection Manager before you can use device management features. Because device management configuration data is always customized, it is not loaded during BRM installation.Because /config/device_state objects are brand aware, you load an object for each unique combination of device type and brand. For example, if you have two device types (A and B) that are offered by two brands (1 and 2) and a third device type (C) that is offered only by Brand 1, you load /config/device_state objects for these five combinations: A1, A2, B1, B2, and C1.
If you aren't using branding or if the state change definitions for a device type are the same for all brands, you can create a single /config/device_state object for that device type by using the root login. The device management opcodes automatically check the /config/device_state object associated with root if they can't find an object associated with a device's brand.
/config/device_state objects get their brand associations from the BRM login used to create them. So in the scenario mentioned above, you would need to use two different logins (for Brands 1 and 2) to create /config/device_state objects for the three device types. See "Running Utilities with a Branded Database" in BRM Managing Customers.
The load_pin_device_state utility shares a configuration file with the load_pin_device_permit_map utility. This file is generated during installation and is located in BRM_Home/apps/device_management/Infranet.properties.
When you enter state change information into the state change definition file, you must refer to the localized text strings that describe the valid states for a particular device type. You must define these text strings and load them into the database by using the load_localized_strings utility. A sample localized strings file for device states is located in BRM_Home/sys/msgs/device_states/device_states.en-US.
Displays information about successful or failed processing as the utility runs.
Writes error information for debugging purposes to the utility log file. By default, the file is located in the same directory as the utility and is called default.pinlog. You can specify a different name and location in the Infranet.properties file.
The name and location of the state change definitions file, where device represents the device type. For example, the default file for Number Management is pin_device_state_num. Each device type must have its own file.
A sample state change definition file is provided in BRM_Home/sys/data/config/pin_device_state.
Use this syntax for entries:
storable_object_type device_type state_id: state_type: strid_id: string_ver:opcode_num:flags next_id1: opcode_num1:flags1 next_id2: opcode_num2:flags2
storable_object_type
A subclass of /config/device_state, for example /config/device_state/sim. The storable object type must be the first non-comment line in the file. Only one storable object type can be specified.
device_type
The device type, for example /device/sim. The device type must be the second non-comment line in the file. Only one device type can be specified.
state_id
An integer state ID, such as 0, 1, 2, and so on. State IDs can be freely assigned, except for 0, which is reserved for the Raw state.
state_type
An integer representing the state type to which state_id belongs. The state type determines the valid behaviors of states of that type. There are four possible values:
0 (RAW): Includes the state that marks the beginning of the device life cycle. Only one state can be of this type. States of type RAW can transition only to states of type INIT. Device objects cannot be saved in the Raw state.
1 (INIT): Includes all the states in which the device can be saved immediately after its creation. States of type INIT can transition to states of type INIT, NORMAL, or END.
2 (NORMAL): Includes all the working states between INIT and END. States of type NORMAL can transition to INIT states, other NORMAL states, and END states.
3 (END): Includes all the terminal states of the life cycle. Devices cannot be transitioned from states of this type.
str_id
ID of the state's localized text string in /string. You must load these text strings into the database by using a text file and the load_localized_strings utility.
str_version
Version number of the state's localized text string in /string.
opcode_num
The opcode number of the first policy opcode to be called during a transition from state_id. Device opcode numbers are specified in the device.h file. This file is located in BRM_Home/include/ops directory.
flags
Flags to be used when calling the opcode specified by opcode_num. Flags are listed in the pin_device.h file and explained in the opcode documentation.
next_idx
An integer state ID that specifies a device state to which state_id can transition. Any integer value is allowed except 0, which is reserved for the Raw state.
opcode_numx
Specifies the policy opcode called just after the state change to next_idx is complete. Device opcode numbers are specified in the device.h file. This file is located in BRM_Home/include/ops directory.
flagsx
Flags to be used when calling the opcode specified by the matching opcode_numx. Flags are listed in the pin_device.h file and explained in the opcode documentation.
The sample state change definitions file includes additional information about the correct syntax for entries. Its location is BRM_Home/sys/data/config/pin_device_state.
If the load_pin_device_state utility doesn't notify you that it was successful, look in the log file (normally default.pinlog) for error messages. The log file is located in the directory from which the utility was started, or in a directory specified in the Infranet.properties configuration file.
The utility fails if it detects duplicate state IDs in the state change definitions file. It also fails if the file contains more than one storable object or device type entry.
Use this utility to load a list of service types that identify users through alias names rather than service logins. See "Improving Search Performance for Prepaid Services" in BRM Telco Integration.
You specify which service types identify users through alias names in the BRM_Home/sys/data/config/pin_excluded_logins.xml file. You then load the file into the /config/login_exclusion object in the BRM database.
When you run the utility, the pin_excluded_logins.xml and business_configuration.xsd files must be in the same directory. By default, both files are in BRM_Home/sys/data/config.
After running this utility, you must stop and restart the Connection Manager (CM). See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
Note:
You cannot load separate /config/login_exclusion objects for each brand. All brands use the same object.Important:
To connect to the BRM database, the load_pin_excluded_logins utility needs a configuration file in the directory from which it is run. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.Displays information about successful or failed processing as the utility runs.
Creates a log file for debugging purposes. Use this parameter for debugging when the utility seemed to run without error but the data was not loaded into the database.
Runs the utility in test mode to validate the XML file. This parameter does not create, modify, or delete any entries in the /config/login_exclusion object.
Tip:
To avoid load errors based on XML content problems, run the utility with this option before loading data into the database.Displays help information for using this utility.
The name and location of the XML file. The default XML file is BRM_Home/sys/data/config/pin_excluded_logins.xml, but the utility can take any XML file name as a parameter as long as the file's contents conform to the appropriate schema definition.
If you copy the file to the same directory from which you run the load utility, specify only the file name. If you run the command in a different directory from where the file is located, you must include the entire path for the file.
Important:
The file must be in the same directory as the business_configuration.xsd and pin_excluded_logins.xml files.The utility validates the XML file against rules defined in the pin_excluded_logins.xsd file. This file resides in the BRM_Home/sys/data/config directory, and you must point to it through a business_configuration.xsd file in the directory that contains your working XML file.
The utility validates the following:
The service name length is from 1 to 1,023 characters.
The service names listed in the file are unique.
Use this utility to load state-change definitions for orders into the BRM database.
You define which state changes are valid and which policy opcodes to call for each state change in a state change definition file. A sample file is provided as BRM_Home/sys/data/config/pin_order_state.
After defining the state changes, you use the load_pin_order_state utility to load the definitions into the database as a /config/order_state object.
Note:
This utility is brand-aware. You can load separate /config/order_state objects for each brand.Note:
You must load the state change definitions into the database and restart the CM before you can use order management features. Because order management configuration data is always customized, it is not loaded during BRM installation.Because /config/order_state objects are brand aware, you load an object for each unique combination of order type and brand. For example, if you have two order types (A and B) that occur in two brands (1 and 2) and a third order type (C) that occurs only in Brand 1, you load /config/order_state objects for these five combinations: A1, A2, B1, B2, and C1.
If you aren't using branding or if the state change definitions for a order type are the same for all brands, you can create a single /config/order_state object for that order type by using the root login. The order management opcodes automatically check the /config/order_state object associated with root if they can't find an object associated with an order's brand.
/config/order_state objects get their brand associations from the BRM login used to create them. So in the scenario mentioned in the previous paragraph, you would need to use two different logins (for Brands 1 and 2) to create /config/order_state objects for the three order types. See "Running Utilities with a Branded Database" in BRM Managing Customers.
When you enter state change information into the state change definition file, you must refer to the localized text strings that describe the valid states for a particular order type. You must define these text strings and load them into the database by using the load_localized_strings utility. A sample localized strings file for order states is located in BRM_Home/sys/msgs/order_states/order_states.en-US.
Displays information about successful or failed processing as the utility runs.
Writes error information for debugging purposes to the utility log file. By default, the file is located in the same directory as the utility and is called default.pinlog. You can specify a different name and location in the Infranet.properties file.
The name and location of the state change definitions file, where order represents the order type. For example, for Number Management, the file could be pin_order_state_num. Each order type must have its own file.
A sample state change definition file is provided in BRM_Home/sys/data/config/pin_order_state.
Use this syntax for entries:
storable_object_type order_type state_id: state_type: strid_id: string_ver : next_id1 : next_id2
storable_object_type
A subclass of /config/order_state, for example /config/order_state/sim. The storable object type must be the first non-comment line in the file. Only one storable object type can be specified.
order_type
The order type, for example /order/voucher. The order type must be the second non-comment line in the file. Only one order type can be specified.
state_id
An integer state ID, such as 0, 1, 2, and so on. State IDs can be freely assigned, except for 0, which is reserved for the Raw state.
state_type
An integer representing the state type to which state_id belongs. The state type determines the valid behaviors of states of that type. There are four possible values:
0 (RAW): Includes the state that marks the beginning of the order life cycle. Only one state can be of this type. States of type RAW can transition only to states of type INIT. Order objects cannot be saved in raw state.
1 (INIT): Includes all the states in which the order can be saved immediately after its creation. States of type INIT can transition to states of type INIT, NORMAL, or END.
2 (NORMAL): Includes all the working states between INIT and END. States of type NORMAL can transition to INIT states, other NORMAL states, and END states.
3 (END): Includes all the terminal states of the life cycle. Orders cannot be transitioned from states of this type.
str_id
ID of the state's localized text string in /string. You must load these text strings into the database via a text file and the load_localized_strings utility.
str_version
Version number of the state's localized text string in /string.
next_idx
An integer state ID that specifies a order state to which state_id can transition. Any integer value is allowed except 0, which is reserved for Raw state.
The sample state change definitions file includes additional information about the correct syntax for entries. Its location is BRM_Home/sys/data/config/pin_order_state.
If the load_pin_order_state utility doesn't notify you that it was successful, look in the log file (normally default.pinlog) for error messages. The log file is located in the directory from which the utility was started, or in a directory specified in the Infranet.properties configuration file.
The utility fails if it detects duplicate state IDs in the state change definitions file. It also fails if the file contains more than one storable object or order type entry.
Use this utility to specify account and service object fields to be included in the flist sent to a real-time rerating, discounting, or zoning pipeline. The main uses for this utility include:
Improving system efficiency by removing (trimming) fields that Pipeline Manager doesn't use.
Supporting custom iScripts and iRules in the real-time pipeline by adding fields to flists which are not included by default.
See "Customizing Flists Sent to a Real-Time Pipeline" in BRM System Administrator's Guide.
You can configure a different set of fields to be included in the flist based on event type.
Account object fields are included in the PIN_FLD_INHERITED_INFO substruct in the flist. Service object fields are included in the PIN_FLD_INHERITED_INFO.PIN_FLD_SERVICE_INFO substruct.
Note:
You cannot load separate /config/rtp/trim_flist objects for each brand. All brands use the same object.Important:
You can't remove fields from the PIN_FLD_INHERITED_INFO substruct or the subordinate PIN_FLD_INHERITED_INFO.PIN_FLD_SERVICE_INFO substruct.You specify the list of required fields in an XML file (field_list.xml) and then load the file using the utility.
Important:
If you use the utility to add new fields to the flist, you must update the input modules of the all pipelines to add the fields to the EDR container.
After you use the utility, you must restart BRM.
Specifies the XML file that describes which fields should be read. For a sample flist, see BRM_Home/sys/data/config/pin_config_rtp_trim_flist.xml.
Displays information about successful or failed processing as the utility runs.
Creates a log file for debugging purposes. Use this parameter for debugging when the utility appears to have run with no errors, but the data has not been loaded into the database.
Use this BRM Perl script to parse include files for custom fields and opcodes and to generate memory-mappable files that extend the opcode and field name-to-number mapping tables. This allows you to use custom fields and opcodes by using their name or number in applications.
Note:
You can define opcodes and fields without including them in the mapping tables; however, you can't use them in client applications or testnap by using their symbolic names instead of numbers.The parse_custom_ops_fields script reads the specifications of opcodes and fields from the input header file and creates corresponding entries in the output memory-mapped file or header file.
The script also generates a Java class for each field. You must compile each class with JavaPCM.jar in the CLASSPATH. You can either include the CLASS files in a JAR file, or build them in a base directory and leave them there. Then you must add the JAR file or the base directory to the CLASSPATH.
If you build the class files in the base directory, make sure the base directory matches the package name. For example, if the java_package is com.portal.classFiles, then the base directory must be /com/portal/classFiles.
For custom fields, the script creates a properties file in the java_package directory, named InfranetPropertiesAdditions.properties. You must append this file to your Infranet.properties file.
The BRM API used. It can be pcmc (for PCM C), or pcmjava (for Java PCM).
Note:
perlpcmif is a wrapper API for PCM C. If you run the script with the pcmc option, you can call custom opcodes in your Perl PCM-based client applications.input
The header file you create for your custom opcodes and fields.
The memory-mapped file or directory for the output of the script. If language is pcmjava, then output must be a directory having some correspondence with the Java package. For example, if the java_package is in com.portal.classFiles, then output must be f:/mysource/com/portal/classFiles.
The Java package, where you want to put the generated classes.
Use this utility to dump and validate information for one or more accounts from the BRM database.
For more information on using pin_adu_validate utility, see "About Dumping and Validating Account-Related Information" in BRM Managing Customers.
Note:
To connect to the BRM database, this utility needs a configuration file in the directory from which you run it. The pin.conf file for this utility is in BRM_Home/sys/diagnostics/pin_adu_validate. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.Uses the account search flist in the input file configured in the pin_adu_validate configuration file (pin.conf) to search for storable objects associated with the accounts in the BRM database and dumps the object data into an output file.
Performs the predefined validations enabled in the pin_adu_validate configuration file (pin.conf) file and any custom validations defined in the PCM_OP_ADU_POL_VALIDATE policy opcode.
Note:
To perform validation, you must specify both the -dump and -validate options at the same time.Searches for account information in the BRM database using the account search flist in the input file configured in the pin_adu_validate configuration file (pin.conf) file and provides statistical data about the accounts, such as the number of object instances found for each object specified in the pin.conf file. The statistical data is written to the Connection Manager (CM) log file.
Note:
pin_adu_validate uses the date ranges configured in the pin.conf file to provide statistics for most commonly updated objects. See "Limiting Dump Information by Specifying a Date Range" in BRM Managing Customers.Sample output:
Number of /account object instances found for the account [82828]: 1 Number of /service/email object instances found for the account [82828]: 1 Number of /service/ip object instances found for the account [82828]: 1 Number of /payinfo/cc object instances found for the account [82828]: 1
Use the pin_bus_params utility to retrieve and load configurable business parameters for the /config/business_params objects in the BRM database. These parameters enable optional BRM features or control things like the tracking level for write-off reversals, whether to validate exclusions for discounts, and so forth.
You use this utility to perform two tasks:
Retrieve the contents of a /config/business_params object and convert its contents into XML for easy modification.
Load a modified XML file containing a parameter class and its associated parameters into the appropriate /config/business_params object in the BRM database.
The utility retrieves the /config/business_params objects, converts them to XML, and writes them into the BRM_Home/sys/data/config/pin_bus_params_ParameterClassName.xml.out file. The utility also loads the objects into BRM from this file, converting them back into the format required by the object. You can optionally place the file in a different location, but if you do, you must also copy the bus_params_conf.xsd file from the BRM_Home/xsd directory to the new location and modify the file to include the correct relative paths to the bus_params_ParameterClassName. xsd files.
You can use another utility, pin_cfg_bpdump, to dump the contents of all business parameters in XML format. You can direct the XML output to a file or to a utility or application. See "Dumping Business Parameters in XML Format" in BRM System Administrator's Guide.
Note:
This utility is brand-aware. You can load separate /config/busines_params objects for each brand.Caution:
When loading business parameters, the pin_bus_params utility overwrites the /config/business_params object for the parameter class that appears in the XML file. If you are updating some of the parameters in the class, you cannot load the new parameters only. You must load a complete set of parameters for the class.The pin_bus_params utility is a perl script. To run the utility, you must set path to perl in your environment.
Important:
To connect to the BRM database, the pin_bus_params utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.For retrieving a /config/business_params object for a parameter class:
pin_bus_params [-h] -r ParameterClassTag bus_params_ParameterClassName.xml
For loading a /config/business_params object from a specified file:
pin_bus_params [-h] bus_params_ParameterClassName.xml
Retrieves the contents of a /config/business_params object and converts it to XML for editing.
Displays the syntax and parameters for this utility.
Specifies the parameter class tag for the parameter class you are retrieving. This parameter is case sensitive and uses the following naming convention:
BusParamsObjectClassName
Where ObjectClassName is the name of the class in the /config/business_params object. For example, the object class name for the /config/business_params object that contains the business parameters that control billing is billing, so the parameter class tag is BusParamsBilling. This parameter is case sensitive.
If you use the - r parameter, this parameter specifies the name and location of the XML output file created by the utility. This file contains the business parameters for the class identified in the ParameterClassName part of the file name.
If you do not use the - r parameter, this parameter specifies the name and location of the XML input file that you are loading into the /config/business_params object. This file contains the business parameters for the class identified in the ParameterClassName part of the file name. BRM overwrites the /config/business_params object that class.
To specify a different directory, include the full path and file name, as in the following example that loads XML file contents into the /config/business_params object for the billing business parameters:
pin_bus_params C:\param_conf\bus_params_billing.xml
Important:
If you are loading parameters from a directory other than BRM_Home/sys/data/config, the directory you are using must contain a business_configuration.xsd file. The utility uses the bus_params_ParameterClassName.xsd file to validate the XML file.The utility checks XML validity against rules defined in the bus_params_ParameterClassName.xsd file. This file resides in the BRM_Home/sys/data/config directory, and you must point to it through a bus_params_config.xsd file in the directory that contains your working XML file.
The validity check ensures that the XML meets these standards:
The parameter class name in the file is unique.
The parameter class contains at least one parameter.
The pin_bus_params utility notifies you when it successfully creates or modifies the /config/business_params object. Otherwise, look in the default.pinlog file for errors. This file is either in the directory from which the utility was started, or in a directory specified in the utility configuration file.
If you use the utility to load a /config/business_params object, you can display the object by using the Object Browser, or use the robj command with the testnap utility. See "Reading an Object and Writing Its Contents to a File". This example shows an element in the /config/business_params object:
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/business_params 10830 0 0 PIN_FLD_CREATED_T TSTAMP [0] (1083892760) Thu May 06 18:19:20 2004 0 PIN_FLD_MOD_T TSTAMP [0] (1083892760) Thu May 06 18:19:20 2004 0 PIN_FLD_READ_ACCESS STR [0] "G" 0 PIN_FLD_WRITE_ACCESS STR [0] "S" 0 PIN_FLD_ACCOUNT_OBJ POID [0] 0.0.0.1 /account 1 0 0 PIN_FLD_DESCR STR [0] "Business logic parameters for AR" 0 PIN_FLD_HOSTNAME STR [0] "-" 0 PIN_FLD_NAME STR [0] "ar" 0 PIN_FLD_PROGRAM_NAME STR [0] "-" 0 PIN_FLD_VALUE STR [0] "" 0 PIN_FLD_VERSION STR [0] "" ... 0 PIN_FLD_PARAMS ARRAY [2] allocated 4, used 4 1 PIN_FLD_DESCR STR [0] "Enable/Disable payment suspense management. The parameter values can be 0 (disabled), 1 (enabled). Default is 0 (disabled)." 1 PIN_FLD_PARAM_NAME STR [0] "payment_suspense_enable" 1 PIN_FLD_PARAM_TYPE INT [0] 1 1 PIN_FLD_PARAM_VALUE STR [0] "1"
Important:
To connect to the BRM database, you must restart the Connection Manager (CM) to activate new business parameters. For information on restarting the CM, see "Starting and Stopping the BRM System" in BRM System Administrator's Guide.For multischema systems, you must also refresh the configuration data by running the pin_multidb perl script with the -R CONFIG parameter set. For more information, see "pin_multidb" in BRM System Administrator's Guide.
Use the pin_cfg_bpdump utility to dump BRM business parameters in XML format. You can direct the output to a file or to another utility or application, such as a diagnostic application.
For more information, see "Dumping Business Parameters in XML Format" in BRM System Administrator's Guide.
Important:
To connect to the BRM database, the pin_cfg_bpdump utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.The pin_cfg_bpdump utility outputs in XML format the contents of all /config/business_params objects.
The pin_cfg_bpdump utility does not produce pinlog notifications of success or failure. If there is an error, the utility produces no output. You can refer to the CM and DM logs for information about the problem.
Use this utility to encrypt files, plaintext, and plaintext passwords; generate encryption keys; load keys into memory; store root keys in root key wallets; and automatically modify the Oracle Data Manager (DM) pin.conf file.
For more information, see the following:
To encrypt files, plaintext, and plaintext passwords:
pin_crypt_app [-enc [-f Filename] | Plaintext | Plaintext_passwd]
To generate an encrypted AES key:
pin_crypt_app [-genkey -key Key | -update_dm_conf]
To generate or modify a root key:
pin_crypt_app [-genrootkey]
To generate a 256-bit encrypted key from the AES key provided:
pin_crypt_app [-key AES_key]
To encrypt files and plaintext, and to generate a key using the Oracle ZT PKI algorithm:
pin_crypt_app [-useZT -enc -f Filename |-enc Plaintext | -genkey -key Key]
To display the syntax and parameters for this utility:
pin_crypt_app [-help]
Encrypts files, plaintext, and plaintext passwords. Use the following options with this parameter:
-f Filename — The utility uses AES encryption to encrypt the specified file. Filename is the name of the file to encrypt.
Plaintext — The utility uses AES encryption to encrypt the specified plaintext. Plaintext is the text to encrypt.
Plaintext_password — The utility uses AES encryption to encrypt the specified password. Plaintext_password is the text to encrypt.
Generates a 256-bit encrypted AES key. BRM generates a random AES key internally to generate the encrypted AES key. Use the following options with this parameter:
-key — The utility generates a 256-bit encrypted AES key. Key is the 256-bit key in hexadecimal notation (64 hexadecimal characters).
-update_dm_conf — The utility adds the new key to the BRM_Home/sys/dm_oracle/ pin.conf file.
Note:
If this is the first time that an AES key has been created, stop and restart the DM when prompted by the pin_crypt_app utility.The -key and -update_dm_conf options can be combined.
Generates or modifies a root key and stores it in a root key wallet. The root key is used for encryption using the Oracle ZT PKI–approved encryption algorithm.
For more information on the Oracle ZT PKI encryption algorithm, see "Configuring the Data Manager for Oracle ZT PKI Encryption".
Generates a 256-bit encrypted key from the specified AES key. Use this parameter if you already have an AES key and do not want BRM to generate one internally.
Uses the Oracle ZT PKI algorithm to encrypt files and plaintext and to generate a key. Use the following options with this parameter:
-enc -f Filename — The utility uses the Oracle ZT PKI encryption algorithm to encrypt the specified file. Filename is the name of the file to encrypt.
-enc Plaintext — The utility uses the Oracle ZT PKI encryption algorithm to encrypt the specified plaintext. Plaintext is the text to encrypt.
-genkey -key Key — The utility uses the Oracle ZT PKI encryption algorithm to generate a 256-bit encrypted key. Key is the 256-bit key in hexadecimal notation (64 hexadecimal characters).
Displays the syntax and parameters for this utility.
Use the pin_crypt_upgrade utility to migrate MD5-encrypted data to the AES encryption scheme. This utility uses the psiu_encrypt and psiu_decrypt APIs.
Important:
Before you run the pin_crypt_upgrade utility, the DM pin.conf file must contain the existing MD5 plaintext key in the decrypt entry and an encrypted AES key in the crypt entry. This utility uses both keys to upgrade all fields that are set to encryptable. For more information, see "Migrating Data from MD5 to AES Encryption". For information on generating an encrypted AES key, see "Generating an Encrypted AES Key".Sets the log level to debug and writes debug information to the log file for this process. If not set, the only output is error-level information.
Displays information about successful or failed processing as the utility runs.
Upgrades the records that are modified before the date specified. If this parameter is not specified, the current pin_virtual_time is used to retrieve the records.
The pin_crypt_upgrade utility notifies you only if it encounters errors. Look in the default.pinlog file for errors. This file is either in the directory from which the utility was started or in a directory specified in the utility configuration file.
Note:
The pin_crypt_upgrade utility automatically runs the pin_crypt_rewrite utility. The pin_crypt_rewrite utility is an internal application. Do not run the pin_crypt_rewrite manually.Transport definitions for storable classes and fields from one BRM server to another. This utility reads storable class and field definitions from a Portal Object Definition Language (PODL) file and loads them into the BRM data dictionary. This utility also exports storable class and field definitions from the BRM data dictionary to a PODL file.
Important:
Before attempting to create new storable classes, verify that enough space is available in the BRM database. This utility can not test for available space. If the available space is exhausted before deployment is complete, new storable classes might be in an inconsistent state.See "Deploying Custom Fields and Storable Class Definitions".
There are five commands for pin_deploy:
To print the syntax and parameters for this utility, type -h or -help.
Connect to BRM server, determine changes to be made, and report any conflicts. May alternatively accept PODL from stdin.
pin_deploy verify [file_one file_two ... file_N]
Example:
pin_deploy verify myobj.podl
Connects to the default database schema specified in the pin.conf file, determines the changes required for creating the class and field definitions contained in the PODL file, and reports conflicts.
If your BRM installation includes a separate dm_invoice database, you can use two parameters with the verify command:
Use the -d switch to connect to a dm_invoice database for a BRM installation that initially used a dm_oracle database schema to store /invoice objects. If you use the -d switch, specify the target database schema by database number. Omit the -d switch and database number to connect to the default database schema.
Use the -e switch to print debugging information to the logfile.
pin_deploy verify [-de] [target_db] [file_one file_two ... file_N]
Example:
pin_deploy verify -de 0.0.6.1 myobj.podl
Connects to the dm_invoice database 0.0.6.1, determines the changes required for creating the class and field definitions contained in the PODL file, reports conflicts, and prints debugging information to the logfile.
Load storable class and field definitions into the data dictionary. Succeeds only if there are no conflicts. If there are conflicts, they are reported and no action occurs. May alternatively accept PODL from stdin.
pin_deploy create [file_one file_two ... file_N]
Example:
pin_deploy create myobj.podl
Connects to the default database schema specified in the pin.conf file, creates the class and field definitions contained in the PODL file, and prints debugging information to the logfile. If conflicts are encountered, the operation fails without taking any action.
If your BRM installation includes a separate dm_invoice database, you can use two parameters with the create command:
Use the -d switch to connect to a dm_invoice database for a BRM installation that initially used a dm_oracle database schema to store /invoice objects. If you use the -d switch, specify the target database schema by database number. Omit the -d switch and database number to connect to the default database schema.
Use the -e switch to print debugging information to the logfile.
pin_deploy create [-de] [target_db] [file_one file_two ... file_N]
Example:
pin_deploy create -de 0.0.6.1 myobj.podl
Connects to the dm_invoice database 0.0.6.1, creates the class and field definitions contained in the file, and prints debugging information to the logfile. If conflicts are encountered, the operation fails without taking any action.
Load storable class and field definitions into the data dictionary. Overwrites storable class and field definitions even if conflicts exist. The SQL table and column names for storable classes can not be overwritten. When loading field definitions, only the field description attribute is overwritten. May alternatively accept PODL from stdin.
pin_deploy replace [file_one file_two ... file_N]
Example:
pin_deploy replace myobj.podl
Connects to the default database schema specified in the pin.conf file, creates the class and field definitions contained in the PODL file, and prints debugging information to the logfile. If conflicts occur, existing definitions are overwritten.
If your BRM installation includes a separate dm_invoice database, you can use two parameters with the replace command:
Use the -d switch to connect to a dm_invoice database for a BRM installation that initially used a dm_oracle database schema to store /invoice objects. If you use the -d switch, specify the target database schema by database number. Omit the -d switch and database number to connect to the default database schema.
Use the -e switch to print debugging information to the logfile.
pin_deploy replace [-de] [target_db] [file_one file_two...file_N]
Example:
pin_deploy replace -de 0.0.6.1 myobj.podl
Connects to the dm_invoice database 0.0.6.1, creates the class and field definitions contained in the PODL file, and prints debugging information to the logfile. If conflicts occur, existing definitions are overwritten.
Export storable class definitions from a BRM server in PODL format. May specify any number of storable classes on command line. If no storable classes are specified, then all classes will be exported.
pin_deploy class [-mnscp] [class_one class_two ... class_N]
[-m] Export storable class implementation.
[-n] Export storable class interface.
[-s] Include all subclasses of specified storable class.
[-c] Include field definitions for all customer-defined fields within storable classes.
[-p] Include field definitions for all BRM-defined fields within storable classes.
Examples:
pin_deploy class -mn /account /bill
Export definitions for the /account and /bill storable classes from a BRM server in PODL format. Includes both implementations and interfaces.
pin_deploy class -s /event
Export the /event storable class interface along with all of its subclasses.
Export field definitions from a BRM server in PODL format. May specify any number of fields by name. If no fields are specified, then all fields will be exported unless the -c or -p parameters are used.
pin_deploy field [-cp] [field_one field_two ... field_N]
[-c] Include field definitions for all customer-defined fields.
[-p] Include field definitions for all BRM-defined fields.
Examples:
pin_deploy field PIN_FLD_PRODUCTS PIN_FLD_NAMEINFO
Export definitions for the PIN_FLD_PRODUCTS and PIN_FLD_NAMEINFO fields from a BRM server in PODL format.
pin_deploy field -cp
Export definitions for all customer and BRM-defined fields from a BRM server in PODL format.
Use this utility to migrate event import templates from one BRM database schema to another. You use event import templates to load data from log files into BRM as billable events. For more information, see "Migrating Event Import Templates from One BRM Database Schema to Another" in BRM Setting Up Pricing and Rating.
Note:
This utility is brand-aware. You can load separate /config/gel/template objects for each brand.Important:
To connect to the BRM database, the pin_uei_deploy utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.The name of the template.
This parameter is followed by the name of the event import template that you read, create, delete, or modify (depending on the command).
The input file (event import template) to load into the database schema.
The output file to save on the local system.
Displays the syntax and parameters for this utility.
Lists all event import templates stored in the database schema.
pin_uei_deploy -l
There are no parameters for this command.
Creates the specified event import template.
pin_uei_deploy -t template_name -c -i output_file
Example:
Create an event import template named CDR3 and load it into the database schema:
pin_uei_deploy -t CDR3 -c -i CDRoutput
Note:
If an event import template with the same name exists in the database schema, the operation fails and pin_uei_deploy logs an error. Delete the existing event import template first, or overwrite it by using the modify operation.Modifies the specified event import template.
pin_uei_deploy -t template_name -m -i output_file
Example:
Load into the database schema an event import template called CDR3 and overwrite the existing template with the same name:
pin_uei_deploy -t CDR3 -m -i CDRoutput
Deletes the specified event import template.
pin_uei_deploy -t template_name -d
Example:
Delete the event import template named CDR3:
pin_uei_deploy -t CDR3 -d
Reads the specified event import template from the database schema.
pin_uei_deploy -t template_name -r -o output_file
Example:
Read the event import template named CDR3, and save it to an output file on the local system named CDRoutput:
pin_uei_deploy -t CDR3 -r -o CDRoutput
Use the BRM pin_virtual_time utility to adjust or display BRM's current time and date, without affecting the operating system time and date. This utility is useful for testing billing and other time-sensitive functions in BRM.
For information about using the pin_virtual_time utility, see "Testing Your Price List" in BRM Setting Up Pricing and Rating.
Caution:
Use pin_virtual_time only with a test database. You should not change the BRM system time on a production BRM database.Note:
If you use pin_virtual_time with a BRM system that includes the Pipeline Manager, you need to set the VirtualTime parameter for the DAT_BalanceBatch module to True to ensure that balances are calculated correctly. See "DAT_BalanceBatch" in BRM System Administrator's Guide.
To test custom client applications that are connected to the CM, you can use PCM_OP_GET_PIN_VIRTUAL_TIME to get the virtual time that is set by pin_virtual_time.
To run BRM with pin_virtual_time enabled:
Make sure all BRM components are stopped.
Configure all BRM components, via their pin.conf files, to use pin_virtual_time. A file containing time and date information for the pin_virtual_time utility is created the first time that pin_virtual_time is run. BRM recommends you designate BRM_Home/lib/pin_virtual_time_file with the -f parameter.
Type pin_virtual_time with the -m option to set the mode and value of the time.
Important:
If there are multiple BRM machines, run pin_virtual_time on all of them.Start all BRM components.
Perform testing as desired.
Between testing stages, adjust the time with pin_virtual_time. You can change modes.
After completing testing, stop all BRM components
Remove or comment out (with #) the pin_virtual_time entry in the pin.conf files.
Perform database cleanup if needed.
All BRM server component pin.conf files must contain the following line to use pin_virtual_time to set BRM's time:
- - pin_virtual_time BRM_Home/lib/pin_virtual_time_file
The pin_virtual_time_file file contains the information that BRM requires to determine the time/date mode and how to set it.
The pin_virtual_time_file file is mapped into memory by pin_virtual_time when each BRM component starts up. If different BRM components are running on different machines (for example, the Connection Manager on one machine and the Data Manager on another), then pin_virtual_time must be enabled in the pin.conf files on both machines, and whenever pin_virtual_time is set on one machine it must be set correspondingly on the other machine(s). Failure to do so may cause BRM to operate incorrectly.
See "Using Configuration Files to Connect and Configure Components" in BRM System Administrator's Guide for information on setting up pin.conf files.
Note:
Make sure installation is complete before you put a pin_virtual_time line in the pin.conf file for your DM.By default (without the -m option), pin_virtual_time prints the current pin_virtual_time to stdout once and then exits.
Print the current BRM time every interval seconds to stdout (until interrupted by CTRL C).
Set BRM according to mode and time_value:
0 = Use operating system time (normal mode). BRM uses operating system time with no adjustments.
1 = Use time_value as a constant time (freeze mode). Time is frozen at the specified time until the pin_virtual_time command is used again to change the time or mode. Use only when absolutely necessary, because BRM expects time to be moving.
2 = Use time_value as the new time, and keep the clock running (offset mode). Time is adjusted to the time specified, and then advances one second every second. This is the mode that should be used for testing.
Use the format MMDDHHMM[CC]YY[.SS].
Accept backwards movement. Allow the specified time to be before the current pin_virtual_time (time can be moved backwards).
Caution:
Move time backwards only when rebuilding BRM from scratch. Otherwise, moving time backwards can cause severe data corruption.Store the pin_virtual_time structure in the designated file and location. BRM recommends BRM_Home/lib/filename. This path and file name must match the path and file name specified in the pin_virtual_time line in the pin.conf files for each BRM component.
Displays the syntax and parameters for this utility.
If the utility doesn't notify you that it was successful, look in the utility log file (default.pinlog) to find any errors. The log file is either in the directory from which the utility was started, or in a directory specified in the configuration file.
Print the current pin_virtual_time setting and mode:
% pin_virtual_time
mode 2 940102477 Sat Oct 16 12:34:37 1999
Print current pin_virtual_time every four seconds:
% pin_virtual_time -i 4
mode 2 940102527 Sat Oct 16 12:35:27 1999
mode 2 940102531 Sat Oct 16 12:35:31 1999
mode 2 940102535 Sat Oct 16 12:35:35 1999
mode 2 940102539 Sat Oct 16 12:35:39 1999
^C
%
Set pin_virtual_time to offset mode 12/31/98 11:30:43:
% pin_virtual_time -m 2 123111301998.43 filename BRM_Home/lib/pin_virtual_time_file, mode 2, time: Thu Dec 31 11:30:43 1998
Set pin_virtual_time to normal mode:
% pin_virtual_time -m 0 filename BRM_Home/lib/pin_virtual_time_file, mode 0
The testnap utility enables a developer to manually interact with the BRM server by establishing a PCM connection with the Connection Manager (CM) and then executing PCM operations by using that connection. Using testnap, a developer can perform the following tasks:
Create input flists
Save input and output flists
Send opcodes
View return (output) flists
Create, view, modify, and delete objects and their fields
Open, commit, and abort transactions
For examples and information on using testnap, see "Testing Your Applications and Custom Modules".
Opcode Workbench, part of the Developer Center offers similar functionality in a GUI-based application. See "Testing Your Applications and Custom Modules" and the Opcode Workbench help system for detailed information.
The testnap utility requires a pin.conf configuration file to connect to your BRM system. You can either use the CM's pin.conf file, or run testnap from a directory that contains a suitable pin.conf file, such as BRM_Home/sys/test.
The testnap utility relies on POID logins and types to identify the specific account or storable class to modify. A POID database number is required as a placeholder only.
The necessary pin.conf information is:
- nap cm_name hostname # Name of the system where the cm is running. - nap userid 0.0.0.1 /service/pcm_client 1 # Database number, 0.0.0.1 by default. - nap login_type 1 # Type 1 means login with password. - nap login_name root.0.0.0.n # Username testnap uses to log in to Portal. - nap login_pw password # Password is "password" by default. Differs from one Portal installation to another. - nap cm_ptr ip hostname 11960 # CM pointer: protocol hostname port. Allows multiple CM's to be specified in a pin.conf file. The application will try them consecutively until one works or there are no more "cm_ptr" entries.
The correct path to the shared libraries must also be configured. The library path is configured by default to point to the standard libraries in BRM_Home/lib. If the libraries are not in BRM_Home/lib, then you must set the library path environment appropriately.
The testnap utility allocates numerous internal buffers, which are used to store object or flist fields. Buffers are referenced by integers of the user's choice. Every time a new buffer is referenced, testnap allocates that new buffer.
If you do not specify a buffer number for a command that expects one, you will be prompted for a buffer number.
The meta keyword causes testnap to display the size of external buffer fields. By default, the contents of external buffer fields are displayed.
r {<<token [file]} [buf]
Read an flist or object from a file and put it in a testnap buffer. The <<token operator causes testnap to read from stdin until the token string is read.
r+ {<<token [file]} [buf]
Read and append flist to existing buf. The <<token operator causes testnap to read from stdin until the token string is read.
w [buf] [file]
Write contents of testnap buffer to a file.
w+ [buf] [file]
Append contents of a testnap buffer to the same file.
l
List the testnap buffers that are currently in use.
d [buf]
Display a testnap buffer.
! cmds [args]
Run a shell command (for UNIX systems only).
s [buf]
Save an flist or object from the input buffer to a testnap buffer.
< [file]
Execute cmd script.
p [<property> <value>]
Display or set properties.
q
Quit this program.
h, help,?
Print usage help message.
create {[buf] | [poid]}
Create an object. Run PCM_OP_CREATE_OBJ and print the return flist to stdout. The poid keyword causes the poid id of the object that is created to be the poid id specified in the input flist.
delete {[buf] | [- <db> <type> <id>]}
Delete an object. Run PCM_OP_DELETE_OBJ and print the return flist to stdout. The poid of the object to be deleted can be specified on the command line.
robj {[buf] | [- <db> <type> <id>]} [meta]
Read an object. Run PCM_OP_READ_OBJ using either the poid in the flist in buf, or the poid specified on the command line. Prints the return flist (the contents of the object) to stdout.
rflds buf [meta]
Read fields. Run PCM_OP_READ_FLDS using the flist in buf, and print the return flist to stdout. Each field (or row) in the field list must be in a valid flist format. The values for the last field are arbitrary, but must be valid for their type. For example, you have to include "" for STR fields and (some number) for a TSTAMP field. If either of these fields are blank, an error is returned.
wflds [buf]
Write fields. Run PCM_OP_WRITE_FLDS and print the return flist to stdout.
dflds [buf]
Delete fields. Run PCM_OP_DELETE_FLDS and print the return flist to stdout.
search buf [meta] [count]
Search. Run PCM_OP_SEARCH and print the return flist to stdout. The count operator sets the PCM_OPFLG_COUNT_ONLY flag, which causes search to return only the number of matches found by the search. The count is returned as the ELEM_ID of the RESULTS array on the output flist.
ssrch buf [meta]
Step-search. Run PCM_OP_STEP_SEARCH and print the return flist to stdout.
snext buf [meta]
Step-search next. Run PCM_OP_STEP_NEXT to get the next object in a step search, and print the return flist to stdout.
send buf
End step-search. Run PCM_OP_STEP_END and print the return flist to stdout.
gdd {[buf] | [- <db> <type> <id>]}
Get data dictionary. Run PCM_OP_GET_DD and print the return flist to stdout. The poid can be specified on the command line.
sdd < flags> [buf]
Set data dictionary. Run PCM_OP_SET_DD and print the return flist to stdout.
sort buf sort_buf [descending_flag]
Read contents of buf, sort it non-recursively using the template in sort_buf, and print the sorted flist to stdout. Available on UNIX only. The descending flag is optional, with 0 (the default) indicating ascending order, and any non-zero integer indicating descending order.
Sorting is not implemented for the following:
POID
BINSTRS
BUFFERs
ERRBUFS
The number of ARRAY elements in the sort specification is ignored. Use 0. Sort specifications just need valid numbers. The numbers are not necessarily valid or desired values for the current sort; they are basically required place-holders.
rsort buf sort_buf [descending_flag]
Recursive sort. Read contents of buf, sort it recursively using the template in sort_buf, and print the sorted flist to stdout. Available on UNIX only. The descending flag is optional, with 0 (the default) indicating ascending order, and any non-zero integer indicating descending order.
open [ro|rw|lock {[buf] | [- <db> <type> <id>]}]
Open transaction. Run PCM_OP_TRANS_OPEN and print the return flist to stdout.
commit
Commit the current transaction. Run PCM_OP_TRANS_COMMIT and print the return flist to stdout.
abort
Cancel the current transaction. Run PCM_OP_TRANS_ABORT and print the return flist to stdout.
inc [buf]
Increment one or more fields of an object. Run PCM_OP_INC_FLDS and print the return flist to stdout.
noop [buf]
Run non-operational opcode. Run PCM_OP_TEST_LOOPBACK on that database schema and print the return flist to stdout.
pass [buf]
Run a pass_thru op to server. Run PCM_OP_PASS_THRU, an extension op that just sends an flist to a DM that supports it.
xop op flag buf
Run opcode op with flags set to flag, the contents of buf as the input flist, and print the sorted flist to stdout.
id
Print user and session ID.
echo string
Echo a string.
If an error occurs, the contents of the error buffer (ebuf) which corresponds to the error are written to stderr.
# Delete attempt with the - argument missing: pin@demo5-668> testnap ===> database 0.0.0.1 from pin.conf "userid" delete 0.0.0.1 /account 1 ERROR: bad number "0.0.0.1" no object to use for delete
# Attempt to read a non-existent object: robj - 0.0.0.1 /account 11988 PCM_OP_READ_OBJ failed: err 3:PIN_ERR_NOT_FOUND, field 0/16:PIN_FLD_POID, loc 4:PIN_ERRLOC_DM, errclass 4:PIN_ERRCLASS_APPLICATION, rec_id 0, resvd 30001
For more information on the error buffer, see "Understanding API Error Handling and Logging".
For an extensive set of examples, refer to the Examples section of "Testing Your Applications and Custom Modules".