Delimited Output Limitations with Using Distribution

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. Using Event-Driven Publishing 21-3

21.1.2.2 Remove_Parameter

Use REMOVE_PARAMETER to remove a parameter from a parameter list. Call the procedure, and pass the parameter list from which you want to remove a parameter along with the name of the parameter you want to remove. For example: DECLARE myPlist SRW_PARAMLIST; BEGIN myPlist := SRW_PARAMLISTSRW_PARAMETER,; srw.add_parametermyPlist,myParameter,myValue; srw.remove_parametermyPlist,myParameter; END;

21.1.2.3 Clear_Parameter_List

To remove ALL parameters from your list, use CLEAR_PARAMETER_LIST. For example: DECLARE myPlist SRW_PARAMLIST; BEGIN myPlist := SRW_PARAMLISTSRW_PARAMETER,; srw.add_parametermyPlist,myParameter,myValue; srw.clear_parameter_listmyPlist; END; This will remove all parameters from your list.

21.1.3 Including non-ASCII Characters in Parameter Names and Values

To use non-ASCII characters in user parameter names and values when using the Event-Driven Publishing API, you must include in your parameter list a parameter called DEFAULTCHARSET, with its value set to a valid character set name. This character set name can be specified with either the databases NLS_CHARACTERSET for example, JA16SJIS or IANA-defined character set name for example, WINDOWS-31J. You must also ensure that the value of the DEFAULTCHARSET parameter matches the defaultcharset parameter specified in the rwservlet.properties file. Oracle Reports Services encodes non-ASCII user parameter names and values using the character set specified by DEFAULTCHARSET, allowing you to use the Event-Driven Publishing API for reports with non-ASCII characters in parameter names and values.

21.1.4 Submitting a Job

A parameter list contains all vital parameters for submitting a job. The job type determines which parameters are required on the list to enable the Reports Server to process the request. The listed parameters are the same ones that you must specify when you submit a job from a browser to Oracle Reports Servlet rwservlet. In such a case, if the job is a report you will need at least the following parameters but may have more: Note: If you do not add a parameter called DEFAULTCHARSET to your parameter list, Oracle Reports Services encodes your user parameter names and values using the databases NLS_CHARACTERSET.