Quick Start with Programming Interface

  Related Topics

Properties

Methods

Events

Predefined Constants

Map of Properties

ResultCodeConstants


Properties

ReportName

DocumentName

ReportsServer

OutputDestination

OutputName

DatabaseUser

DatabasePassword

DatabaseName

ReportMode

UserDefinedParameters

CommandFile

OnRunSuccess

OnRunFailure

ShowParameterForm

PageSize

Orientation

NumberOfCopies

OutputDriver

CurrencyString

ThousandsCharacter

DecimalCharacter

ArrayBufferKBSize

VirtualMemoryKBSize

LongColumnBufferKBSize

SetTransactionReadOnly

AutomaticCommit

NonBlockingSQL

DebuggingChecks

ProfileLogFile

ErrorLogFile

TraceLogFile

TraceMode

TraceLogAll

TraceLogPerformance

TraceLogReportsObjects

TraceLogPLSQLObjects

TraceLogSQLTrace

TraceLogTimeStamp

TraceLogErrors

CallMode

CallTimeout

CallFrequency

JobTolerance

JobName

JobSchedule

SystemUser

SystemPassword

JobNotifyOnSuccess

JobNotifyOnFailure

Distribute

Destination


Methods

GetCommandLine

GetReportStateCode

GetReportStateCodeString

GetReportStateString

RunReport

RunReportSimple

SetDefaults

Terminate Report

GetOutputName


Events

AfterRunReport

BeforeRunReport

RunReportProgress


Predefined Constants

OutputDestinationConstants

ReportModeConstants

CallModeConstants

OrientationConstants

OnRunConstants

TraceModeConstants

ResultCodeConstants


Map of Properties to Command Line Arguments

ActiveX Control Property	Reports Server/Runtime Command Line Argument
ArrayBufferKBSize	ARRAYSIZE
AutomaticCommit	AUTOCOMMIT
CallFrequency	n/a
CallMode	n/a
CallTimeout	n/a
CommandFile	CMDFILE
CurrencyString	CURRENCY
DatabaseUser	USERID
DatabasePassword	USERID
DatabaseName	USERID
DebuggingChecks	RUNDEBUG
DecimalCharacter	DECIMAL
Destination	DESTINATION
Distribute	DISTRIBUTE
DocumentName	REPORT
ErrorLogFile	ERRFILE
JobTolerance	TOLERANCE  (server only)
JobName	JOBNAME  (server only)
JobSchedule	SCHEDULE (server only)
JobNotifyOnSuccess	NOTIFYSUCCESS (server only)
JobNotifyOnFailure	NOTIFYFAILURE (server only)
LongColumnBufferKBSize	LONGCHUNK
NonBlockingSQL	NONBLOCKSQL
NumberOfCopies	COPIES
OnRunFailure	ONRUNFAILURE
OnRunSuccess	ONRUNSUCCESS
Orientation	ORIENTATION
OutputDestination	DESTYPE
OutputDriver	DESFORMAT
OutputName	DESNAME
PageSize	PAGESIZE
ProfileLogFile	PROFILE
ReportMode	MODE
ReportName	REPORT
ReportsServer	SERVER
SetTransactionReadOnly	READONLY
ShowParameterForm	PARAMFORM
SystemUser	AUTHID
SystemPassword	AUTHID
ThousandsCharacter	THOUSANDS
TraceLogFile	TRACEFILE
TraceMode	TRACEMODE
TraceLogAll	TRACEOPTS=TRACE_ALL
TraceLogErrors	TRACEOPTS=TRACE_ERR
TraceLogPerformance	TRACEOPTS=TRACE_PRF
TraceLogPLSQLObjects	TRACEOPTS=TRACE_PLS
TraceLogReportsObjects	TRACEOPTS=TRACE_APP
TraceLogSQLTrace	TRACEOPTS=TRACE_SQL
TraceLogTimeStamp	TRACEOPTS=TRACE_TMS
UserDefinedParameters	user-defined report parameters
VirtualMemoryKBSize	BUFFERS


Map of Command Line Arguments to Properties

Reports Server/Runtime Command Line Argument	ActiveX Control Property
n/a	CallFrequency, CallMode, CallTimeout
ARRAYSIZE	ArrayBufferKBSize
AUTHID	SystemPassword, SystemUser
AUTOCOMMIT	AutomaticCommit
BUFFERS	VirtualMemoryKBSize
CMDFILE	CommandFile
COPIES	NumberOfCopies
CURRENCY	CurrencyString
DECIMAL	DecimalCharacter
DESTYPE	OutputDestination
DESFORMAT	OutputDriver
DESNAME	OutputName
DESTINATION	Destination
DISTRIBUTE	Distribute
ERRFILE	ErrorLogFile
JOBNAME  (server only)	JobName
LONGCHUNK	LongColumnBufferKBSize
MODE	ReportMode
NONBLOCKSQL	NonBlockingSQL
NOTIFYSUCCESS	JobNotifyOnSuccess
NOTIFYFAILURE	JobNotifyOnFailure
ONRUNFAILURE	OnRunFailure
ONRUNSUCCESS	OnRunSuccess
ORIENTATION	Orientation
PAGESIZE	PageSize
PARAMFORM	ShowParameterForm
PROFILE	ProfileLogFile
READONLY	SetTransactionReadOnly
REPORT	DocumentName, ReportName, _ReportName
RUNDEBUG	DebuggingChecks
SCHEDULE (server only)	JobSchedule
TOLERANCE  (server only)	JobTolerance
SERVER	ReportsServer
THOUSANDS	ThousandsCharacter
TRACEFILE	TraceLogFile
TRACEMODE	TraceMode
TRACEOPTS=TRACE_ALL	TraceLogAll
TRACEOPTS=TRACE_ERR	TraceLogErrors
TRACEOPTS=TRACE_PRF	TraceLogPerformance
TRACEOPTS=TRACE_PLS	TraceLogPLSQLObjects
TRACEOPTS=TRACE_APP	TraceLogReportsObjects
TRACEOPTS=TRACE_SQL	TraceLogSQLTrace
TRACEOPTS=TRACE_TMS	TraceLogTimeStamp
USERID	DatabaseUser
user-defined report parameters	UserDefinedParameters
USERID	DatabasePassword, DatabaseName


Map of Properties

Map of Properties to Command Line Arguments

Map of Command Line Arguments to Properties


General page


Data Source page


Output Options page


Parameter Options page


Runtime Options page


Debugging Options page


Scheduling Options page


Server Options page


Notification Options page


System Authentication page


vh


ReportName

The ReportName (or DocumentName) property is the report to run.  You can specify any valid run file (i.e., a file with an extension of .rdf or .rep).  If you do not enter a file extension, Report Builder searches first for a file with extension .rep, then extension .rdf, and then no extension.

dispid(1) for ReportName, dispid(2) for DocumentName
Type: BSTR
Corresponds to REPORT command line parameter.


ReportsServer

The ReportsServer property is the TNS address of the Reports Server.

dispid(3)
Type =BSTR
Corresponds to SERVER command line parameter.


OutputDestination

The OutputDestination property is the type of destination device that will receive the report output.  See OutputDestinationConstants.

dispid(4)
Type: short
Corresponds to DESTYPE command line parameter.


OutputName

The OutputName property is the name of the file, printer, or mail address to which the report output will be sent.  You can specify multiple usernames by enclosing the names in parentheses and separating them by commas (e.g., (<name>, <name>, . . .<name>)).

dispid(5)
Type: BSTR
Corresponds to DESNAME command line parameter.


DatabaseUser

The DatabaseUser property is your ORACLE username and password with an optional Net80 address (not the SYSTEM account).

dispid(6)
Type: BSTR
Corresponds to USERID command line parameter.


DatabasePassword

The DatabasePassword property is the ORACLE password for the database user specified for the DatabaseUser property.

dispid(7)
Type: BSTR
Corresponds to USERID command line parameter.


DatabaseName

The DatabaseName property is the Net80 address of the database that the report will run against.

dispid(8)
Type: BSTR
Corresponds to USERID command line parameter.


ReportMode

The ReportMode property specifies whether to run the report in character mode or bitmap.  This enables you to run a character-mode report from bit-mapped Report Builder or vice versa.  For example, if you want to send a report to a Postscript printer from a terminal (e.g., a vt220), you could invoke character-mode RWRUN60 and run the report with MODE=BITMAP.  See ReportModeConstants.

dispid(9)
Type: short
Corresponds to MODE command line parameter.


UserDefinedParameters

The UserDefinedParameters property is a list of the user parameters for the report in command line format (e.g., myparam1=yes myparam2=10).

dispid(10)
Type: BSTR
Represents user-defined command line parameters string.


CommandFile

The CommandFile property is a file that contains arguments for the run command.  This option enables you to run a report without having to specify a large number of arguments each time you run a report.

dispid(11)
Type: BSTR
Corresponds to CMDFILE command line parameter.


OnRunSuccess

The OnRunSuccess property is whether you want a COMMIT or ROLLBACK performed when the report is finished executing.  See OnRunConstants.

dispid(12)
Type: short
Corresponds to ONRUNSUCCESS command line parameter.


OnRunFailure

The OnRunFailure property is whether you want a COMMIT or ROLLBACK performed if an error occurs and the report fails to complete.  See OnRunConstants.

dispid(13)
Type: short
Corresponds to ONRUNFAILURE command line parameter.


ShowParameterForm

The ShowParameterForm property is whether to display the Runtime Parameter Form when you execute a report.

dispid(14)
Type: boolean
Corresponds to PARAMFORM command line parameter.


PageSize

The PageSize property is the dimensions of the physical page (i.e., the size of the page that the printer outputs) in the form page width x page height.  Note that the page must be large enough to contain the report.  For example, if a frame in a report expands to a size larger than the page dimensions, the report will not run.

dispid(15)
Type: BSTR
Corresponds to PAGESIZE command line parameter.


Orientation

The Orientation property controls the direction in which the pages of the report will print.  See OrientationConstants.

dispid(16)
Type: short
Corresponds to ORIENTATION command line parameter.


NumberofCopies

The NumberofCopies property is the number of copies of the report to print.

dispid(17)
Type: long
Corresponds to COPIES command line parameter.


OutputDriver

The OutputDriver property specifies the printer driver (in bit-mapped environments), the printer characteristics (in character-mode environments), PDF (Portable Display Format), or HTML.

dispid(18)
Type: BSTR
Corresponds to DESFORMAT command line parameter.


CurrencyString

The CurrencyString property is the currency character to be used in number formats.

dispid(19)
Type: BSTR
Corresponds to CURRENCY command line parameter.


ThousandsCharacter

The ThousandsCharacter property is the thousands character to be used in number formats.

dispid(20)
Type: BSTR
Corresponds to THOUSANDS command line parameter.


DecimalCharacter

The DecimalCharacter property is the decimal character to be used in number formats.

dispid(21)
Type: BSTR
Corresponds to DECIMAL command line parameter.


ArrayBufferKBSize

The ArrayBufferKBSize property is the size of the array in kilobytes for use with ORACLE array processing.  Generally, the larger the arraysize, the faster the report will run.

dispid(22)
Type: long
Corresponds to ARRAYSIZE command line parameter.


VirtualMemoryKBSize

The VirtualMemoryKBSize property is the size of the virtual memory cache in kilobytes.  You should tune this setting to ensure that you have enough space to run your reports, but not so much that you are using too much of your system's resources.

dispid(23)
Type: long
Corresponds to BUFFERS command line parameter.


LongColumnBufferKBSize

The LongColumnBufferKBSize property is the size (in kilobytes) of the increments in which Report Builder retrieves a LONG column value.  When retrieving a LONG value, you may want to retrieve it in increments rather than all at once because of memory size restrictions.  LONGCHUNK applies only to ORACLE7.

dispid(24)
Type: long
Corresponds to LONGCHUNK command line parameter.


SetTransactionReadOnly

The SetTransactionReadOnly property requests read consistency across multiple queries in a report.  When accessing data from ORACLE, read consistency is accomplished by a SET TRANSACTION READ ONLY statement (refer to your Oracle7 Server SQL Language Reference and Oracle8 Server SQL Reference manuals for more information on SET TRANSACTION READ ONLY).

dispid(25)
Type: boolean
Corresponds to READONLY command line parameter.


AutomaticCommit

The AutoCommit property specifies whether database changes (e.g., CREATE) should be automatically committed to the database.  Note that some non-ORACLE databases (e.g., SQL Server) require that AUTOCOMMIT=YES.

dispid(26)
Type: boolean
Corresponds to AUTOCOMMIT command line parameter.


NonBlockingSQL

The NonBlockingSQL property specifies whether to allow other programs to execute while Report Builder is fetching data from the database.

dispid(27)
Type: boolean
Corresponds to NONBLOCKSQL command line parameter.


DebuggingChecks

The DebuggingChecks property is whether you want extra runtime checking for logical errors in the report.

dispid(28)
Type: boolean
Corresponds to RUNDEBUG command line parameter.


ProfileLogFile

The ProfileLogFile property is the name of a file in which you want to store performance statistics on report execution.  If you specify a filename, Report Builder calculates statistics on the elapsed and CPU time spent running the report.

dispid(29)
Type: BSTR
Corresponds to PROFILE command line parameter.


ErrorLogFile

The ErrorLogFile property is the name of a file in which you want Report Builder to store all error messages that are issued during the execution of your report.

dispid(30)
Type: BSTR
Corresponds to ERRFILE command line parameter.


TraceLogFile

The TraceLogFile property is the name of the file in which Report Builder logs trace information.

dispid(31)
Type: BSTR
Corresponds to TRACEFILE command line parameter.


TraceMode

The TraceMode property indicates whether Report Builder should add the trace information to the file or overwrite the entire file.  See TraceModeConstants.

dispid(32)
Type: short
Corresponds to TRACEMODE command line parameter.


TraceLogAll

The TraceLogAll property indicates that all possible trace information should be logged in the trace file.  This property overrides all other trace properties.

dispid(33)
Type: boolean
Corresponds to TRACEOPTS=TRACE_ALL Command line parameter.


TraceLogPerformance

The TraceLogPerformance property indicates that performance statistic should be logged in the trace file.

dispid(34)
Type: boolean
Corresponds to TRACEOPTS=TRACE_PRF command line parameter.


TraceLogReportsObjects

The TraceLogReportsObjects property indicates that trace information on all of the report objects should be logged in the trace file.

dispid(35)
Type: boolean
Corresponds to TRACEOPTS=TRACE_APP command line parameter.


TraceLogPLSQLObjects

The TraceLogPLSQLObjects property indicates that trace information on all of the PL/SQL objects should be logged in the trace file.

dispid(36)
Type: boolean
Corresponds to TRACEOPTS=TRACE_PLS command line parameter.


TraceLogSQLTrace

The TraceLogSQLTrace property indicates that trace information on all of the SQL should be logged in the trace file.

dispid(37)
Type: boolean
Corresponds to TRACEOPTS=TRACE_SQL command line parameter.


TraceLogTimeStamp

The TraceLogTimeStamp property indicates that a time stamp should be entered for each entry in the trace file.

dispid(38)
Type: boolean
Corresponds to TRACEOPTS=TRACE_TMS command line parameter.


TraceLogErrors

The TraceLogErrors property indicates that error messages and warnings should be logged in the trace file.

dispid(39)
Type: boolean
Corresponds to TRACEOPTS=TRACE_ERR command line parameter.


CallMode

The CallMode property indicates whether to run the report via the Reports Server or the Reports Background Engine.  If you are running to the Reports Server, you also specify whether to use a synchronous or asynchronous call.  See CallModeConstants.

dispid(40)
Type: short.


CallTimeout

The CallTimeout property is the length of time to wait for a response from the server before timing out.

dispid(41)
Type: long.


CallFrequency

The CallFrequency property is how often the Reports Server should be polled for job status.

dispid(42)
Type: long


JobTolerance

The JobTolerance property specifies a time tolerance for duplicate jobs.  If exactly the same report has been started with the same parameters within the specified JobTolerance, the current request is recognized as a duplicate job and the cached output is reused rather than re-executing the report.

dispid(43)
Type: long
Corresponds to TOLERANCE command line parameter.


JobName

The JobName property is the name of the job as it will appear in the Reports Queue Manager.

dispid(44)
Type: BSTR
Corresponds to JOBNAME command line parameter.


JobSchedule

The JobSchedule property is a scheduling command that indicates when and how often the report should be run.  It uses AT scheduling command syntax.  For example, hourly_from_09:00am_December_25,_1999.

dispid(45)
Type: BSTR
Corresponds to SCHEDULE command line parameter .


SystemUser

The SystemUser property is the WebDB username and password that enables you to run reports to the restricted Reports Server.

dispid(55)
Type: BSTR
Corresponds to AUTHID command line parameter.


SystemPassword

The SystemPassword property is the password for the user specified for the SystemUser property.

dispid(56)
Type: BSTR
Corresponds to AUTHID command line parameter.


JobNotifyOnSuccess

  Related Topics

The NotifyOnSuccess property sends a notification message to the specified e-mail address or addresses when a job runs successfully. The server executable reads a notification content template that is specified in the server’s configuration file.

The SUCCNOTEFILE parameter must be defined in the server’s configuration file for the server to send the notification message. See your system administrator for more information. Note

The notification message indicates the job name, the report server, and the time the job successfully finished.

Dispid(57)
Type: BSTR
Corresponds to the NOTIFYSUCCESS command line parameter .


If the server cannot find the template file or the server configuration file does not include the SUCCNOTEFILE or FAILNOTEFILE parameters, the server will log an error in the server’s log file only if the LOGOPTION parameter is specified. See your system administrator for more information.


JobNotifyOnFailure

  Related Topics

The NotifyOnFailure property sends a notification message to the specified e-mail address or addresses when a job fails to run. The server executable reads a notification content template that is specified in the server’s configuration file.

The FAILNOTEFILE parameter must be defined in the server’s configuration file for the server to send the notification message. See your system administrator for more information. Note

The notification message indicates the job name, the server name, the time the job was terminated, and the reason for the failure.

dispid(58)
Type: BSTR
Corresponds to the NOTIFYFAILURE command line parameter .


Distribute

The Distribute property enables or disables distributing the report output to multiple destinations, as specified by the distribution list defined the Distribution dialog box or a DST file.

dispid(59)
Type: BOOLEAN
Corresponds to the DISTRIBUTE command line parameter.


Destination

The Destination property allows you to specify the name of a DST file  that defines the distribution for the current run of the report.

dispid(60)
Type: BSTR
Corresponds to the DESTINATION command line parameter.


GetCommandLine

The GetCommandLine method constructs a command line based on the current values of the control properties.  It then returns the constructed command line as a string.

dispid(49),
Prototype: BSTR GetCommandLine();


GetReportStateCode

The GetReportStateCode method retrieves the current state (result or progress code) of a specific report (ReportHandle).  The codes returned are the same ones passed in control events.  See ResultCodeConstants.

dispid(50),
Prototype: long GetReportStateCode([in] long ReportHandle);


GetReportStateCodeString

The GetReportStateCodeString method retrieves a user-readable string for the specified result or progress code.  See ResultCodeConstants.

dispid(51)
Prototype: BSTR GetReportStateCodeString([in] long Code);


GetReportStateString

The GetReportStateString method retrieves a user-readable result or progress string for the current state of a specified report (ReportHandle).

dispid(52)
Prototype: BSTR GetReportStateString([in] long ReportHandle);


RunReport

The RunReport method runs a report with the Reports Server or the Reports Background Engine using the current values of the control properties.  It returns ReportHandle and a result/progress code for the report submission (not the report execution result).  Note that this call is always asynchronous and never waits for a report run to finish.  If you want synchronous behavior for the report, you should use further progress codes passed through control events or returned by the GetReportStateCode method to organize it programmatically.  See ResultCodeConstants. for result and progress codes.

dispid(46)
Prototype: long RunReport([in, out] long ReportHandle);


RunReportSimple

The RunReportSimple method is a wrapper around the RunReport method.  It runs a report with the the Reports Server or the Reports Background Engine without generating control events (CallFrequency=0; CallTimeout=0; CallMode=Local/Async).  No ReportHandle is passed out.

dispid(47)
Prototype: long RunReportSimple();


SetDefaults

The SetDefaults method forces all control properties to assume their default values.  This method does not affect the property values of reports that are already running.

dispid(48)
Prototype: void SetDafaults();


Terminate Report

The TerminateReport method terminates the run of specified report (ReportHandle).  It returns result codes that are the same as the ones passed in control events. See ResultCodeConstants.

dispid(53)
Prototype: long TerminateReport([in] long ReportHandle);


GetOutputName

The GetOutputName method gets the filename of a report’s output when the output was sent to the Reports Server’s cache, orODToServerCache.  Note that to get files from the Reports Server cache, you must share the filesystem where the cache is located.

dispid(54)
Prototype: BSTR GetOutputName([in] long ReportHandle);


BeforeRunReport

The BeforeRunReport event fires just before the control submits a report for execution.

dispid(2)
Prototype: void AfterRunReport([in] long ReportHandle, [in] long ResultCode);


AfterRunReport

The AfterRunReport event fires just after the control is finished running the report.  It indicates the result of the report run.  See ResultCodeConstants.

dispid(1)
Prototype: void BeforeRunReport([in] long ReportHandle);


RunReportProgress

The RunReportProgress event fires while the control is in the process of running the report.  It indicates the report’s progress at the specified frequency.  See ResultCodeConstants.

dispid(3)
Prototype: void RunReportProgress([in] long ReportHandle, [in] long ProgressCode);


OutputDestinationConstants

OutputDestinationConstants are the constants used for OutputDestination property values.

Constant	Description
orODInReport = 0	Uses the value specified in the report file.
orODToLocalFile = 1	Outputs the report to a local file.
orODToFile = 2	Outputs the report to a file.
orODToPrinter = 3	Outputs the report to a printer.
orODToMail = 4	Outputs the report to e-mail.
orODToScreen = 5	Outputs the report to screen.
orODToPreview = 6	Outputs the report to Previewer (using printer fonts).
orODToServerCache = 7	Outputs the report to the Reports Server cache.
Usage Notes

•	If you are using the Reports Server and you specify orODToLocalFile = 1, the output will be transferred to the local filesystem.  If you specify orODToFile = 2, output is sent to a file on the Reports Server side.

•	orODToScreen = 5 and orODToPreview = 6 are only valid for the Reports Background Engine (rwrbe60.exe)


ReportModeConstants

ReportModeConstants are the constants used for the ReportMode property values.

Constant	Description
orRMInReport = 0	Uses the value specified in the report file.
orRMBitmapMode = 1	Runs the report in bit-mapped mode.
orRMCharacterMode = 2	Runs the report in character mode.


CallModeConstants

CallModeConstants are the constants used for the CallMode property values.

Constant	Description
orCMCallLocal = 0	Submits the report to the Reports Background Engine by invoking the rwisv60.exe executable which in turn calls rwrbe60.exe.  When the OROCX_USE_RUNTIME environment variable is defined, the runtime executable, rwrun60.exe, will be invoked instead.
orCMCallSync = 1	Calls the Reports Server in Synchronous Communication mode.  This causes less network traffic because the RPC call is used only once for job submission.
orCMCallAsync = 2	Calls the Reports Server in Asynchronous Communication mode.  This option has the advantage of knowing the precise state of the report during its run (i.e. number in queue, server warnings and error messages, etc.).


OrientationConstants

OrientationConstants are the constants used for the Orientation property values.

Constant	Description
orOInReport = 0	Uses the value specified in the report file.
orOInPrinter = 1	Uses the orientation currently selected by the printer.
orOPortrait = 2	Uses portrait orientation.
orOLandscape = 3	Uses landscape orientation.


OnRunConstants

OnRunConstants are the constants used for the OnRunSuccess and OnRunFailure property values.

Constant	Description
orORInReport = 0	Uses the value specified in the report file.
orORCommit = 1	Performs a COMMIT when the report is finished.
orORRollback = 2	Performs a ROLLBACK when the report is finished.
orORNoAction = 3	Does nothing when the report is finished.


TraceModeConstants

TraceModeConstants are the constants used for the TraceMode property values.

Constant	Decsription
orTMInReport = 0	Uses the value specified in the report file.
orTMAppend = 1	Appends new information to the existing trace log file.
orTMReplace = 2	Overwrites the existing trace log file with new information.


ResultCodeConstants

ResultCodeConstants are the constants used as error, progress, and result codes in control events and methods.

Constant	Description
orResNoError = 0	General Success code.
orResFailed = 1	Error occurred in Reports ActiveX control.
orResNoComm = 10	Error: Cannot initialize connection to the Reports Server.  Make sure that the network is configured properly and the Reports Server is running.
orResNoMemory = 11	Error: Not enough memory.
orResNoResources = 31	Error: Cannot run report.  System Resources are exhausted: Cannot create thread or thread synchronization object.
OrResParInvalid = 32	Error: Cannot run report.  Value of one or several properties is invalid.  Check values of the control properties and try again.
OrResParMissing = 33	Error: Cannot run report.  Value of one or several mandatory properties (ReportName, DatabaseUser, and ReportsServer, unless local run) where not specified). Specify necessary properties and try again.
orResLocalExeNotFound = 34	Error: Cannot run report.  You chose to run the report using the Reports Background Engine executable. It is installed improperly or not found.
OrResTimeout = 35	Specified CallTimeout was reached before the report ran successfully.  Report run state terminated on timeout.
orResTooManyConnections = 36	Error: Cannot run report.  Too many active connections to the Reports Server exist.  Try again later.
orResListenerNone = 37	Error: Cannot run report.  The Reports Server is not answering.  Make sure it is properly installed and running.
orResListenerBusy = 38	Error: Cannot run report.  The Reports Server is busy and refuses to connect.  Try again later.
orResListenerBad = 39	Error: Cannot run report.  Cannot connect to the Reports Server.  Network tnsname of Reports Server is invalid or unknown.  Check your network setup.
orResBadCommandLine = 40	Error: Cannot run report.  Reports Server rejects passed command line. Check values of control properties.
orResBadSchedule = 41	Error: Cannot run report.  Reports Server rejects passed scheduling parameters. Check values of control properties.
orResServerShutdown = 42	Error: Cannot run report.  Reports Server is shutting down.  Try again later.
orResServerError = 43	Error: Cannot run report.  Error occurred while queuing report on Reports Server.  Server resources might be exhausted.  Try again later.
orResExecutableBad = 44	Error: Cannot run report.  Runtime executable is corrupted or has wrong binary format.
orResNoSuchJob = 45	Job does not exist or is already finished.
orResJobEnqueued = 46	Report is running: Job is queued by Reports Server and scheduled for run.
orResJobRunning = 47	Report is running: Job is being run by Reports Server Engine.
orResJobParForm = 48	Report is running: Reports Server Engine displaying report parameter form and awaiting user input.
orResJobPreviewer = 49	Report is running: Reports Server Engine displaying report preview and awaiting user input.
orResJobFinished = 50	Report ran successfully.
orResJobTerminated = 51	Report is finished. Error(s) occurred during report run.
orResJobCrashed = 52	Reports Server Fatal Error: Reports Server engine crashed while trying to run report.
orResJobCancelled = 53	Report run is finished. Report job was canceled on user's or administrator's request.
orResSecurityProblems = 54	Error: Cannot perform requested operation due to security problems.  Check your privileges, userid, and password strings.
orResCallServerInProgress = 55	Communicating with the Reports Server.  Report is running.
orResCallServerSubmitted = 56	Waiting for permission to communicate with Reports Server.
orResCallServerInit = 57	Preparing report run request for submission to Reports Server.
orResExecutingLocal = 58	Running report using Reports Background Engine on local machine.
orResJobOpeningReport = 59	Report is running: Reports Server engine opening and reading report definition file.
orResOutputDestinationInvalid = 60	Error: Cannot run report.  Value of OutputDestination property is set to ToScreen or ToPreview.  Interactive destination is allowed only for local run.  Change value and try again.
orResLocalFileNotFound = 61	Error: Cannot run report.  The value of one of the properties is a filename that cannot be opened.  Correct the filename and try again.
orResLocalFileBad = 62	Error: Cannot run report.  Value of one of the properties specifies a filename which cannot be created.  Correct the filename and try again.
orResOutputTransfer = 63	Report was run successfully. Transferring report output from remote server to a local file.
orResNoOutputTransfer = 64	Report is finished with error: Report output is not available or cannot be transferred to a local filesystem.  It may be because the report run was terminated with an error or a file input/output error occurred.
OrResLocalOutputNameBad = 65	Report ran successfully, but the report output cannot be transferred to a local file system.  The local filename may be bad or it cannot be created or opened.
orResServerIOFailed  = 66	Error: Reports Server detected a file input/output failure.
orResClientIOFailed = 67	Error: File input/output failure on local machine. Check local file system.
orResBadJobTolerance  = 68	Error: Unable to interpret the time tolerance. Check value of a JobTolerance property.
orResBadReportName  = 69	Report name was not specified. Check the value of a ReportName property.
orResBadDatabaseUser = 70	Database login was not specified. Check the values of the DatabaseUser, DatabasePassword, DatabaseName.
orResListenerNLS = 71	Cannot connect to the Reports Server. The Reports Server with the specified TNS name is using a different character set than you and conversion is not possible.


Messages and Error Handling

•	Control properties don’t generate exceptions and can be gotten or set at any time.  Invalid values are ignored.

•	Informational methods (such as GetCommandLine, SetDafaults, GetReportStateCode, GetReportStateCodeString, and GetReportStateString) also never generate exceptions.

•	If the submission of a report for execution fails for any reason, an OLE Automation exception occurs.  If submission is successful, the control returns a report handle which can be used to track the report’s progress (e.g., in the RunEventProgess event).

•	The report is considered to be running from the time the report handle is returned to the time the AfterRunReport event is fired.

•	The control uses a single status code throughout the report’s execution.  It is returned by the RunReport, TerminateReport, and GetReportStateCode methods.  It is passed to the AfterRunReport and RunReportProgress events.

•	The status code does not represent any report-specific information (e.g., report number in server queue and server error and warning messages).

•	The control container script can work with code values or map status codes to strings by using the GetReportStateCodeString or GetReportStateCode methods.

•	Any report-specific status can be returned only during the report’s execution.  For containers without event support, the status of the report can be polled in a loop.  The report handle will be valid for some time after the report run was finished and a stalled handle will not cause faults.


Displays a file dialog box from which you can choose the report to run.


Is the name of the report that you want to run.  Enter the name or click the browse button to choose one.


Is the type of destination device to which you want to send the report output (Screen, File, Printer, Preview, Mail, Server cache, Distribution file).


Displays a file dialog box from which you can choose a file for report output, a printer for printer output, or destination file for distribution.


Is the name of the file, printer, mail address, or destination file name to which you want to send the report output.  Enter a name or click the browse button to choose one.


Is the name of the Reports Server you want to run the report.  Enter the name of a valid Reports Server.


Is the database username.  Enter your database username, and, optionally, password and database name (in the format userid/password@database ).


Is the password for the specified database user.  Enter the correct password (the characters you type will appear as asterisks).


Is the name of the database to which you want to connect.  Enter the name of a valid database.


Means that the mode in which to run the report is taken from the report definition.


Means that the report should be run as a bit-mapped report.


Means the report should be run in character mode.


Means that the report's orientation (landscape or portrait) will be taken from the report definition.


Means that the report's orientation (landscape or portrait) will be the currently selected orientation of the printer.


Means that the report's orientation will be portrait.


Means that the report's orientation will be landscape.


Is the dimensions of the report.  Enter a valid width and height (of the form width x height) or select from the list of values.


Is the format in which you want the report output.


Is the number of copies of the report output that you want produced.  Enter an integer greater than zero.


Is whether to display the Runtime Parameter Form before running the report.  Select or deselect the check box as desired.  The Runtime Parameter Form is a dialog that enables you to change the values of report parameters before the report is run.


Is a string which specifies values for the report’s user parameters.  Enter a string of the form parameter1name=value parameter2name=value . . . or select a string from the list of values.


Is a browse button that displays a file dialog from which you can select a command file.;


Is the name of a command file that specifies parameters for the report.  Enter a filename or click the browse button to choose one.


Is whether you want read consistency across multiple queries in a report.  Select or deselect the check box as desired.  When accessing data, read consistency is accomplished by a SET TRANSACTION READ ONLY statement.


Is whether database changes (e.g., CREATE) should be automatically committed to the database.  Select or deselect the check box as desired.  Note that some non-Oracle databases (e.g., SQL Server) require that database changes be automatically committed.


Is whether to allow other programs to execute while Report Builder is fetching data from the database.  Select or deselect the check box as desired.


Is whether you want a COMMIT or ROLLBACK performed when the report is finished executing.  Select or deselect the check box as desired.


Is whether you want a COMMIT or ROLLBACK performed if an error occurs and the report fails to complete.  Select or deselect the check box as desired.


Is the string to be used for the currency character in number formats.  Enter a valid currency string.


Is the thousands character to be used in number formats.  Enter a valid thousands character.


Is the decimal character to be used in number formats.  Enter a valid decimal character.


Is the size of the array in kilobytes for use with Oracle array processing.  Enter a valid number.  Generally, the larger the arraysize, the faster the report will run.


Is the size of the virtual memory cache in kilobytes.  Enter a valid number.


Is a browse button that displays a file dialog from which you can select an error file.


Is the name of a file in which you want to store all error messages that are issued during the execution of your report.  Enter a filename or click the browse button to choose one.


Is a browse button that displays a file dialog from which you can select a log file.


Is the name of a file in which you want to store performance statistics on report execution.  Enter a filename or click the browse button to choose one.


Is a browse button that displays a file dialog from which you can select a trace log file.


Is the name of the file in which to log trace information.  Enter a filename or click the browse button to choose one.


Is whether trace information should be added to the end of the file or overwrite the entire file.  Choose the desired behavior from the list.


Is whether error messages and warnings should be logged in the trace file.  Select or deselect the check box as desired.


Is whether performance statistic should be logged in the trace file.  Select or deselect the check box as desired.


Is whether information on all of the report objects should be logged in the trace file.  Select or deselect the check box as desired.


Is whether information on all of the PL/SQL objects should be logged in the trace file.  Select or deselect the check box as desired.


Is whether information on all of the SQL should be logged in the trace file.  Select or deselect the check box as desired.


Is whether a time stamp should be entered for each entry in the trace file.  Select or deselect the check box as desired.


Means that you want the report to run immediately.


Means that you want to specify a start time and date on which the report runs.


Is the time when the report will run.  Enter a time or use the up/down buttons to choose one.


Is the time when the report will run.  Enter a time or use the up/down buttons to choose one.


Is the date when the report will run.  Enter a date or use the up/down buttons to choose one.


Is the date when the report will run.  Enter a date or use the up/down buttons to choose one.


Means that the report will run once.


Means that the report will be scheduled to run at a specified interval.


Is the number of units between scheduled runs of the report (e.g., if the unit is hours and you specify two, the report will be run every two hours).  Use the up/down arrows to choose a number.


Is the number of units between scheduled runs of the report (e.g., if the unit is hours and you specify two, the report will be run every two hours).  Use the up/down arrows to choose a number.


Is the units to be used in defining the interval at which the report will be run (e.g., hours).


Means the job will run monthly on the specified day (e.g., the first Monday of each month).


Is the occurrence of the specified day in which the job will run (e.g., first). Use the up or down arrows to choose a value.


Is the day on which the job will run. Use the up or down arrows to choose the day.


Means that the job will run on the last day of each month on or before the specified date (e.g., the last weekday of each month on or before the 15th).


Is the last day in which the job will run (e.g., Monday, weekday). Use the up or down arrows to choose a day.


Is the date on or before which the job will run (e.g., 15th). Enter a date or use the up or down arrows to one.


Is the date on or before which the job will run (e.g., 15th). Enter the date or use the up or down arrows to choose one.


Means that the server will attempt to rerun a failed job at a specified interval.


Is the number of times to retry running a job after it has failed. Enter a number or use the up or down arrows to choose one.


Is the number of times to retry running a job after it has failed. Enter a number or use the up or down arrows to choose one.


Is the time between scheduled retries that the server will attempt to rerun a job (e.g., 1 hour). Enter the time or use the up or down arrows to choose one.


Is the time between scheduled retries that the server will attempt to rerun a job (e.g., 1 hour). Enter the time or use the up or down arrows to choose one.


Is the unit of time between scheduled retries that the server will attempt to rerun a job (e.g., hours). Use the up or down arrows to choose the unit of time.


Means that you want to use the Reports Background Engine on the client to run the report.


Means that you want to make a synchronous call to the Reports Server to run the report.  The call will not return until the report execution is complete.


Means that you want to make an asynchronous call to the Reports Server to run the report.  The client will only contact the Reports Server when it needs information from it (e.g., to submit a request to run a report or obtain progress information).


Is the frequency at which the Reports Server will be polled for report progress information.  Use the up/down arrow buttons to choose a frequency in seconds.


Is the frequency at which the Reports Server will be polled for report progress information.  Use the up/down arrow buttons to choose a frequency in seconds.


Is the length of time to wait for a response from the server before timing out.


Is the name associated with the report in the queue.  Enter a valid string.


Is the e-mail address to which a notification message is sent when a job runs successfully. Enter a valid e-mail address or addresses.


Is the e-mail address to which a notification message is sent when a job fails to run. Enter a valid e-mail address or addresses.


Is the WebDB username that authenticates the user to the restricted Reports Server.  Enter the username, and optionally the password (in the format username/password).


Is the password for the specified WebDB username.  Enter the correct password (the characters you type will appear as asterisks).


About the Reports ActiveX control

The Reports ActiveX is an OLE custom control that exposes the Reports Server and the Reports Background Engine through industry-standard OLE ActiveX technology.  The Reports ActiveX enables you to run reports from any ActiveX container.  As with any other ActiveX control, a container can get or set the control’s properties and invoke the control’s methods at any time.  Note that the Reports ActiveX is just one of the Reports Server’s clients.

  Reports ActiveX Architecture

When the RunReport method is invoked to submit a report for execution, the control performs the following:

1	Creates a snapshot of properties and initiates a communication connection with the Reports Server or Reports Background Engine.

2	Submits a report for execution by creating a command line from the properties and sending it to the Reports Server or the Reports Background Engine.  Note that only minimal parameter validation is performed.

3	If there are no problems with the report submission, RunReport returns successfully.

When a report starts to execute, the ActiveX control tracks the report execution.  How the report execution is tracked depends on the communication mode chosen to run the report.  In all cases, the control will generate BeforeRunReport and AfterRunReport control events.  If you request updates on progress at regular intervals (via the Call Frequency property), the RunReportProgress event is also generated at the requested frequency.


About the Reports Server

The Reports Server enables you to run your reports on a remote machine.  The Reports Server takes requests from clients to run reports.  These requests are entered into a queue and dispatched to run when one of the Reports Server’s runtime processes becomes available.  The Reports Server can be queried for the status of requests.  A scheduling command may accompany non-interactive report requests.  The scheduling command specifies that the report be run at a given time and frequency.


System requirements

The Reports ActiveX control is a Win32 application which takes advantage of multithreading.  As with any other ActiveX control, it is a DLL.  It uses several other DLLs and requires them for normal functioning.  Reports ActiveX uses static linkage with dependent DLLs.  This means that the Reports ActiveX DLL cannot be loaded successfully unless all of its dependent DLLs are accessible to the system.

For best results, use the Oracle Installer for installing all necessary components.

Reports ActiveX Dependent DLLs

•	Windows System Libraries

•	Microsoft MFC 4.1 library, MFC40.DLL, and Microsoft C++ 4.1 Runtime Library MSVCRT40.DLL

•	Oracle CORE, CORE40.DLL

•	Oracle National Language Support Runtime, NLSRTL33.DLL

•	Reports Server Utilities and Communication, ZRC60.DLL and all DLLs upon which this library depends

•	Oracle RPC, NL80.DLL, NS80.DLL, NT80.DLL and all dependent libraries

The Oracle Component libraries require the HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\ORACLE_HOME registry variable be set to the BIN directory where the libraries are placed.

The Oracle NLS Library requires the following registry variables be set and the NLS Runtime Library resources be installed to the locations specified by ORA_NLS33 and NLSRTL33:

•	HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\ORA_NLS33

•	HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\NLSRTL33

•	HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\NLS_LANG

Oracle RPC resources must be installed in ORACLE_HOME\NETWORK.  All Reports Server names must be specified in the ORACLE_HOME\NETWORK\ADMIN\TNSNAMES.ORA configuration file.

The Reports ActiveX control is NLS-compliant.  The US resources are bound with the control as well as provided as an external DLL (RWXUS60.DLL).  If Ambient Property NLS Locale is not set, the control uses internally bound US resources and OLE type library.

When the Reports ActiveX control registers, it searches ORACLE_HOME\BIN and REPORT60 for external resource DLLs (RWXxxx60.DLL, where xxx is standard abbreviation of Windows NLS locale) and attempts to register them as localized OLE type libraries.


Performance tips

  Related Topics

•	Use the Reports Server unless you specifically need Preview or Screen interactive output (in which case you must use the Reports Background Engine).

•	Typically, asynchronous communication mode (set via the Call Mode property) is the best choice.  It ensures that multiple reports are not left waiting for another report to complete its run.  However, each progress event (RunReportProgress) in this mode generates some network traffic.  Set the report progress frequency accordingly (via the Call Frequency property).

•	Synchronous communication mode works best if:

•	You are not planning to run many reports at the same time with your application, or you are implementing a synchronous run model in your user interface.

•	The estimated report execution time is short (i.e., the reports you run are relatively simple and your Reports Server is not heavily loaded).

•	The precision of intermediate report execution progress status is not important or not used at all.

•	Use control events rather than polling the GetReportStateCode method to track the execution state.

•	Do not perform any lengthy processing while in control events.


About communication modes

The Reports ActiveX supports three modes of communication with the Reports Server (set via the Call Mode property):

Asynchronous

Synchronous

Local, i.e., the Reports ActiveX Control can use only the Reports Background Engine installed on the local machine.


Asynchronous communication

In asynchronous communication mode, the Reports ActiveX control places a call to the Reports Server when it needs something (e.g., to submit a report or obtain a progress update).  The call immediately returns with the requested information.  You should take the following into consideration when using asynchronous mode:

•	The Reports ActiveX control creates a communication thread for each successful report submission.  This thread will poll the Reports Server for progress at the specified frequency (set via Call Frequency) and generate appropriate control events.  In between control events, the thread is put to sleep.

•	Calls to the Reports Server are RPC calls, which do create network traffic.  This is why report frequency is measured in seconds rather than smaller increments.


Synchronous communication

In synchronous communication mode, the Reports ActiveX control places only a single call to the Reports Server, which does not return until the report execution is complete.  You should take the following into consideration when using synchronous communication:

•	In a Windows GUI application, which is asynchronous, it is usually not desirable to render the user interface unresponsive (e.g., no repainting or progress feedback).  It is always important for the ActiveX control to maintain asynchronous behavior, even if the underlying communication mode is synchronous.  You can emulate synchronous behavior by maintaining a state (e.g., using a Boolean flag or enumeration variable).  For example, an application could disable a Run Report button until the current report submission is running.

•	True report execution progress is unknown to the client because there is only a single call to the Reports Server.  A result is returned only after the report run is done.  If execution progress is requested from the Reports ActiveX control, it has to be emulated.

•	Only one thread in the process can talk to the Reports Server at a time (because only one communication context can be created per process).  If the control creates a synchronous call, all other communication requests will have to wait until the synchronous call is done (i.e. report run is over).  The time it takes for a report to complete varies depending upon the Reports Server conditions and cannot be guaranteed.

•	The Reports ActiveX control creates two threads per report submission (caller and observer threads) in synchronous mode.  The caller thread calls the Reports Server and does not return until the report is done.  The observer thread checks the state of the caller thread and generates progress events, if requested, at the specified frequency.  These progress events do not reflect the actual report execution progress.  The generated progress is generic (e.g., report is running) and without detail (e.g., opening report definition or formatting page 1).  In between control events, the observer thread is put to sleep.


Local communication

In local mode, the Reports ActiveX control does not communicate with the Reports Server at all.  Instead it uses the Reports Background Engine.  Everything happens on the local machine, which means that performance may not be as good as it is with the Reports Server.  You should take the following into consideration when using local mode:

Interactive destinations for report output (i.e., Preview and Screen) are enabled.

The Reports Server property is ignored.

The Reports ActiveX creates an observer thread in local mode.  This thread spawns an application (rwisv60.exe) that calls the Reports Background Engine process (rwrbe60.exe).  The report’s execution is considered done as soon as rwisv60.exe terminates.  Until that happens, the observer thread generates progress events at the specified frequency.


Report execution state

The state of report execution can be obtained anytime between the  BeforeRunReport and AfterRunReport events.  You can obtain the state of the report execution through the RunReportProgress event or by invoking control methods (such as GetReportStateCode) to query the report execution state .  The use of events is the preferable approach.  After the report execution is complete (i.e., after the AfterReportRun has been generated), the control will keep information about it for several seconds but then it will be destroyed and becomes inaccessible.


Reports Server restrictions

All filenames, printer names, and mail addresses must be valid on the Reports Server.  If the OutputDestination was a file, it must be a file accessible from the local file system (e.g., on a network drive) in order to retrieve it.  Alternatively, OutputDestination can be set to be a local file.  In this case, the destination name must be a valid local filename.  When the report successfully completes, the Reports ActiveX control will transfer the report output (along with any dependent files) to the specified local file.


Required properties

  Related Topics

To run a report with the ActiveX control, you must specify at least the following properties:

ReportName	the name of report to run

DatabaseUser	the database connection string

CallMode	the communication mode

ReportsServer	the name of the Reports Server


A standalone or plug-in reader, such as the Adobe Acrobat Reader, that enables you to display your PDF files.


UNICODE

rwsxu60.ocx is the UNICODE build of the Reports ActiveX control and should be run when you are in a double-byte environment.  Note that this build will also run in a single-byte environment, but the double-byte environment is where it is actually needed.

Usage Notes

•	Use UNICODE builds of the Reports Queue Manager (rwqmu60.exe) and the Reports ActiveX control conistently.  For example, if you are using the UNICODE build of the Reports ActiveX control, you should also use the UNICODE build of the Reports Queue Manager.  Otherwise, you must ensure that the USER_NLS_LANG environment variable is specified.  If you are using the default US configuration, these restrictions do not apply.

•	UNICODE builds run on Windows NT 4.0 but not on Windows 95.


An HTML 3.0 compliant browser (e.g., Netscape 2.2 or higher).


Reports Server

The Reports Server enables you to run your reports on a remote machine.  The Reports Server takes requests from clients to run reports.  These requests are entered into a queue and dispatched to run when one of the Reports Server’s runtime processes becomes available.  The Reports Server can be queried for the status of requests.  A scheduling command may accompany non-interactive report requests.  The scheduling command specifies that the report be run at a given time and frequency.


Reports Background Engine

The Reports Background Engine is a simplified server that maintains a queue and Reports Runtime on the local machine (i.e., no network connections are needed) to handle report execution requests.  When you use the Reports Background Engine, interactive destinations for report output (i.e., Preview and Screen) are enabled.  (In earlier versions, the Reports Background Engine was called the Reports Server.)


Server Job Log File

The server job log by default records information such as the server start and shut down time, and the engine start and shut down time. If you want the log to record when a report job runs successfully or fails, ask your system administrator to add the LOGOPTION parameter to the server’s configuration file.