Elements of the API

Using Event-Driven Publishing 21-5 BEGIN myPlist := SRW_PARAMLISTSRW_PARAMETER,; srw.add_parametermyPlist,GATEWAY,http:…; srw.add_parametermyPlist,SERVER,mySVR; srw.add_parametermyPlist,REPORT,MyReport.RDF; srw.add_parametermyPlist,USERID,mesecret; myIdent := srw.run_reportmyPlist; myStatus := srw.report_statusmyIdent; END; You can use the returned status record for fetching information about the status of your job.

21.1.6 Using the Servers Status Record

The status record contains processing information about your job. It contains the same information found in the server queue showjobs. Additionally, it contains information about the files produced for finished jobs and the lineage for scheduled jobs. The most important information in the status record is the current job status and the status text, used in turn to check for runtime errors and their causes. You can use timing information to determine if a job is subject to cancellation because it has exceeded its predicted time for completion. One way to use the status record is to cancel a job. The Event-Driven Publishing API offers a method for cancelling a job that has been submitted to the server. This might be handy if you want to remove a job that has exceeded its allowed time to run or if you simply have scheduled jobs you want to cancel. To cancel a job, use the following procedure: DECLARE myPlist SRW_PARAMLIST; myIdent SRW.JOB_IDENT; myStatus SRW.STATUS_RECORD; BEGIN myPlist := SRW_PARAMLISTSRW_PARAMETER,; SRW.ADD_PARAMETERmyPlist,GATEWAY,http:…; SRW.ADD_PARAMETERmyPlist,SERVER,mySVR; SRW.ADD_PARAMETERmyPlist,REPORT,myReport.RDF; SRW.ADD_PARAMETERmyPlist,USERID,mesecret; myIdent := SRW.RUN_REPORTmyPlist; myStatus := SRW.REPORT_STATUSmyIdent; if myStatus.StatusCode = srw.RUNNING then SRW.CANCEL_REPORTmyIdent; END; As evident in this example, you cancel a report by calling the CANCEL_REPORT procedure SRW.CANCEL_REPORT and passing it the job_ident record of the job you want to cancel. The procedure takes an optional parameter list to enable you to pass any additional parameters you might need.

21.2 Debugging Applications that Use the Event-Driven Publishing API

Because these processes all run behind the scenes, there is no actual place where debugging information is produced during normal execution. Therefore, the API has two procedures that toggle a special debugging mode that produces extensive debugging information through DBMS_OUTPUT: 21-6 Publishing Reports to the Web with Oracle Reports Services ■ SRW.START_DEBUGGING ■ SRW.STOP_DEBUGGING To switch on debugging mode simply call SRW.START_DEBUGGING and to stop it call SRW.STOP_DEBUGGING. The debugging mode must be started immediately before you run your actual logic. It stays on as long as the current instance of the package is loaded. One way you can display this information is by setting SERVEROUT to ON in SQLPLUS before you run your script. In addition to this method of debugging, the API has a set of pre-defined exceptions to be used for error handling. Youll find examples of these exceptions in the srw_ test.sql script provided with your Oracle Reports Services installation.

21.3 Invoking a Report from a Database Event

Database triggers are the primary mechanism for invoking reports using the Event-Driven Publishing API. The Oracle database enables you to define various scopes of triggers that fire in response to various events. To submit a database-driven job, you use the code described in the previous sections within a database trigger. There are many ways to use event-driven publishing. One way is to create security protocols using a trigger that fires whenever a grant is done or a user logs on or off. Another way is to create automated processes that respond to certain types of changes to data in a table. For example, a database trigger could fire when the status of an expense report changes to DONE; in turn, a report could automatically be sent to an employees manager. For example: CREATE TRIGGER EXP_REP_TRG AFTER INSERT OR UPDATE on EXP_REP FOR EACH ROW myPlist SRW_PARAMLIST; myIdent SRW.JOB_IDENT; BEGIN IF :new.ExpStat = DONE THEN myPlist := SRW_PARAMLISTSRW_PARAMETER,; SRW.ADD_PARAMETERmyPlist,GATEWAY,http:…; SRW.ADD_PARAMETERmyPlist,SERVER,fooSVR; SRW.ADD_PARAMETERmyPlist,REPORT,foo.RDF; SRW.ADD_PARAMETERmyPlist,USERID,foobar; SRW.ADD_PARAMETERmyPlist,ExpenseID,:new.ExpID; myIdent := SRW.RUN_REPORTmyPlist; END IF; END; This trigger will fire after each update on the EXP_REP table. In the event the status changes to DONE, the report request is run. If you want your request to run against a key specified in the cgicmd.dat key map file for more information, see Section 18.13, Using a Key Map File , specify the CMDKEY parameter in lieu of the REPORT parameter. If the key contains user ID information, you can omit the USERID parameter as well. For example: CREATE TRIGGER EXP_REP_TRG AFTER INSERT OR UPDATE on EXP_REP FOR EACH ROW myPlist SRW_PARAMLIST; myIdent SRW.JOB_IDENT; BEGIN