A.6 Command Line Keywords - Part 2

A.6.1 DISTRIBUTE

Table A-41 indicates which components can use the DISTRIBUTE keyword.

Description  Use DISTRIBUTE to enable or disable distributing the report output to multiple destinations, as specified by the distribution list defined in the report distribution definition (defined in the Distribution dialog box in Oracle Reports Builder at design time) or a distribution XML file.

Syntax DISTRIBUTE={YES|NO}

Values 

• YES Distribute the report to the distribution list.

• NO Ignore the distribution list and output the report as specified by the DESNAME, DESTYPE, and DESFORMAT parameters. This is fundamentally a debug mode to allow running a report set up for distribution without actually executing the distribution.

Default  NO

Usage Notes The DISTRIBUTE keyword works in close association with the DESTINATION keyword. DISTRIBUTE must have a value of YES for the DESTINATION keyword to take effect. If both these keywords are specified, DESTYPE, DESNAME, and DESFORMAT are ignored if they are also specified.

A.6.2 DTYPE

Table A-42 indicates which components can use the DTYPE keyword.

Description Use DTYPE to specify the format to which to convert the reports or libraries.

Syntax DTYPE={PLDFILE|PLLFILE|RDFFILE|REPFILE|REXFILE|TDFFILE|XMLFILE|JSPFILE|REGISTER}

Values The following values apply:

• PLDFILE The converted PL/SQL libraries will be stored in files in ASCII format.

• PLLFILE The converted PL/SQL libraries will be stored in files containing source code and P-code (compiled PL/SQL).

• RDFFILE The converted report(s) will be stored in one or more report definition files (files with the .rdf extension).

• REPFILE The converted report(s) will be stored in one or more binary runfiles (files with the .rep extension).

• REXFILE The converted report(s) will be stored in one or more text files (files with the .rex extension).

• TDFFILE The report will be converted to a template file (files with the .tdf extension).

• XMLFILE The converted report(s) will be stored in an XML file (files with the .xml extension).

• JSPFILE The converted report(s) will be stored in a JSP file (files with the .jsp extension).

• REGISTER A script file is created to load each report specified by SOURCE into Oracle Portal with the RWWWVREG.REGISTER_REPORT function. Each load function is populated with the necessary information to register the report in Oracle Portal. By running the resulting script file in SQL*Plus against the Oracle Fusion Middleware DB Provider, you can batch register multiple reports in Oracle Portal. For more information, see Appendix C, "Batch Registering Reports in Oracle Portal".

Default REPFILE

Usage Notes 

• When you try to create a .rep file using rwconverter, the source report's PL/SQL is automatically compiled. If there are compile errors, an error message is displayed and the .rep file is not created. To avoid this problem, ensure that you compile the source report's PL/SQL using Program > Compile in Oracle Reports Builder, before you try to create a .rep file.

• When converting a report to a template, only objects in the report's header and trailer sections and the margin area are used in the template. Objects in the main section are ignored.

A.6.3 DUNIT

Table A-43 indicates which components can use the DUNIT keyword.

Description Use DUNIT to specify the destination unit of measurement to which the report should be converted. If specified, DUNIT must differ from the SOURCE report's unit of measurement. If unspecified, the SOURCE report's unit of measurement is used.

Syntax DUNIT={CENTIMETER|CHARACTER|INCH|POINT}

Values 

• CENTIMETER The converted reports will initially use centimeters as the unit of measurement

• CHARACTER The converted reports will initially use characters as the unit of measurement.

• INCH The converted reports will initially use inches as the unit of measurement.

• POINT The converted reports will initially use points as the unit of measurement

Default Null (the report's unit of measurement is used).

A.6.4 ENGINERESPONSETIMEOUT

Table A-44 indicates which command can use the ENGINERESPONSETIMEOUT keyword.

Description  Use ENGINERESPONSETIMEOUT to specify the maximum amount of time (in minutes) for an engine to update the status of the job while running a report in your environment. If it takes longer than this amount of time to update the job status for some reason (for example, due to the engine hanging or a long blocking SQL query), then Reports Server terminates the job.

This parameter overrides the engineResponseTimeOut attribute of the engine element in the Reports Server configuration file. Refer to Section 7.2.1.9, "engine" for information about the engine element.

Syntax ENGINERESPONSETIMEOUT=number

Values 

number A number of minutes (for example, 5).

Default None

A.6.5 ENVID

Table A-44 indicates which command can use the ENVID keyword.

Description  Use ENVID to specify the environment required for the current job request. This keyword allows for dynamic enviroment switching, as described in Section 7.2.2, "Dynamic Environment Switching".

Syntax ENVID=id

Values 

id An identifier that corresponds to an environment element id in the configuration file. The matching environment element defines environment variables that will be used for the current job request. For examples, see Section 7.2.2, "Dynamic Environment Switching".

Default None

A.6.6 EXPIRATION

Table A-46 indicates which command can use the EXPIRATION keyword.

Description  Use EXPIRATION to define how long report output can exist in cache before it is deleted.

See Section 17.12, "Reusing Report Output from Cache" for more information on duplicate job detection. See Section 23.4, "Tuning Reports Server Configuration" and Section 23.8, "Running the Report" for tuning considerations in relation to maxQueueSize and cacheSize values.

Syntax EXPIRATION=time_string

Values 

time_string Is in one of two formats:

• n{unit}, for a number with an optional unit. The unit can be minute(s), hour(s), or day(s). The default unit is minute(s) if no unit is specified.

• {Mon DD, YYYY} hh:mi:ss am|pm {timezone}, for a date/time format. Date information is optional. If it isn't specified, today is assumed. Time zone is also optional. If it isn't specified, the Reports Server's time zone is used. The date/time is always in a US locale. This format is the same as defined in the Java DateFormat.MEDIUM type.

Default None

A.6.7 EXPIREDAYS

Table A-47 indicates which components can use the EXPIREDAYS keyword.

Description Use EXPIREDAYS to specify the number of days after which the Oracle Reports output pushed to Oracle Portal should be expired.

Syntax EXPIREDAYS={PERMANENT|1 day|2 days|3 days|7 days|14 days|31 days|60 days|90 days|120 days}

Values 

• PERMANENT Does not expire.

• n days Expires after n days.

Default None

Usage Notes 

• Use of this keyword is optional to push Oracle Reports output to Oracle Portal.

• Relevant keywords include CONTENTAREA*, EXPIREDAYS, ITEMTITLE, OUTPUTFOLDER*, OUTPUTPAGE, PAGEGROUP, SITENAME*, STATUSFOLDER*, STATUSPAGE.

  * maintained for backward compatibility with Oracle9iAS Portal Release 1 and Oracle WebDB Release 2.2.

A.6.8 FORMSIZE

Table A-48 indicates which components can use the FORMSIZE keyword.

Description Use FORMSIZE to specify the size of the Runtime Parameter Form for the converted report in terms of the destination unit of measurement (specified using DUNIT).

Syntax FORMSIZE=width x height

Values 

width/height Any valid values in the specified unit of measurement.

Default None

Usage Notes 

• For non-character DUNITs, you can use a decimal to specify fractions (for example, 8.5 x 11).

• For more information on the Runtime Parameter Form, see the PARAMFORM keyword.

A.6.9 FROM

Table A-49 indicates which components can use the FROM keyword.

Description  Use FROM to specify the e-mail address of the sender of an e-mail.

Syntax FROM="emailid"

Values 

emailid Any valid e-mail address in the form someone@foo.com.

Default loginid@machine_name

Usage Notes Related keywords include BCC, CC, REPLYTO, and SUBJECT. Note that DESNAME is used to specify the main recipient(s) of the e-mail.

A.6.10 GETJOBID

Table A-50 indicates which components can use the GETJOBID keyword.

Description Use GETJOBID to retrieve the result output of the Reports Server job with job ID n.

Syntax http://your_webserver/reports/rwservlet/getjobid n[?][server=server_name][&authid=username/password]

Values See Syntax

Default None

Usage Notes 

• This keyword is a command that does not require a value; that is, commands are entered by themselves without a corresponding value.

• Job must be successfully finished and present in the Reports Server cache. Use SHOWJOBS to see the current list of jobs.

• Related keywords are SERVER and AUTHID.

A.6.11 GETSERVERINFO

Table A-51 indicates which components can use the GETSERVERINFO keyword.

Description Use GETSERVERINFO to display Reports Server information. You can choose the format (HTML or XML) in which the information is returned through statusformat.

Syntax http://your_webserver/reports/rwservlet/getserverinfo[?][server=server_name][&authid=username/password][&statusformat={html|xml}]

Values See Syntax

Default None

Usage Notes 

• This keyword is a command that does not require a value; that is, commands are entered by themselves without a corresponding value.

• Related keywords are SERVER and AUTHID.

A.6.12 HELP

Table A-52 indicates which components can use the HELP keyword.

Description Use HELP to display a help topic that lists the keywords you can use with the rwservlet command.

Syntax http://yourwebserver/reports/rwservlet/help

or

http://your_webserver/reports/rwservlet/help?command=keyword

Values See Syntax

Default None

Example

http://your_webserver/reports/rwservlet/help?command=keyword

A.6.13 ITEMTITLE

Table A-53 indicates which components can use the ITEMTITLE keyword.

Description Use ITEMTITLE to specify the display name Oracle Portal should use for Oracle Reports output. The name will display in Oracle Portal and link to Oracle Reports output.

Syntax ITEMTITLE=title

Values 

title Any text. Put quotation marks around the value if the value has any character spaces in it or you are specifying the option in the cgicmd.dat key map file (for more information, see Section 17.13, "Using a Key Map File").

Default The report file name

Usage Notes 

• Use of this keyword is optional to push Oracle Reports output to Oracle Portal.

• Relevant keywords include CONTENTAREA*, EXPIREDAYS, ITEMTITLE, OUTPUTFOLDER*, OUTPUTPAGE, PAGEGROUP, SITENAME*, STATUSFOLDER*, STATUSPAGE.

  * maintained for backward compatibility with Oracle9iAS Portal Release 1 and Oracle WebDB Release 2.2.

A.6.14 JOBNAME

Table A-54 indicates which components can use the JOBNAME keyword.

Description Use JOBNAME to specify the name for a job to appear in Reports Queue Manager. It is treated as a comment and has nothing to do with running the job. If JOBNAME is not specified, then Reports Queue Manager shows the report name as the job name.

Syntax JOBNAME=string

Values 

string Any job name.

Default None

Usage Notes JOBNAME can be used when running JSP-based Web reports from the command line.

A.6.15 JOBRETRY

Table A-55 indicates which components can use the JOBRETRY keyword.

Description Use JOBRETRY to specify the maximum number of times a job should be retried after failing. When specified, this keyword takes precedence over the server configuration file entry for the retry attribute of the job element.

Syntax JOBRETRY=retries

Values 

retries An integer that specifies the number of times to retry a job that fails with unexpected errors, after the intial run (total attempts = initial run + JOBRETRY value).

Default 0

Usage Notes Jobs explicitly canceled are not be retried. All jobs that fail with unexpected errors (either engine crash or normal errors) are retried.

If an invalid value is specified for JOBRETRY, Oracle Reports generates runtime exception REP-50003.

A.6.16 JOBTYPE

Table A-56 indicates which components can use the JOBTYPE keyword.

Description Use JOBTYPE to specify the type of job to be processed by the server. You can enter any type of job, as long as Reports Server has an engine to process it.

Syntax JOBTYPE=jobtype

Values 

jobtype A job for which Reports Server has an engine. For example: report (for rwEng engine) or rwurl (for rwURLEng engine).

Default report

Usage Notes The database authentication functionality provided in Oracle Reports is available only when JOBTYPE=report. This is the job type of the default engine (rwEng) provided with OracleAS Reports Services. The database authentication functionality is not available when JOBTYPE specifies a different value (for example, for a custom engine that you develop yourself). This is because a custom engine may require a different format for the connect string, while the Oracle Reports database authentication functionality limits the connect string to the Oracle Reports format user/password@dbname used for the default engine.

A.6.17 JVMOPTIONS

Table A-57 indicates which components can use the JVMOPTIONS keyword.

Description Use JVMOPTIONS to set options for the Java Virtual Machine (JVM).

Syntax 

JVMOPTIONS={options in the Reports Runtime, Reports Builder, Reports Converter, or Reports Server's JVM}

Usage Notes

• The default value -Xmx256M specifies the JVM heap size of 256 MB to avoid the Out Of Memory error when running reports with large graphs or running big reports.

• When the Reports Engine starts up, it checks for JVM options specified in the rwserver.conf file in the jvmoptions attribute of the engine element. For more information, see Section 7.2.1.9, "engine". If specified, the JVM options set in rwserver.conf override the value of the REPORTS_JVM_OPTIONS environment variable. If not specified in rwserver.conf, Oracle Reports uses the JVM options specified by the REPORTS_JVM_OPTIONS environment variable. For more information, see Section B.1.51, "REPORTS_JVM_OPTIONS".

• When running reports with Reports Server, JVM options cannot be set using the REPORTS_JVM_OPTIONS environment variable. For Reports Server, set JVM options on the command line using the JVMOPTIONS command line keyword.

• When running reports with Reports Builder, Reports Runtime, and Reports Converter, JVM options specified on the command line with the JVMOPTIONS command line keyword override JVM options specified by the REPORTS_JVM_OPTIONS environment variable.

Examples

You could use the following command line to start the Reports Server (rwserver) with a 512MB heap space:

rwserver server=servername jvmoptions=-Xmx512M

You could also use the following command line to start Oracle Reports Builder (rwbuilder) with a 512MB heap space:

rwbuilder jvmoptions=-Xmx512M

If multiple options are passed, they must be enclosed in quotes:

rwserver server=servername jvmoptions="-Xmx256M -Xms128M"

A.6.18 KILLENGINE

Table A-58 indicates which components can use the KILLENGINE keyword.

Description Use KILLENGINE to stop a Reports Server engine with the specified engine ID and engine type. For a secured Reports Server, only users with Adminstrator privileges can use this keyword. For an unsecured Reports Server, the user ID and password values for the AUTHID keyword must match the user ID and password specified by the identifier tag in the server.conf configuration file.

Syntax http://your_webserver/reports/rwservlet/killengine[?][server=server_name][&authid=username/password][&type=engine_type]

Values See Syntax

Default None

Usage Notes 

• The engine must currently exist in the Reports Server.

• Use GETSERVERINFO to see the current engines existing in the server.

• Related keywords are GETSERVERINFO, SERVER, and AUTHID.

Example

To kill an engine rwEng-0

http://yourwebserver/reports/rwservlet/killengine0?server=myserver&authid=mydb/password&type=rwEng

A.6.19 KILLJOBID

Table A-59 indicates which components can use the KILLJOBID keyword.

Description Use KILLJOBID to kill a Reports Server job with the specified job ID n.

Syntax http://your_webserver/reports/rwservlet/killjobidn[?][server=server_name][&authid=username/password][&statusformat={html|xml|xmldtd}]

Values See Syntax

Default None

Usage Notes 

• The job must be current (enqueued or scheduled).

• Use SHOWJOBS to see the current list of jobs. The STATUSFORMAT can be set to html (default), xml , or xmldtd to return status in that format. The status information is generated in HTML, XML, or XMLDTD (with an internal DTD subset).

• Related keywords are SHOWJOBS, SERVER, AUTHID, and STATUSFORMAT.

A.6.20 LONGCHUNK

Table A-60 indicates which components can use the LONGCHUNK keyword.

Description LONGCHUNK is the size (in kilobytes) of the increments in which Oracle Reports Builder retrieves a LONG column value. When retrieving a LONG value, you might want to retrieve it in increments rather than all at once because of memory size restrictions. LONGCHUNK applies only to Oracle databases.

Syntax LONGCHUNK=n

Values 

n A number from 1 through 9999 (note that thousands are not expressed with any internal punctuation, for example, a comma or a decimal point). For some operating systems, the upper limit might be lower.

Default 10

Usage Notes LONGCHUNK can be used when running JSP-based Web reports from the command line.

A.6.21 MIMETYPE

Table A-61 indicates which components can use the MIMETYPE keyword.

Description Use MIMETYPE to override the MIME type assigned by the Reports Server when it returns output for the Web. In most cases, the default MIME type is correct, but, in cases where it is not, you can override it with this keyword.

Syntax MIMETYPE=string

Values 

string A valid MIME type specification.

Default None

Usage Notes Oracle Reports Services does not verify the string you enter for MIMETYPE. You must ensure yourself that the string is correct for the returned report output.

Example

MIMETYPE=application/vnd.ms-excel

A.6.22 MODE

Table A-62 indicates which components can use the MODE keyword.

Description  Use MODE to specify whether to run the report in character mode or bitmap. This enables you to run a character-mode report from Oracle Reports Builder.

Syntax MODE={BITMAP|CHARACTER|DEFAULT}

Values 

• BITMAP Run the report in bitmap mode.

• DEFAULT Run the report in the mode of the current component being used.

• CHARACTER On Windows - the Oracle Reports Builder ASCII driver will be used to produce editable ASCII output.

Default DEFAULT

A.6.23 MODULE|REPORT

Table A-63 indicates which components can use the MODULE|REPORT keyword.

Description  Use MODULE or REPORT to specify the name of the report to run.

Syntax  REPORT|MODULE=runfile

Values  

runfile Any valid runfile (that is, a file with an extension of .rep,.rdf,.jsp, or .xml).

Default None

Usage Notes

• If you specify a character-mode report, Oracle Reports Builder displays a warning, then opens the report using a page size of 8.5" x 11" and a form size of 7" x 6".

• To run the report (for example, display it in the Paper Design View), it must be a complete report definition (that is, contain its own data model and layout definition). You cannot run a partial report definition.

• An XML report definition must have the .xml file extension when specified with the MODULE|REPORT keyword.

• If you do not enter a file extension, Oracle Reports Builder searches first for a file with extension .rep, then extension .rdf, then .jsp, and then no extension, using the file path search order to find the file.

A.6.24 NAME

The NAME keyword is used only by the rwbridge component.

Description  Use NAME to specify the name of the Oracle Reports Bridge. The Oracle Reports Bridge component (rwbridge) searches for the Oracle Reports Bridge configuration file, repbrg_bridgename.conf, in ORACLE_HOME/reports/conf. If not found, a new configuration file is created in ORACLE_HOME/reports/conf.

Syntax  NAME=bridgename

Values  

bridgename Any alphanumeric string.

Default None

A.6.25 NONBLOCKSQL

Table A-64 indicates which components can use the NONBLOCKSQL keyword.

Description Use NONBLOCKSQL to specify whether to allow other programs to execute while data is fetched from the database.

Syntax NONBLOCKSQL={YES|NO}

Values 

• YES Other programs can execute while data is being fetched.

• NO Other programs cannot execute while data is being fetched.

Default YES

Usage Notes NONBLOCKSQL can be used when running JSP-based Web reports from the command line.

A.6.26 NOTIFYFAILURE

Table A-65 indicates which components can use the NOTIFYFAILURE keyword.

Description Use NOTIFYFAILURE to specify the recipient(s) of a notification e-mail should a report request fail. Use this keyword when you configure your Reports Server to use the notification class. For more information, see the notification discussion in Configuring Oracle Reports Services.

Syntax NOTIFYFAILURE="emailid"|("emailid", "emailid",...)

Values 

emailid A valid e-mail address in the form someone@foo.com.

Default None

Usage Notes 

• The default notification e-mail templates that are used for the body of the notification e-mail are included with your installation of Oracle Fusion Middleware. The NOTIFYFAILURE template is named failnote.txt, and is located at ORACLE_HOME\reports\template.

• NOTIFYFAILURE can be used when running JSP-based Web reports from the command line.

A.6.27 NOTIFYSUCCESS

Table A-66 indicates which components can use the NOTIFYSUCCESS keyword.

Description Use NOTIFYSUCCESS to specify the recipient(s) of a notification e-mail should a report request succeed. Use this keyword when you configure your Reports Server to use the notification class in the configuration file, or when you select the Enable Email Notification element on the Reports Application Advanced Configuration page in Oracle Enterprise Manager. For more information, see the notification discussion in Chapter 7, "Configuring Oracle Reports Services".

Syntax NOTIFYSUCCESS="emailid"|("emailid", "emailid",...)

Values 

emailid A valid e-mail address in the form someone@foo.com.

Default None

Usage Notes 

• The default notification e-mail templates that are used for the body of the notification e-mail are included with your installation of Oracle Fusion Middleware. The NOTIFYSUCCESS template is named succnote.txt, and is located at ORACLE_HOME\reports\template.

• NOTIFYSUCCESS can be used when running JSP-based Web reports from the command line.

A.6.28 NUMBERFORMATMASK

Table A-67 indicates which components can use the NUMBERFORMATMASK keyword.

Description Use NUMBERFORMATMASK to specify how number values display in your delimited report output.

Syntax NUMBERFORMATMASK=mask

Values Any valid number format mask.

Default None

Usage Notes 

• This keyword can only be used if you have specified DESFORMAT=DELIMITED or DESFORMAT=DELIMITEDDATA.

  Note:

  For valid NUMBERFORMATMASK values see the Oracle Reports online Help topic, "Number Format Mask Syntax."

• NUMBERFORMATMASK can be used when running JSP-based Web reports from the command line.

A.6.29 ONFAILURE

Table A-68 indicates which components can use the ONFAILURE keyword.

Description  Use ONFAILURE to specify whether you want a COMMIT or ROLLBACK performed if an error occurs and the report fails to complete.

Syntax ONFAILURE={COMMIT|ROLLBACK|NOACTION}

Values 

• COMMIT Perform a COMMIT if the report fails.

• ROLLBACK Perform a ROLLBACK if the report fails.

• NOACTION Do nothing if the report fails.

Default 

• ROLLBACK, if a USERID is provided.

• NOACTION, if called from an external source (for example, Oracle Forms Services) with no USERID provided.

Usage Notes 

• The COMMIT or ROLLBACK for ONFAILURE is performed after the report fails. Other COMMITs and ROLLBACKs can occur prior to this one. For more information, see the READONLY command.

• ONFAILURE can be used when running JSP-based Web reports from the command line.

A.6.30 ONSUCCESS

Table A-69 indicates which components can use the ONSUCCESS keyword.

Description  Use ONSUCCESS to specify that either a COMMIT or ROLLBACK should be performed when a report is finished running.

Syntax ONSUCCESS={COMMIT|ROLLBACK|NOACTION}

Values 

• COMMIT Perform a COMMIT when a report is done.

• ROLLBACK Perform a ROLLBACK when a report is done.

• NOACTION Do nothing when a report is done.

Default 

• COMMIT, if a USERID is provided.

• NOACTION, if called from an external source (for example, Oracle Forms Services) with no USERID provided.

Usage Notes 

• The COMMIT or ROLLBACK for ONSUCCESS is performed after the after-report trigger fires. Other COMMITs and ROLLBACKs can occur prior to this one. For more information, see the READONLY command.

• ONSUCCESS can be used when running JSP-based Web reports from the command line.

A.6.31 ORIENTATION

Table A-70 indicates which components can use the ORIENTATION keyword.

Description  ORIENTATION specifies the direction in which the pages of the report will print.

Syntax ORIENTATION={DEFAULT|LANDSCAPE|PORTRAIT}

Values 

• DEFAULT Use the current printer setting for orientation.

• LANDSCAPE Landscape orientation (long side at top and bottom).

• PORTRAIT Portrait orientation (short side at top and bottom).

Default DEFAULT

Usage Notes  

• The ORIENTATION command line keyword is effective only when DESTYPE=PRINTER or DESFORMAT=RTF. The orientation of RTF report output is based on the following order of precedence:

  1. ORIENTATION command line keyword.

  2. ORIENTATION system parameter.

  3. Orientation property for the pertinent report section (Header, Main, or Trailer): Portrait or Landscape.

  4. (If the Orientation property is set to Default) Width and Height properties for the pertinent report section:

     • If Width is greater than Height (for example, 11 x 8.5), then orientation is landscape.

     • If Height is greater than Width (for example, 8.5 x 11), then orientation is portrait.

• For PDF report output, any values specified for the ORIENTATION command line keyword, ORIENTATION system parameter, and Orientation property are ignored. Orientation of the PDF output is based solely on the values of the Width and Height properties, as above.

• If ORIENTATION=LANDSCAPE for a character-mode report, then you must ensure that your printer definition file contains a landscape clause.

• This keyword is not supported when output to a PCL printer on UNIX.