Using a Distribution XML File at Runtime

21 Using Event-Driven Publishing 21-1 21 Using Event-Driven Publishing Modern business processes often require the blending of automation into the work environment through behind-the-scenes functions and procedures. Behind-the-scenes tasks can include the automatic production of output such as an invoice that prints automatically when an order is processed, a Web site that is automatically updated with current data, or an automatic e-mail with fresh report output when a transaction is completed. Automatic output in response to events used to be a fairly complicated effort, particularly if you wished to produce the same results possible through interactive, RAD development tools, such as Oracle Reports Developer. To address the requirement of automatic output, Oracle Reports Services includes a scheduling mechanism that enables the invocation of reports on a scheduled basis without requiring additional user interaction. But this leaves one requirement unresolved: the ability to automatically run a report in response to an event in the database, such as the insertion of a record or the change of a value. With the Oracle Reports Services Event-Driven Publishing API, you can automatically run a report in response to an event in the database, such as the insertion of a record or the change of a value. The Event-Driven Publishing API is a PLSQL API that allows for the automatic submission of jobs to Oracle Reports Services from within the database. This chapter provides an overview of the Event-Driven Publishing API and includes examples of its use. It includes the following sections: ■ The Event-Driven Publishing API ■ Debugging Applications that Use the Event-Driven Publishing API ■ Invoking a Report from a Database Event ■ Integrating with Oracle Advanced Queuing

21.1 The Event-Driven Publishing API

The Event-Driven Publishing API is a PLSQL package that provides the basic functions required for the development of procedures that respond to events in the database. Event-driven jobs are submitted using the HTTP protocol. The server assigns a unique job_ident record to every call, useful for tracking the status of the job.

21.1.1 Elements of the API

The API consists of several key elements: 21-2 Publishing Reports to the Web with Oracle Reports Services ■ The SRW Package contains all relevant functions and procedures for submitting jobs, checking job status, and cancelling jobs, as well as manipulating parameter lists. ■ The SRW_ParamList defines a parameter list. A parameter list is the main vehicle for passing values when submitting a job. A parameter list is required for each job submission. It must contain several key parameters. ■ The SRW_ParamList_Object is required for such features as Advanced Queuing, where a parameter list must be stored in the database so that it may be passed along with a message. These API elements are discussed in more detail in the following sections. The API is installed together with Oracle Reports Services Security and Oracle Portal, but neither is required. Installation scripts are also available separately should you want to install the API into a database that does not also hold Oracle Portal: ■ srwAPIins.sql installs the Event-Driven Publishing API. ■ srwAPIgrant.sql grants access privileges to the API. Run this script for each user to whom you will grant access to the API. If everyone may have access, you can run this once and grant access to PUBLIC. ■ srwAPIdrop.sql removes the API.

21.1.2 Creating and Manipulating a Parameter List

A parameter list is a PLSQL variable of type SRW_PARAMLIST. A variable of this type is an array of 255 elements of type SRW_PARAMETER, which itself consists of two attributes: NAME and VALUE. The API provides procedures for manipulating parameter lists, including: ■ Add_Parameter ■ Remove_Parameter ■ Clear_Parameter_List

21.1.2.1 Add_Parameter

Whenever you use a parameter list for the first time, it must be initialized before you can add parameters to it. For example: DECLARE myPlist SRW_PARAMLIST; BEGIN myPlist := SRW_PARAMLISTSRW_PARAMETER,; srw.add_parametermyPlist,myParameter,myValue; END; Both attributes of a parameter NAME and VALUE are of type VARCHAR2 and may not exceed a length of 80 characters for the NAME and 255 characters for the value. The ADD_PARAMETER function has a fourth—optional—attribute, called MODE. MODE determines whether a parameter will be overwritten or an error raised in the event that a parameter with the same name already exists. To specify that an error will be raised in the event of duplicate names, use the constant CHECK_FOR_EXISTANCE. This is the default value for the MODE attribute. To specify that a parameter will be overwritten in the event of duplicate names, use the constant OVERWRITE_IF_ EXISTS.