Skip Headers
Oracle® Communications Billing and Revenue Management Synchronization Queue Manager
Release 7.5

E16720-07
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

2 Installing and Configuring the Synchronization Queue DM

This chapter describes how to install and configure Oracle Communications Billing and Revenue Management (BRM) Synchronization Queue Data Manager (DM).

For information about the Synchronization Queue DM and how it works, see "Understanding the Synchronization Queue Data Manager".

About Installing the Synchronization Queue DM

Before setting up the Synchronization Queue DM, you should be familiar with BRM concepts and architecture. See:

Note:

Synchronization Queue Data Manager is included in two separate downloadable packages: Web Services Manager and EAI Manager.

System Requirements

The Synchronization Queue DM is available for the HP-UX IA64, Solaris, AIX, and Linux operating systems.

Software Requirements

Before installing the Synchronization Queue DM, you must install:

Information Requirements

You need the following information about your existing BRM system during the Synchronization Queue DM installation:

  1. Queuing alias name.

  2. Queuing database user name and password.

  3. Database name and retention time of the queuing database.

Installing and Configuring the Synchronization Queue DM

Important:

Install the Synchronization Queue DM and then perform all configuration steps before starting the Synchronization Queue DM.

Installing the Synchronization Queue DM requires you to:

  1. Configure the database for Oracle Advanced Queuing (AQ). See "Configuring the Database for Advanced Queuing".

  2. Install the Synchronization Queue DM. See "Installing the Synchronization Queue DM".

  3. If your database queue is not located on the system where BRM is installed, link the databases. See "Linking Oracle Databases".

  4. Configure the EAI payload for synchronization queuing. See "Configuring the EAI Payload for the Synchronization Queue DM".

  5. Enable event notification. See "Configuring Event Notification for the Synchronization Queue DM".

  6. Configure the Synchronization Queue DM. See "Configuring the Synchronization Queue DM".

Configuring the Database for Advanced Queuing

Before you install the Synchronization Queue DM, you must configure the queuing database machine for Oracle Advanced Queuing (AQ).

Perform the following on the queuing database machine in your system:

  1. Open the Oracle_home/dbs/init.ora file.

  2. Set the compatible parameter to specify the Oracle database version.

    Important:

    If you use an entry lower than 10.0, your BRM system fails.
  3. Set the aq_tm_process parameter to 1 to specify one Oracle Queue Monitor process (QMn). QMn removes from the queue any processed events that are over an hour old.

  4. Save and close the file.

  5. Using SQL*Plus, log in to your database as the SYS user and grant AQ privileges to user pin:

    % sqlplus "sys/password@databaseAlias as sysdba"
      
    SQL> grant execute on dbms_aq to pin;
      
    Grant succeeded.
      
    SQL> grant execute on dbms_aqadm to pin;
      
    Grant succeeded.  
      
    SQL> grant select on sys.gv_$aq to pin;
      
    Grant succeeded.  
      
    SQL> grant execute on dbms_lock to pin;
      
    Grant succeeded.
      
    SQL> grant execute on dbms_aqin to pin;
      
    Grant succeeded. 
    
    SQL> grant execute on sys.dbms_aqin to pin;
    
    Grant succeeded.
      
    
  6. Stop and restart the Oracle database, which initializes the database instance with your changes.

Installing the Synchronization Queue DM

Note:

If you have already installed the product, you must uninstall features that you will reinstall before installing them again.

Synchronization Queue Data Manager is available in two separate downloadable packages:

  • Web Services Manager (7.5.0_WebServicesMgr_platform_32_opt.tar.Z) - This package includes Synchronization Queue DM, JCA Resource Adapter, and Web Services Manager.

  • EAI Manager (7.5.0_EAI_FrameworkMgr_platform_32_opt.tar.Z) - This package includes both EAI Manager and Synchronization Queue DM.

You must download the media pack and extract all appropriate components before you can install Synchronization Queue Data Manager.

To install the Synchronization Queue DM:

  1. Download the appropriate package to a temporary directory (temp_dir).

    Important:

    • If you download to a Windows workstation, use FTP to copy the package to a temporary directory on your UNIX server.

    • You must increase the heap size used by the Java Virtual Machine (JVM) before running the installation program to avoid "Out of Memory" error messages in the log file. For information, see "Increasing Heap Size to Avoid "Out Of Memory" Error Messages" in BRM Installation Guide.

  2. Go to the directory where you installed the Third-Party package and source the source.me file.

    Caution:

    You must source the source.me file to proceed with installation, otherwise ”suitable JVM not found” and other error messages appear.

    Bash shell:

    source source.me.sh
      
    

    C shell:

    source source.me.csh
      
    
  3. Go to temp_dir and enter this command:

    7.5.0_DM_AQ_platform_32_opt.bin -console
    

    Note:

    You can use the -console parameter to run the installation in command-line mode. To enable a graphical user interface (GUI) installation, install a GUI application such as X Windows and set the DISPLAY environment variable before you install the software.
  4. (Optional) If you are not installing all components on this computer, use the custom install when asked to specify the setup type. Select the components you are installing by typing their respective numbers and clicking Next.

  5. Follow the instructions displayed during installation. The default installation directory for the Synchronization Queue DM is /opt/portal/7.5.

    Note:

    The installation program does not prompt you for the installation directory if BRM or the Synchronization Queue DM is already installed on the machine and automatically installs the package at the BRM_home location.
  6. Go to the directory where you installed the Synchronization Queue DM package and source the source.me file:

    Bash shell:

    source source.me.sh
      
    

    C shell:

    source source.me.csh
      
    
  7. Go to the BRM_home/setup directory and run the pin_setup script.

    Note:

    The pin_setup script creates a queue on the specified database, configures your pin.conf files, and starts all required BRM processes.
  8. Stop the Synchronization Queue DM process. For information, see "Starting and Stopping the Synchronization Queue DM".

Linking Oracle Databases

Note:

If your database queue resides on the system on which BRM is installed, skip this section and go to "Configuring the EAI Payload for the Synchronization Queue DM".

If you installed the database queue on a system other than the system on which BRM is installed, you must create a link from the queuing database to the BRM database. This allows Oracle to forward events to queue residing on the other database.

Before linking your Oracle databases, verify that the database alias names are defined in each tnsnames.ora file (Oracle_home/network/admin/tnsnames.ora).

Tip:

You can check this by logging in to one database as user pin and connecting to the other databases by using the database alias. For example:
SQL> connect pin/password@databaseAlias

Note:

If you need to change the location of the database queue, follow the instructions in "Manually Creating a Database Queue on an Oracle Database".

To link your databases, perform the following steps from each database:

  1. Using SQL*Plus, log in to your database as the SYSTEM user and grant database linking privileges to user pin:

    % sqlplus system/manager@databaseAlias
       
    SQL> grant create database link to pin;
       
    Grant succeeded.
      
    
  2. Log in to the database as user pin:

    SQL> connect pin/password@databaseAlias
      
    
  3. Create a link to the other databases by entering the following command:

    SQL> CREATE DATABASE LINK remoteDatabaseAlias CONNECT TO pin IDENTIFIED BY pin_password USING 'RemoteDatabaseAlias';
      
    

    For example, if your BRM database has the alias name Portal1 and the database where the queue is located has the alias name Portal2, log in to Portal1 and give the following SQL command:

    SQL> CREATE DATABASE LINK portal2 CONNECT TO pin IDENTIFIED BY pin_password USING 'portal2';
      
    

    and log in to Portal2 and give the following SQL command:

    SQL> CREATE DATABASE LINK portal1 CONNECT TO pin IDENTIFIED BY pin_password USING 'portal1';
    

Configuring the EAI Payload for the Synchronization Queue DM

You must modify your BRM system's payload configuration file in the following situations:

For information about defining business events in the EAI payload configuration file, see "About the Payload Configuration File Syntax" in BRM Developer's Guide.

Checking for Conflicts in EAI payload Configuration Files

If your BRM system already has an EAI publisher, the Synchronization Queue DM installation program merges the Synchronization Queue DM payload configuration file with the existing payload configuration file that is referenced in BRM_home/sys/eai_js/Infranet.properties. The merged file is named payloadconfig_MergedWithCRMSync.xml.

In rare cases, conflicts can occur when payload configuration files are merged. This can happen when entries in the two files have conflicting definitions.

Important:

You must determine if there are merge conflicts before you run the Synchronization Queue DM.

Compare the Synchronization Queue DM payload configuration file (BRM_home/sys/eai_js/payloadconfig_crm_sync.xml) with the existing payload configuration file. If any of the following conditions exists, you must modify the business events in conflict and manually merge the two files in order to run the Synchronization Queue DM with other EAI publishers in the same BRM system:

  • Two different business event definitions specify the same StartEvent.

  • The same business event definitions have different values for one or more of these attributes: StartEvent, EndEvent, or Source.

  • The same business event or element definitions have different search criteria.

  • The same element definitions have different values for one or more of these attributes: Source, PinFld, DataFrom, UseOnlyElement, or Tag.

  • The same element definitions have different OnEvent values.

Specifying the Default Payload Configuration File

If your BRM system already has an EAI publisher, you must make the merged payload configuration file your system's default payload configuration file.

To specify the default payload configuration file, change the EAI configFile entry so that it points to the merged payload configuration file:

  1. In a text editor, open the eai_js properties file (BRM_home/sys/eai_js/Infranet.properties).

  2. Change the infranet.eai.configFile entry to refer to the merged file:

    infranet.eai.configFile=./payloadconfig_file_name.xml
      
    

    where ./payloadconfig_file_name.xml is the name of the merged file.

    The default merged file name is payloadconfig_MergedWithCRMSync.xml. If you manually merged payload configuration files, the file name is the name you gave it.

    Tip:

    You can use any meaningful name for the file that you choose, providing that it starts with payloadconfig_ and that the file name and the value of the infranet.eai.configFile entry match.
  3. Save and close the file.

Specifying the Synchronization Queue DM Database Number

The default BRM database number for your Synchronization Queue DM is 0.0.9.7. If you use a different database number, you must change the value of the publisher database in the payload configuration file.

  1. In a text editor, open the payload configuration file in the BRM_home/sys/eai_js directory (payloadconfig_crm_sync.xml, or the merged file if you merged payload configuration files).

  2. Find the <PublisherDefs> section.

  3. In the Publisher DB entry, specify the correct BRM database number.

    For example, if your Synchronization Queue DM database number is 0.0.9.5, change this entry:

    <PublisherDefs>
        <Publisher DB="0.0.9.7" Format="XML">
      
    

    to this:

    <PublisherDefs>
        <Publisher DB="0.0.9.5" Format="XML">
      
    
  4. Save and close the file.

Revising the Payload Configuration File when Uninstalling the Synchronization Queue DM

To remove Synchronization Queue elements from your system's EAI payload configuration file after uninstalling the Synchronization Queue DM:

  1. In a text editor, open the payload configuration file in the BRM_home/sys/eai_js directory (payloadconfig_crm_sync.xml, or the merged file if you merged payload configuration files).

  2. Find the <PublisherDefs> section.

  3. Remove the following publisher definition:

    <Publisher DB="0.0.9.7" Format="XML">
    

    Note:

    This is the default Synchronization Queue DM publisher definition. Your definition might have a different Publisher DB value.
  4. Save and close the file.

  5. Stop and restart the Payload Generator External Module (the EAI Java server) by entering this command from the BRM_home/bin directory:

    pin_ctl restart eai_js
    

Configuring Event Notification for the Synchronization Queue DM

Business events defined in the Synchronization Queue DM payload configuration file include a set of BRM events. When one of these BRM events occurs, the EAI framework uses event notification to call the opcode that caches the BRM event in the Payload Generator.

Before you can use the Synchronization Queue DM, you must configure the event notification feature as follows:

  1. If your system has multiple configuration files for event notification, merge them.

  2. Ensure that the merged file includes the entire event notification list in the BRM_home/sys/data/config/pin_notify_crm_sync file.

  3. (Optional) If you defined new business events in the Synchronization Queue DM payload configuration file, you must edit your final event notification list to include all the BRM events in the new business events.

  4. Load your final event notification list into the BRM database.

For more information, see "Using Event Notification" in BRM Developer's Guide.

Configuring the Synchronization Queue DM

You configure the Synchronization Queue DM to connect to the BRM database and the database queue by performing these tasks:

  1. Connect the Synchronization Queue DM's EAI framework to BRM by editing the CM configuration file (pin.conf). See "Configuring the CM for Synchronization Queuing".

  2. Map BRM business events to the database queue by editing the aq_queuenames file. See "Specifying which Business Events to Send to the Database Queue".

  3. Connect the Synchronization Queue DM to the database queue by editing the Synchronization Queue DM configuration file (pin.conf). See "Configuring the Synchronization Queue DM Configuration File".

Configuring the CM for Synchronization Queuing

You must modify the CM pin.conf file to enable the EAI framework to notify the Synchronization Queue DM when specific events occur. You should also verify that the pointer to the Synchronization Queue DM specifies the correct database and port numbers.

To configure the CM for synchronization queuing:

  1. Open the CM configuration file (BRM_home/sys/cm/pin.conf) in a text editor.

  2. Set the enable_publish entry to 1:

    - fm_publish enable_publish 1
      
    
  3. Verify that the dm_pointer entry for the Synchronization Queue DM specifies the correct database and port:

    - cm dm_pointer db_number ip host_name_or_ip_address port
      
    

    where:

    • db_number is the Synchronization Queue DM database number. The default is 0.0.9.7.

      Important:

      The Synchronization Queue DM database number must match the number in these entries:
      • The dm_db_no entry in the Synchronization Queue DM configuration file (BRM_home/sys/dm_aq/pin.conf).

      • The Publisher DB entry of the Synchronization Queue Publisher definition in the payload configuration file (BRM_home/sys/eai_js/payloadconfig_crm_sync.xml).

    • host_name_or_ip_address is the host name or IP address of the computer on which the Synchronization Queue DM runs.

    • port is the Synchronization Queue DM port number. The default is 17513.

      Important:

      The Synchronization Queue DM port number must match the number in the dm_port entry in the Synchronization Queue DM configuration file (BRM_home/sys/dm_aq/pin.conf).

      Note:

      If you change the location of the Synchronization Queue DM, you need to modify this entry.
  4. Save and close the file.

  5. Stop and restart the CM. See the description for "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

Specifying which Business Events to Send to the Database Queue

You must configure which events the Synchronization Queue DM sends to the database queue by editing the aq_queuenames file.

Note:

  • Only business events that are defined in the payloadconfig file can be sent to the database queue.

  • The Synchronization Queue DM does not send events to the queue until you edit the aq_queuenames file.

To specify which business events to send to the database queue:

  1. Open the BRM_home/sys/dm_aq/aq_queuenames file in a text editor.

  2. Specify the business events to send to the queue:

    • If the queue resides on the database from which the Synchronization Queue DM connects, use this syntax:

      queue_name
      {
        business_events
      }
        
      
    • If the queue resides on a separate database from which the Synchronization Queue DM connects, use this syntax:

      queue_name@database_link
      {
        business_events
      }
        
      

    where:

    • queue_name specifies the queue name. The queue name must match the name you assigned to the queue when you created it.

    • database_link specifies the Oracle database link for connecting to the queue if it resides on another database. Use the database link names you created in "Linking Oracle Databases".

    • business_events specifies which events to send to the queue. You can configure the Synchronization Queue DM to send all business events defined in the payloadconfig file or only specific business events. You can also specify to exclude events from being sent to the database queue. Table 2-1 shows the syntax for each criterion:

      Table 2-1 Synchronization Queue Event Syntax

      To send... ... use this syntax

      All business events

      ALL

      Important: If your system includes IMDB Cache with multiple logical partitions, you must set business_events to ALL.

      Only specific business events

      event_name

      All business events except those specified

      !event_name


      For example, to send all business events to the AQ_QUEUE queue:

      AQ_QUEUE
      {
        ALL
      }
        
      

      To send only ProductInfoChange and DiscountInfoChange events to the queue, separate the events by a space, a new line, or the word OR:

      AQ_QUEUE
      {
        ProductInfoChange
        DiscountInfoChange
      }
        
      

      To send all business events except DiscountInfoChange to the queue located on a database with the alias Portal2:

      AQ_QUEUE@Portal2
      {
        !DiscountInfoChange
      }
        
      
  3. Save and close the file.

Configuring the Synchronization Queue DM Configuration File

During installation, the Synchronization Queue DM installer generates a configuration file (pin.conf) that specifies how to connect to your BRM database and database queue and that contains other configuration settings. The installer populates the connection entries with values from your pin_setup.values file and provides default information for the other configuration entries.

Before you start the Synchronization Queue DM, verify that the configuration file contains accurate information. If necessary, change the values in the file to those specified in the following steps:

  1. Open the Synchronization Queue DM configuration file (BRM_home/sys/dm_aq/pin.conf) in a text editor.

  2. Verify the plugin_name entry:

    -dm plugin_name path/name
      
    

    where:

    • path is the path to the shared library file.

    • name is the shared library file name, such as libplugin_aq10g.so and libplugin_aq11g.so.

  3. Verify the dm_sm_obj entry:

    -dm dm_sm_obj path/name
      
    

    where:

    • path is the path of the shared library file for the EAI DM.

    • name is the name of the shared library file, which is libdm_eai.so for Solaris, Linux, and HP-UX IA64; or libdm_eai.a for AIX.

  4. Verify the queue_map_file entry specifies the path and file that maps the Oracle database queue to the event it is to receive. For example:

    - dm_ifw_sync queue_map_file ./aq_queuenames
      
    

    For more information, see "Specifying which Business Events to Send to the Database Queue".

  5. Verify the sm_database entry:

    - dm sm_database alias_name
      
    

    where alias_name is the alias name of the Oracle queuing database to which the Synchronization Queue DM connects. The value of this entry should be the TNSNAMES.ORA alias, which can be found in the Oracle_home/network/admin/tnsnames.ora file:

  6. Verify the sm_id entry:

    - dm sm_id user_name
      
    

    where user_name specifies the database user name that the Synchronization Queue DM uses to log in to the queuing database.

  7. Verify the sm_pw entry:

    - dm sm_pw password
      
    

    where password is the password for the user specified in the queuing_database_id entry.

  8. Verify the dm_db_no entry:

    - dm dm_db_no database
      
    

    Where database is the number of the database on which dm_aq is installed. The default is 0.0.9.7 / 0.

  9. Verify the dm_port entry:

    - dm dm_port port_number
      
    

    where port_number is the database port for connecting to the DM. The default is 17513.

  10. (Optional) You can also edit these entries to change how often the Synchronization Queue DM attempts to connect to the database queue:

    • -dm_ifw_sync connect_retries

    • -dm_ifw_sync retry_interval

    For more information, see "Configuring the Synchronization Queue DM Database Connection Attempts".

    For other entries you can edit, see the comments in the pin.conf file.

  11. Save and close the file.

Excluding Events Triggered by External Applications

Business events need to be sent to the synchronization queue only when the transactions that generate business events originate with BRM. If a business event is generated by a transaction that originates with an external system, queuing the business event is unnecessary because the external system already knows about the change.

You can suppress business events that are generated due to actions taken on external systems from being published by specifying the external system's login service POID in the Synchronization Queue DM configuration file (pin.conf). The Synchronization Queue DM will not queue business events that include this login service POID.

To suppress business events for transactions that originate on external systems from being published:

  1. Open the Synchronization Queue DM configuration file (BRM_home/sys/dm_aq/pin.conf) in a text editor.

  2. Uncomment the service_poid entry and, if necessary, change the value of the service_poid entry. The default service is /service/admin_client. For example:

    -dm_ifw_sync service_poid 0.0.0.1 /service/admin_client 2
      
    
  3. Save and close the file.

Starting and Stopping the Synchronization Queue DM

To start the Synchronization Queue DM, enter this command at the prompt for Oracle AQ:

pin_ctl start dm_aq
  

To stop the Synchronization Queue DM, enter this command at the prompt for Oracle AQ:

pin_ctl stop dm_aq

Monitoring and Maintaining the Synchronization Queues

This section provides information and guidelines to help you manage your Synchronization Queue DM queues.

The main administrative tasks for database queues are:

Manually Creating a Database Queue on an Oracle Database

The Synchronization Queue DM installer automatically creates a default queue in a specified database. If you need to change the location of your queue or to re-create the queue, you can create a new queue by running the pin_portal_sync_oracle utility.

Important:

To avoid system errors, disconnect or stop your external applications that will connect to the queue you are adding before you run pin_portal_sync_oracle. After creating and testing your queue, you can reconnect the applications that will communicate with the queue.

When you create a queue, you must decide:

  • The database in which to create the queue.

    You can create the queue in the BRM database or in an external database. The best location for the queue depends on your business needs: enqueuing performance will be better when the queue is on the BRM system; dequeuing performance will be better when the queue is on the external application's system.

  • The tablespace in which to create the queue.

    You can create the queue in an existing tablespace or in its own separate tablespace.

    Tip:

    For optimal performance in production systems, create the queue in its own tablespace.

To manually create a database queue:

  1. Stop the Synchronization Queue DM if it is running. See "Starting and Stopping the Synchronization Queue DM".

  2. If you are changing the location of the database queue, drop the existing queue. See "Dropping the Queue and Queue Tables".

  3. If necessary, configure the Oracle database for synchronization queuing. See "Configuring the Database for Advanced Queuing".

  4. If necessary, link the database where the queue will reside to the database where BRM is installed. See "Linking Oracle Databases".

  5. Verify default queue storage and retention time settings in the create_sync_queue.conf file. For information, see:

  6. Create your queue by logging in as user pin and running pin_portal_sync_oracle with the create command:

    Note:

    To create queues, user pin must have Oracle AQ privileges.
    % su - pin
    % pin_portal_sync_oracle.pl create [-l username/password@databaseAlias] [-q queue_name -t queue_table]
      
    

    where:

    -l specifies how to connect to the database.

    -q specifies the name of the queue. If this parameter is not included, the utility creates a queue named AQ_QUEUE.

    -t specifies the name of the queue database table. If this parameter is not included, the utility creates a table named AQ_SYNC.

    See "pin_portal_sync_oracle" for more information about this utility.

  7. Verify that the queue and queue table were created and function properly by running pin_portal_sync_oracle with the test command:

    % pin_portal_sync_oracle.pl test [-q queue_name]
      
    

    The utility enqueues and dequeues 20 test events.

  8. Create a summary report to verify that the queue processed the test events properly by running pin_portal_sync_oracle with the report command:

    % pin_portal_sync_oracle.pl report -r summary 
      
    

    If successful, the report shows all 20 events with a processed state:

    Tue Feb 07                                           page 1
                     Event Summary Report 
    Evt. Stat  Event Name                     Event Count 
    ---------  -----------------------------  ----------- 
    PROCESSED  LongTestEvent                      10 
               ShortTestEvent                     10 
    *********                                 ----------- 
    sum                                            20 
      
    

    If unsuccessful, you must drop and then recreate the queue and queue table. For information, see "Dropping the Queue and Queue Tables".

  9. If necessary, update the queuing database number. See "Specifying the Synchronization Queue DM Database Number".

You can now start the Synchronization Queue DM. See "Starting and Stopping the Synchronization Queue DM".

Generating Queue Reports

You can monitor the events in your database queue by running pin_portal_sync_oracle to generate reports.

Important:

To avoid system errors, disconnect or stop your external applications that will connect to the queue you are adding before you run pin_portal_sync_oracle. After creating and testing your queue, you can reconnect the applications that will communicate with the queue.
  • A summary report lists the number of events set to the READY and PROCESSED states.

  • A detailed report lists each event's ID, state, queuing time, and dequeuing time.

Generating Oracle AQ reports

To create a summary report for Oracle AQ, run pin_portal_sync_oracle using this command:

% pin_portal_sync_oracle.pl report -r summary [-q queue_name]
  

where queue_name specifies the queue name.

To run a detailed report for Oracle AQ, run pin_portal_sync_oracle using this command:

% pin_portal_sync_oracle.pl report -r detail [-q queue_name]
  

where queue_name specifies the queue name.

For information, see "pin_portal_sync_oracle".

Dropping the Queue and Queue Tables

To drop the queue and its queue table, run pin_portal_sync_oracle with the drop command:

Important:

To avoid system errors, disconnect or stop your external applications that will connect to the queue you are adding before you run pin_portal_sync_oracle. After creating and testing your queue, you can reconnect the applications that will communicate with the queue.
% pin_portal_sync_oracle.pl drop [-q queue_name] [-l username/password@DatabaseAlias]
  

where:

queue_name specifies the queue name.

-l specifies how to connect to the database.

The specified queue is dropped from the database and the utility removes the Synchronization Queue DM package, which contains stored procedures for queuing, dequeuing, and purging events.

For more information, see "pin_portal_sync_oracle".

Configuring the Queue Location

By default, pin_portal_sync_oracle creates an Oracle database queue in the tablespace you specified when you installed the Synchronization Queue DM. If you'd like to use a different tablespace, perform one of the following:

Specifying Default Storage Settings by Using the create_sync_queue.conf File

You can specify the default storage settings by using the create_sync_queue.conf file. The data-synchronization queue that you create uses the default settings unless you override them with pin_portal_sync_oracle.

To specify your default storage settings:

  1. Open the BRM_home/apps/pin_aq/create_sync_queue.conf file in a text editor.

  2. Specify the target tablespace and queue size by editing the storage_clause entry:

    Tip:

    For production systems, create your queue in its own, separate tablespace to improve processing performance.
    $storage_clause = "tablespace PIN00 initrans 5 storage (initial 200k next 200k maxextents unlimited pctincrease 0 )";
      
    
  3. Save and close the file.

Specifying Storage Settings by Using the pin_portal_sync_oracle Utility

You can specify the queue's storage settings by using pin_portal_sync_oracle with the create command and the -s parameter. This option overrides the storage settings in the create_sync_queue.conf file.

Important:

To avoid system errors, disconnect or stop your external applications that will connect to the queue you are adding before you run pin_portal_sync_oracle. After creating and testing your queue, you can reconnect the applications that will communicate with the queue.

To specify storage settings by using pin_portal_sync_oracle:

% su - pin
% pin_portal_sync_oracle.pl create [-q queue_name -t queue_table] -s storage_clause
  

where:

  • queue_name specifies the queue name.

  • queue_table specifies the queue table name.

  • storage_clause specifies the queue's storage parameters.

For more information, see "pin_portal_sync_oracle".

Tip:

For production systems, create your queue in its own, separate tablespace to improve processing performance.

Configuring How Often Processed Events are Removed from the Queue

The Oracle Queue Monitor process (QMn) removes from the queue any event set to the PROCESSED state for a specified amount of time. You specified a default retention time when you installed the Synchronization Queue DM. If you'd like to use a different retention time, perform one of the following tasks:

Specifying Default Retention Times by Using the create_sync_queue.conf File

You can specify the default retention time setting by using the create_sync_queue.conf file. The data-synchronization queue that you create uses this default setting unless you override it with pin_portal_sync_oracle.

To specify how often processed events are removed:

  1. Open the BRM_home/apps/pin_aq/create_sync_queue.conf file in a text editor.

  2. Set the retention_time parameter to the amount of time, in seconds, that you want to store processed events in the database queue:

    Tip:

    For production systems, set the retention time to 0 to optimize your processing performance.
    $retention_time = retention_time;
      
    
  3. Save and close the file.

Specifying Retention Times by Using the pin_portal_sync_oracle Utility

You can specify a queue's retention time by using pin_portal_sync_oracle with the create command and the -r parameter. This option overrides the retention time settings in the create_sync_queue.conf file.

Important:

To avoid system errors, disconnect or stop your external applications that will connect to the queue you are adding before you run pin_portal_sync_oracle. After creating and testing your queue, you can reconnect the applications that will communicate with the queue.

To set the retention time by using pin_portal_sync_oracle:

% su - pin
% pin_portal_sync_oracle.pl create [-q queue_name -t queue_table] -r retention_time
  

where:

  • queue_name specifies the queue name.

  • queue_table specifies the queue table name.

  • retention_time specifies the queue's retention time, in seconds.

For more information, see "pin_portal_sync_oracle".

Tip:

For production systems, set the retention time to 0 to optimize your processing performance.

Configuring the Synchronization Queue DM Database Connection Attempts

You can configure how often the Synchronization Queue DM attempts to connect to the database that contains the synchronization queue.

To configure connection attempts:

  1. Open the Synchronization Queue DM configuration file (BRM_home/sys/dm_aq/pin.conf) in a text editor.

  2. Specify the number of times the Synchronization Queue DM should retry to connect to the Oracle database server by editing the connect_retries entry. The default is 1.

    -dm_aq connect_retries number_of_retries
      
    
  3. Specify the interval, in seconds, between each reconnection attempt by editing the retry_interval entry. The default is 0.

    -dm_aq retry_interval interval
      
    
  4. Save and close the file.

  5. Stop and restart the Synchronization Queue DM. See "Starting and Stopping the Synchronization Queue DM".

Disconnecting and Reconnecting the Synchronization Queue DM to the Queue

You can prevent the Synchronization Queue DM from enqueuing business events when you tune or shut down the queuing database by using the pin_ctl utility.

To disconnect from the queue, use the following command:

pin_ctl stop dm_aq
  

To reconnect to the database queue and begin enqueuing business events, use the following command:

pin_ctl start dm_aq

Troubleshooting the Synchronization Queue DM

If an error occurs during a Synchronization Queue DM operation, check the Synchronization Queue DM log file (BRM_home/sys/dm_aq/dm_aq.pinlog) for error codes. For a list of standard errors and codes, see "BRM Error Codes" in BRM System Administrator's Guide.

Database Queue Creation Error

To install the Synchronization Queue DM and create a database queue, the pin user must have Oracle AQ privileges. If pin does not have privileges, you receive the following error when you attempt to install the Synchronization Queue DM or create queues with the pin_portal_sync_oracle utility:

PLS-00201 identifier 'SYS.DBMS_AQ' must be declared
  

To fix this error:

  1. Using SQL*Plus, log in to your database as the SYS user and grant AQ privileges to user pin:

    % sqlplus "sys/password@databaseAlias as sysdba"
      
    SQL> grant execute on dbms_aq to pin;
      
    Grant succeeded.
      
    SQL> grant execute on dbms_aqadm to pin;
      
    Grant succeeded.  
      
    SQL> grant select on sys.gv_$aq to pin;
      
    Grant succeeded.  
      
    SQL> grant execute on dbms_lock to pin;
      
    Grant succeeded.
      
    SQL> grant execute on dbms_aqin to pin;
      
    Grant succeeded. 
      
    SQL> grant execute on sys.dbms_aqin to pin;
      
    Grant succeeded.
      
    
  2. Reinstall the Synchronization Queue DM or create your queue by running the pin_portal_sync_oracle utility manually. See "Manually Creating a Database Queue on an Oracle Database".