19 Writing Custom Batch Handlers

This chapter describes the Oracle Communications Billing and Revenue Management (BRM) batch handler feature and explains the requirements for writing custom batch handlers.

About Batch Handlers

Batch handlers are typically used to launch specific applications on a timed or occurrence-driven basis. Each batch handler can be any executable program or script that can be run from a command line. It can be written in Perl, shell script, C, Java, or any other language, so long as it can call an application and update the status and other fields in the BRM database.

Batch handlers run under the control of the Batch Controller. The Batch Controller lets you specify when to run programs or scripts automatically, either at timed intervals or upon creation of certain files, such as log files. For more information about the Batch Controller, see "Controlling Batch Operations" in BRM System Administrator's Guide.

Configuration Parameters

For BRM-related parameters, each batch handler must use a standard pin.conf or Infranet.properties configuration file. For any other parameters, it can also use its own, separate, configuration file.

You can configure the Batch Controller's handler_name.start.string parameter to pass parameters to your batch handler, using any options except –p and –d. The command that the Batch Controller issues is actually:

handler_name.start.string –p handler_poid –d failed_handler_poid

Therefore, the –p and –d options are reserved.

For more about configuration, see "Controlling Batch Operations" in BRM System Administrator's Guide.

What a Batch Handler Has to Do

The Batch Controller uses status values, in the BRM database, to monitor the operation status of batch handlers. Handlers must be carefully coded to set this status to the right values at the right times.

Status

As the handler proceeds, the BRM database keeps track of its status, according to Table 19-1:

Table 19-1 Status Values

Status Keyword Value

NOT_STARTED

–1

STARTING

0

STARTED

1

INTERRUPTED

2

COMPLETED

19

FAILED_TO_START

50

FAILED_TO_COMPLETE

51

You can define other status values for the handler to set, for tracking its own internal status, but these custom status values must be 100 or greater.

Important:

All values 99 and lower are reserved for BRM.

All values in this table, other than STARTED and COMPLETED, are set by the Batch Controller. A handler must never set the status of its handler object to any value other than STARTED, COMPLETED, or a value greater than 99. The controller relies on this value.

Activation

When the Batch Controller detects a file or a time that is to trigger a batch handler, it creates a new object in the BRM database to record that occurrence. It then creates new handler objects in the database, with their status set to NOT_STARTED.

The Batch Controller then checks to see if it can run a handler. Its configuration specifies a maximum number of handler instances for high-load times and a different maximum for low-load times.

If the applicable maximum has not been reached, the Batch Controller:

  1. Sets the handler's status to STARTING.

  2. Extracts the Portal object ID (POID) of the related handler object.

  3. Issues this command:

    handler_name.start.string –p handler_poid

    to start the handler. The start string can include parameter options other than –p and –d.

Handler Actions

Once the batch handler has started, it must:

  1. Read its configuration file or files and configure itself.

  2. Connect to the BRM database.

  3. Find the corresponding handler object in the BRM database, using the POID that was passed with the -p option when the Batch Controller started the handler.

  4. Set the status field to STARTED. The Batch Controller uses this field to monitor the status of running handlers.

    If a handler object continues to show STARTING status after a waiting time specified in the Batch Controller's Infranet.properties file, the Batch Controller changes the status to FAILED_TO_START, and then issues this command to start a replacement copy of the handler:

    handler_name.start.string –p handler_poid –d failed_handler_poid

    The replacement handler gets its own POID in the –p option. It also gets the POID of the failed handler, in the –d option.

  5. Perform its designed activity, which typically includes starting a BRM feature or other application.

  6. Collect the return value of the application that the handler called, and change the status field accordingly:

    1. If the activity has completed satisfactorily, set the status field to COMPLETED.

    2. If the return value indicates that the activity was not successful, the handler must set the status field a value greater than 99. After the configured waiting time, if the related handler object does not show status either COMPLETED or greater than 99, the Batch Controller changes the status to FAILED_TO_COMPLETE. It does not, however, start a replacement copy of the handler.

      Note:

      It is up to you to monitor the BRM database and the Batch Controller's log file, to see if any handler has failed to complete. If a handler does take longer than the timeout period to complete, for any reason, it can still update the status of its handler object to a value greater than 99; to satisfy the Batch Controller's timeout watcher.

  7. End the handler's event session.

  8. Exit.

When the Batch Controller detects the COMPLETED status, it decrements its count of currently running handlers.