1. Developer's Guide
  2. Programming Utilities
  3. Developer Utilities

58 Developer Utilities

Learn about the Oracle Communications Billing and Revenue Management (BRM) developer utilities.

Topics in this document:

load_config

Use this utility to load the contents of XML configuration files into configuration (/config/*) objects in the BRM database.

Note:

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 "Connecting 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 pin.conf entries in Table 58-1.

Table 58-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.

Location

BRM_home/apps/load_config

Syntax

load_config [-d] [-h] [-l] [-n] [-r class] [-t] [-T] [-v] [-w] [class] [config_file]

Parameters

-d

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.

-h

Displays syntax and parameters for the utility.

-l

Lists all validated configuration objects in the BRM database that are associated with config_file.

-n

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.

-r class

Deletes all instances of the specified storable class from the BRM database.

To specify the class, do not include /config/. For example, to specify the /config/lifecycle_states storable class, enter lifecycle_states.

-t

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.

-T

Validates configuration objects in the BRM database that are associated with config_file.

-v

Displays information about successful or failed processing as the utility runs.

-w class

Writes information from all objects of the specified storable class in the database to config_file.

To specify the class, do not include /config/. For example, to specify the /config/lifecycle_states storable 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.

config_file

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.

Results

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.

Note:

You must stop and restart the Connection Manager (CM) to make new service life cycle and service state mapping data available.

load_config_provisioning_tags

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 "Creating Provisioning Tags" in BRM Provisioning Services.

For information about the syntax of the XML file, see "Configuring Provisioning Tags " in BRM Provisioning Services.

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.

Note:

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. SeeConnecting BRM Utilities in BRM System Administrator's Guide.

Location

BRM_home/bin

Syntax 

load_config_provisioning_tags [-d] [-v] [-t] [-h] pin_config_provisioning_tags_file

Parameters

-d

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.

-v

Displays information about successful or failed processing as the utility runs.

load_pin_config_provisioning_tags any_other_parameter –v > filename.log

-t

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.

-h

Displays help information for using this utility.

pin_config_provisioning_tags_file

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.

Note:

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

Validity Checks

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.

Results

If load_config_provisioning_tags 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 pin.conf configuration file.

Note:

You must restart the Connection Manager (CM) to make new provisioning tags available.

load_localized_strings

Note:

Currently, localization is not supported in BRM.

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.

Note:

Use only one locale for each type of file.

For information on modifying and loading localized string files, see "Localizing and Customizing Strings".

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.

Note:

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 "Connecting BRM Utilities" in BRM System Administrator's Guide.

Location

BRM_home/data/config

Syntax

load_localized_strings [-v] [-f] [-h] filename.locale

Parameters

-v

Displays information about successful or failed processing as the utility runs.

load_localized_strings any_other_parameter –v > filename.log

-f

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.

-h

Displays help about using the load_localized_strings utility.

filename.locale

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.

    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.

Results

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.

Sample Files

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

load_pin_config_business_type

Self-Care Manager uses business type definitions to display the appropriate entry fields for an account.

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 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.

Note:

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";

Location

BRM_home/data/config

Syntax

load_pin_config_business_type [-d] [-v] [-?] filename

Parameters

-d

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.

-v

Displays information about successful or failed processing as the utility runs.

-?

Displays the syntax and parameters for this utility.

filename

The file containing the business type definitions, typically, BRM_home/data/config/pin_config_business_type.

Results

Table 58-2 lists the possible completion values this utility returns. The returned value is saved in the default.pinlog file:

Table 58-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

load_pin_device_permit_map

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.

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.

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.

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 "Connecting BRM Utilities" in BRM System Administrator's Guide for more information about configuration files.

Location

BRM_home/bin

Syntax

load_pin_device_permit_map [-v] [-d] map_file

Parameters

-v

Displays information about successful or failed processing as the utility runs.

-d

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.

map_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/number) 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/number. 

/device/number    :/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.

Results

If the load_pin_device_permit_map 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.

load_pin_device_state

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.

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.

You create a single /config/device_state object for that device type by using the root login.

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.

Location

BRM_home/bin

Syntax

load_pin_device_state [-v] [-d] state_change_file

Parameters

-v

Displays information about successful or failed processing as the utility runs.

-d

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.

state_change_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:

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

  • object_type

    A subclass of /config/device_state, for example /config/device_state/sim. The object type must be the first non-comment line in the file. Only one 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.

Results

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 object or device type entry.

load_pin_excluded_logins

Use this utility to load a list of service types that identify users through alias names rather than service logins.

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).

Note:

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 "Connecting BRM Utilities" in BRM System Administrator's Guide.

Location

BRM_home/bin

Syntax

load_pin_excluded_logins [-v] [-d] [-t] [-h] xml_file

Parameters

-v

Displays information about successful or failed processing as the utility runs.

-d

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.

-t

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.

-h

Displays help information for using this utility.

xml_file

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.

Note:

The file must be in the same directory as the business_configuration.xsd and pin_excluded_logins.xml files.

Validity Checks

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.

Results

If the load_pin_excluded_logins 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 pin.conf configuration file.

load_pin_order_state

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:

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.

You create a single /config/order_state object for that order type by using the root login.

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.

Location

BRM_home/bin

Syntax

load_pin_order_state [-v] [-d] state_file_order

Parameters

-v

Displays information about successful or failed processing as the utility runs.

-d

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.

state_file_order

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:

object_type
  
order_type 
  
state_id: state_type: strid_id: string_ver
 : next_id1
: next_id2

  • object_type

    A subclass of /config/order_state, for example /config/order_state/sim. The object type must be the first non-comment line in the file. Only one object type can be specified.

  • order_type

    The order type, for example /order/sim. 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.

Results

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 object or order type entry.

parse_custom_ops_fields

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 cannot 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.

Location

BRM_home/bin

Syntax

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

Parameters

language

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.

output

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.

java_package

The Java package, where you want to put the generated classes.

pin_adu_validate

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 "Validating Account Data" 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 "Connecting BRM Utilities" in BRM System Administrator's Guide.

Location

BRM_home/sys/diagnostics/pin_adu_validate

Syntax

pin_adu_validate [-dump [-validate]] [-report]

Parameters

-dump

Uses the account search flist in the input file configured in the pin_adu_validate configuration file (pin.conf) to search for objects associated with the accounts in the BRM database and dumps the object data into an output file.

-validate

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.

-report

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

pin_bus_params

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.

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.

Note:

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 "Connecting BRM Utilities" in BRM System Administrator's Guide.

Location

BRM_home/bin

Syntax

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

Parameters

-r

Retrieves the contents of a /config/business_params object and converts it to XML for editing.

-h

Displays the syntax and parameters for this utility.

ParameterClassTag

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.

bus_params_ParameterClassName.xml

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

Note:

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.

Validity Checks

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.

Results

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"

Note:

To connect to the BRM database, you must restart the Connection Manager (CM) to activate new business parameters.

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.

pin_cfg_bpdump

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.

Note:

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 "Connecting BRM Utilities" in BRM System Administrator's Guide.

Location

BRM_home/diagnostics/pin_cfg_bpdump

Syntax

pin_cfg_bpdump

Parameters

This utility has no parameters.

Results

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.

pin_crypt_app

Use this utility to encrypt files and plaintext passwords, generate encryption keys, load keys into memory, store root keys in Oracle wallets, and automatically modify the Oracle Data Manager (DM) pin.conf file. This utility supports both the OZT and AES encryption methods.

Note:

The AES encryption method is supported only on systems that have upgraded from BRM 7.5 to BRM 12.0 Patch Set 3 or later.

For more information, see:

Location

BRM_home/bin

Syntax

To encrypt files and plaintext passwords in AES:

pin_crypt_app  -enc [-f Filename]

To generate an encrypted AES key:

pin_crypt_app  -genkey [-key Key]

To generate a 256-bit encrypted key from an AES key:

pin_crypt_app  -genkey [-key AES_key]

To store configuration data in the wallet:

pin_crypt_app -setconf -wallet clientWalletLocation -program programName -parameter configEntry -value value

To retrieve configuration data from the client wallet:

pin_crypt_app -getconf -wallet clientWalletLocation -program programName -parameter configEntry

To generate or modify a root key:

pin_crypt_app  -genrootkey

To encrypt files and plaintext using the Oracle ZT PKI algorithm:

pin_crypt_app  -useZT -enc [-f Filename]

Parameters

-enc [-f Filename]

Encrypts files, plaintext, and plaintext passwords in AES format. When -enc is used alone, the utility prompts you for the password or plaintext to encrypt.

Include the -f Filename option to encrypt the specified file.
-genkey

Generates a 256-bit encrypted AES key. BRM generates a random AES key internally to generate the encrypted AES key. Use one or both of these options with the 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.

If this is the first time that an AES key has been created, stop and restart the DM when prompted by the utility.

-key AES_key

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.

-genrootkey

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".

-useZT

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: After prompting the user for the plaintext, the utility uses the Oracle ZT PKI encryption algorithm to encrypt the specified text.

  • -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).

-wallet clientWalletLocation

Specifies the path to the Oracle wallet for setting or getting the configuration values.

-parameter ConfigEntry

Specifies the configuration entry in the wallet that you want to set or get the values for.

-value value

Specifies the value that must be set in the Oracle wallet.

-program

Specifies the name of the program that is storing the configuration entry, such as dm.

-help

Displays the syntax and parameters for this utility.

Results

The pin_crypt_app utility returns the output when the operation is successful. It does not return errors.

pin_deploy

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.

Note:

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".

Location

BRM_home/bin

Commands

There are five commands for pin_deploy:

To print the syntax and parameters for this utility, type -h or -help.

Verify

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 storable class and field definitions contained in the PODL file, and reports conflicts.

Verify for dm_invoice

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 log file. 

    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 storable class and field definitions contained in the PODL file, reports conflicts, and prints debugging information to the log file.

Create

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 storable class and field definitions contained in the PODL file, and prints debugging information to the log file. If conflicts are encountered, the operation fails without taking any action.

Create for dm_invoice

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 log file. 

    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 storable class and field definitions contained in the file, and prints debugging information to the log file. If conflicts are encountered, the operation fails without taking any action.

Replace

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 storable class and field definitions contained in the PODL file, and prints debugging information to the log file. If conflicts occur, existing definitions are overwritten.

Replace for dm_invoice

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 log file. 

    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 storable class and field definitions contained in the PODL file, and prints debugging information to the log file. If conflicts occur, existing definitions are overwritten.

Class

Export storable class definitions from a BRM server in PODL format. Can specify any number of storable classes on command line. If no storable classes are specified, then all storable classes are 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.

Field

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.

pin_uei_deploy

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 to Another" in BRM Loading Events.

Note:

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 "Connecting BRM Utilities" in BRM System Administrator's Guide.

Location

BRM_home/bin

Syntax

pin_uei_deploy   -l|-c|-m|-d|-r|-v 
                 -t template name -i input_file -o output_file [-h]

Parameters

-t template_name

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).

-i input_file

The input file (event import template) to load into the database schema.

-o output_file

The output file to save on the local system.

-h

Displays the syntax and parameters for this utility.

Commands

List

Lists all event import templates stored in the database schema.

pin_uei_deploy -l

There are no parameters for this command.

Create

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.

Modify

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

Delete

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

Read

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

Verbose

Displays information about successful or failed processing as the utility runs.

pin_uei_deploy –v any_other_parameter

pin_virtual_time

Use this 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 Configuring Pipeline Rating and Discounting.

Caution:

Use pin_virtual_time only with a test database. You should not change the BRM system time on a production BRM database.

Note:

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.

Operation

To run BRM with pin_virtual_time enabled:

  1. Make sure all BRM components are stopped.

  2. 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.

  3. Type pin_virtual_time with the -m option to set the mode and value of the time.

    Note:

    If there are multiple BRM machines, run pin_virtual_time on all of them.

  4. Start all BRM components.

  5. Perform testing as desired.

  6. Between testing stages, adjust the time with pin_virtual_time. You can change modes.

  7. After completing testing, stop all BRM components

  8. Remove or comment out (with #) the pin_virtual_time entry in the pin.conf files.

  9. Perform database cleanup if needed.

Dependencies

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" 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.

Syntax

pin_virtual_time [-i interval] [-m mode [time_value] [-y]] 
                 [-f filename] [-h | -H | -?]

Parameters

By default (without the -m option), pin_virtual_time prints the current pin_virtual_time to stdout once and then exits.

-i interval

Print the current BRM time every interval seconds to stdout (until interrupted by CTRL C).

-m mode [time_value] [-y]

Set BRM according to mode and time_value:

mode

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.

time_value

Use the format MMDDHHMM[CC]YY[.SS].

-y

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.

-f filename

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.

-h, -H, -?

Displays the syntax and parameters for this utility.

Results

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.

Examples

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

testnap

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. See "Using the testnap Utility to Test BRM".

Dependencies

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 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.

Syntax

testnap
command [args]

About Buffer Numbers

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.

Testnap Commands

  • 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]

    Run 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.

Error Handling

If an error occurs, the contents of the error buffer (ebuf) which corresponds to the error are written to stderr.

Error Example 1

# 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

Error Example 2

# 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 "Finding Errors in Your Code".

Examples

For an extensive set of examples, refer to the Examples section of "Using the testnap Utility to Test BRM".

pin_config_editor

Use the pin_config_editor utility to set or get configuration entries for JAVA PCM client applications from the client wallet.

Location

BRM_home/bin

Syntax

To store a value in the wallet:

pin_config_editor -setconf -wallet clientWalletLocation -parameter configEntry -value value
To store a password in the wallet:
pin_config_editor -setconf -wallet clientWalletLocation -parameter configEntry [-pwd]

To retrieve configuration data from the client wallet:

pin_config_editor -getconf -wallet clientWalletLocation -parameter configEntry

To view configuration entries in the client wallet:

pin_config_editor -list -wallet clientWalletLocation

To display the syntax and parameters for this utility:

pin_config_editor [-help]

Parameters

-setconf

Adds or modifies values.

-getconf

Gets values.

-wallet clientWalletLocation

Specifies the path to the Oracle wallet for setting or getting the configuration values.

-parameter ConfigEntry

Specifies the configuration entry in the wallet that you want to set or get the values for.

-value value

Specifies the value that must be set in the Oracle wallet.

-pwd

Prompts you for the password to be stored in the client wallet. The password that you enter does not appear on the screen. If you want to store the encrypted password, enter the encrypted password at the command prompt.

-list

Displays all configuration entries in the wallet.

-help

Displays the syntax and parameters for this utility.

Results

The pin_config_editor utility sets the specified configuration entry and lets users retrieve configuration values from the client wallet.