PCREJob class contains all of the API calls which relate to a report-engine job. The functionality of the class mirrors that of the Java Client.

Author:

Copyright (c) 2000 Dynalivery Corp., All Rights Reserved.

Version:

2.4.0

Source:

MobileApps\PCRE\CppClient\Include\pcrejob.h

public enum { jobClosed = 0 ,
              jobOpened = 1 } ;

 static char * StrAlloc ( unsigned int len ) ;

Allocate a string for use by CORBA.

Return:

A pointer to the memory allocated, NULL on failure. This memory should be free'd by StrFree

 static char * StrReAlloc ( const char * str ,
                                  unsigned int len ) ;

Re-allocate a string for use by CORBA, changing the size of the string

Return:

A pointer to the memory allocated, NULL on failure. This memory should be free'd by StrFree

 static char * StrDup ( const char * str ) ;

Copy a string for use by CORBA.

Return:

A pointer to a new copy of the string. This memory should be free'd by StrFree

 static void StrFree ( char * str ) ;

Free memory allocated for a string by CORBA. It is important that all the Str* methods have their memory freed by this call, rather than the standard free().

 void SetName ( const char * jobName ) ;

Set the name associated with this job

 char * GetName ( ) ;

Get the name associated with this job

Return:

The name of this job.

 int getStatus ( ) ;

Get the status of this report job.

Return:

Indicates the status of the job. The various status codes have the following meaning:

PCREJob.JOB_NOTSTARTED

Job has not started yet

PCREJob.JOB_INPROGRESS

Job is in progress

PCREJob.JOB_COMPLETED

Job has completed successfully

PCREJob.JOB_FAILED

Job has failed

PCREJob.JOB_CANCELLED

Job has been cancelled by the user

PCREJob.JOB_HALTED

Job has exceeded the record or time governors

'-1'

Either the print engine or the print job has not yet been opened.

 int getHandle ( ) ;

Get the handle used by this job

Return:

The handle representing this job.

 PCREEngine * getEngine ( ) ;

Get the engine that opened this job

Return:

The engine that opened this job

 PCREJob * getParent ( ) ;

Get the parent of this job, this is meaningless unless the job is a supreport.

Return:

The parent job of this job

 int GetErrorCode ( ) ;

Issue a PEGetErrorCode call for the job.

Return:

The code for the last error which occured.

 const char * GetErrorText ( ) ;

Issue a PEGetErrorText call for the job.

Return:

The text description for the last error which occured.

 void Start ( ) ;

Issue a PEStartPrintJob call for the job.

Return:

Indicates success or failure of call

 int GetStatus ( PEJobInfo * jobInfo ) ;

Get the status and progress statistics of a report job.

Return:

Indicates the status of the job. The various status codes have the following meaning:

PCREJob.JOB_NOTSTARTED

Job has not started yet

PCREJob.JOB_INPROGRESS

Job is in progress

PCREJob.JOB_COMPLETED

Job has completed successfully

PCREJob.JOB_FAILED

Job has failed

PCREJob.JOB_CANCELLED

Job has been cancelled by the user

PCREJob.JOB_HALTED

Job has exceeded the record or time governors

'-1'

Either the print engine or the print job has not yet been opened.

 BOOL IsFinished ( ) ;

Check to see if this print job has finished.

Return:

True if the print job has finished, false otherwise

 void Close ( ) ;

Closes the print job. If printing has not yet finished, it continues. See Crystal Developer's Guide for more information.

 void CloseSubreport ( ) ;

Closes this subreport job.

 void Cancel ( ) ;

Cancels the printing of this job. Typically, this will be tied to a 'cancel' button in the GUI.

 void EnableProgressDialog ( BOOL enable ) ;

Controls the displaying of the print progress dialog box.

 void OutputToPrinter ( int copies ) ;

Sets the print destination for this job to be the printer. See the Crystal Developer's Guide for more information about which printer is used.

 void SelectPrinter ( const char * driverName ,
                            const char * printerName ,
                            const char * portName ,
                            DEVMODE * mode ) ;

Select the printer that this report will be printed to. [The parameters must be supplied or a windows dialog will be thrown up on the server machine.]

 void GetSelectedPrinter ( char * & driverName ,
                                 char * & printerName ,
                                 char * & portName ,
                                 DEVMODE * * mode ) ;

Determine the printer that this report will be printed to.

 void OutputToPDF ( const char * pdfFileName ,
                          PCREPDFOutputOptions * pdfOptions = NULL ) ;

Output the report in PDF format.

 void ExportTo ( PCREExportOptions * exports ) ;

Export the report to a variety of formats.

 void ExportTo ( PEExportOptions * exports ) ;

Export the report to a variety of formats.

 const char * GetReportTitle ( ) ;

Get the title of this job's report.

 void SetReportTitle ( const char * title ) ;

Set the title of this job's report.

 void SetPrintOptions ( PEPrintOptions * options ) ;

Set the options for printing.

 BOOL HasSavedData ( ) ;

Checks to see if this job's report contains saved data.

Return:

Indicates whether the report has saved data.

 void DiscardSavedData ( ) ;

Discard the saved data associated with this job's report.

 int GetNFormulas ( ) ;

Get the number of formulae which are used in this job's report

Return:

The number of formulae used.

 void GetNthFormula ( int nFormula ,
                            char * & formulaName ,
                            char * & formulaText ) ;

Get the nth formula from this job's report. Both the formula name and text are returned

 void GetNthFormulaStr ( short nFormula ,
                               char * & formulaName ,
                               char * & formulaText ) ;

Get the Nth formula from this job's report.

 void GetFormula ( char * formulaName ,
                         char * & formulaText ) ;

Get the text for the given (named) formula.

 void GetSelectionFormula ( char * & formulaText ) ;

Get the selection formula used in this job's report.

 void SetSelectionFormula ( const char * formulaText ) ;

Set the selection formula for this job's report.

 BOOL CheckSelectionFormula ( ) ;

Test the selection formula for validity.

Return:

True if the formula is valid, false otherwise.

 BOOL CheckGroupSelectionFormula ( ) ;

Test the group selection formula for validity.

Return:

True if the formula is valid, false otherwise.

 void SetFormula ( const char * formulaName ,
                         const char * formulaText ) ;

Set the text for a given (named) formula.

 BOOL CheckFormula ( const char * formulaText ) ;

Checks the named formula for validity.

Return:

boolean indicating whether the formula is legal.

 int GetNParams ( ) ;

 int GetNParameterFields ( ) ;

Get the number of parameter fields in this job's report.

Return:

The number of parameter fields in the report.

 void GetNthParameterField ( int paramN ,
                                   PCREParameterField * info ) ;

Get details about the nth parameter field in this job's report.

 void SetNthParameterField ( int paramN ,
                                   PCREParameterField * info ) ;

Set details about the nth parameter field in this job's report.

 void GetNthParam ( int paramN ,
                          char * & parameter ) ;

Retrieve the specified param.

 void SetNthParam ( int paramN ,
                          const char * parameter ) ;

Change the specified param.

 int GetNSortFields ( ) ;

Get the number of sort fields in this job's report.

Return:

The number of sort fields.

 void GetNthSortField ( short sortFieldN ,
                              char * & name ,
                              short * direction ) ;

Get the name and sort direction of a given sort field.

 void SetNthSortField ( short sortFieldN ,
                              char * name ,
                              short direction ) ;

Set the name and sort direction of a given sort field.

 void DeleteNthSortField ( short sortFieldN ) ;

Delete a given sort field from a report.

 int GetNGroupSortFields ( ) ;

Get the number of group sort fields in the current report.

Return:

The number of group sort fields.

 void GetNthGroupSortField ( short sortFieldN ,
                                   char * & name ,
                                   short * direction ) ;

Get the name and sort direction of a given group sort field.

 void SetNthGroupSortField ( short sortFieldN ,
                                   char * name ,
                                   short direction ) ;

Set the name and sort direction of a given group sort field.

 void DeleteNthGroupSortField ( short sortFieldN ) ;

Delete a given group sort field from a report.

 void GetPrintDate ( short * year ,
                           short * month ,
                           short * day ) ;

Get the print date for the job's report.

 void SetPrintDate ( short year ,
                           short month ,
                           short day ) ;

Set the print date for the job's report.

 int GetNGroups ( ) ;

Get the number of groups in this report.

Return:

The number of groups.

 int GetNSections ( ) ;

Get the number of sections in this report.

Return:

The number of sections.

 int GetNSubreportsInSection ( short sectionCode ) ;

Get the number of subreports in a given section

Return:

The number of subreports in the named section

 void GetNthSubreportInSection ( short sectionCode ,
                                       short subreportN ,
                                       PESubreportInfo * info ) ;

Get the Nth subreport in a given section.

 int GetSectionCode ( short sectionN ) ;

Get the section code for the specified section. See Crystal Developer's help.

Return:

The section code for the given section

 int GetMinimumSectionHeight ( short sectionN ) ;

Get the minimum height for a given section. See Crystal Developer's help.

Return:

The minimum height for the specified section in twips.

 void SetMinimumSectionHeight ( short sectionN ,
                                      short height ) ;

Set the minimum height for a given section. See Crystal Developer's help.

 void GetAreaFormat ( short areaCode ,
                            PESectionOptions * options ) ;

Get the area format settings for the specified area.

 void SetAreaFormat ( short areaCode ,
                            PESectionOptions * options ) ;

Set the area format settings for the specified area.

 void SetAreaFormatFormula ( short areaCode ,
                                   short formulaName ,
                                   const char * formulaString ) ;

Sets the formatting options for a report area.

 void SetGroupCondition ( short sectionCode ,
                                const char * conditionField ,
                                short condition ,
                                short sortDirection ) ;

Change the group condition for a group section.

 void GetGroupCondition ( short sectionCode ,
                                char * & conditionField ,
                                short & condition ,
                                short & sortDirection ) ;

Examine the group condition for a group section.

 void GetGroupSelectionFormula ( char * & selectionString ) ;

Examine the group selection string.

 void SetGroupSelectionFormula ( char * selectionString ) ;

Change the group selection string.

 void GetSectionFormat ( short sectionCode ,
                               PESectionOptions * options ) ;

Get the section format settings for specified section.

 void SetSectionFormat ( short sectionCode ,
                               PESectionOptions * options ) ;

Sets the section format settings for specified section.

 void SetFont ( short sectionCode ,
                      short scopeCode ,
                      const char * faceName ,
                      short fontFamily ,
                      short fontPitch ,
                      short charSet ,
                      short pointSize ,
                      short isItalic ,
                      short isUnderlined ,
                      short isStruckOut ,
                      short weight ) ;

Set Font Details. See Crystal Developer's Guide for more information.

 void GetGraphType ( short sectionCode ,
                           short graphN ,
                           short * graphType ) ;

Get information about the type of a given graph.

 void SetGraphType ( short sectionCode ,
                           short graphN ,
                           short * newType ) ;

Set information about the type of a given graph.

 void GetGraphData ( short sectionCode ,
                           short graphN ,
                           PEGraphDataInfo * graphDataInfo ) ;

Get information about the data of a given graph.

 void SetGraphData ( short sectionCode ,
                           short graphN ,
                           PEGraphDataInfo * graphDataInfo ) ;

Set information about the data of a given graph.

 void GetGraphText ( short sectionCode ,
                           short graphN ,
                           PEGraphTextInfo * graphTextInfo ) ;

Get information about the text of a given graph.

 void SetGraphText ( short sectionCode ,
                           short graphN ,
                           PEGraphTextInfo * graphTextInfo ) ;

Set information about the text of a given graph.

 void GetGraphOptions ( short sectionCode ,
                              short graphN ,
                              PEGraphOptions * graphOptions ) ;

Get information about the options of a given graph.

 void SetGraphOptions ( short sectionCode ,
                              short graphN ,
                              PEGraphOptions * graphOptions ) ;

Set information about the text of a given graph.

 char * GetSQLQuery ( ) ;

GetSQLQuery () returns the same query as appears in the Show SQL Query dialog in CRW, in syntax specific to the database driver you are using.

Return:

The SQL query set for this report.

 void SetSQLQuery ( char * queryString ) ;

Set the SQL query for this report.
SetSQLQuery () is mostly useful for reports with SQL queries that were explicitly edited in the Show SQL Query dialog in CRW, i.e. those reports that needed database-specific selection criteria or joins. (Otherwise it is usually best to continue using function calls such as SetSelectionFormula () and let CRW build the SQL query automatically.)

SetSQLQuery () has the same restrictions as editing in the Show SQL Query dialog; in particular that changes are accepted in the FROM and WHERE clauses but ignored in the SELECT list of fields.

 int GetNTables ( ) ;

Get the number of tables in this report.

Return:

The number of tables in this report.

 void GetNthTableType ( short tableN ,
                              PETableType * tableType ) ;

Get information about the type of a given database table.

 void GetNthTableSessionInfo ( short tableN ,
                                     PESessionInfo * sessionInfo ) ;

Get the session information for an MS Access table being used by the report.

 void SetNthTableSessionInfo ( short tableN ,
                                     PESessionInfo * sessionInfo ,
                                     BOOL propagateAcrossTables ) ;

Set the session information for an MS Access table being used by the report.

 BOOL TestNthTableConnectivity ( short tableN ) ;

This function tests whether a database table's settings are valid and ready to be reported on. It returns true if the database session, log on, and location info is all correct.

This is useful, for example, in prompting the user and testing a server password before printing begins.

This function may require a significant amount of time to complete, since it will first open a user session (if required), then log onto the database server (if required), and then open the appropriate database table (to test that it exists). It does not read any data, and closes the table immediately once successful. Logging off is performed when the print job is closed.

If it fails in any of these steps, the error code set indicates which database info needs to be updated using functions above:

• If it is unable to begin a session, PE_ERR_DATABASESESSION is set, and the application should update with PESetNthTableSessionInfo.
• If it is unable to log onto a server, PE_ERR_DATABASELOGON is set, and the application should update with PESetNthTableLogOnInfo.
• If it is unable open the table, PE_ERR_DATABASELOCATION is set, and the application should update with PESetNthTableLocation.

Return:

true If the database session, log on, and location info is all correct.

 void GetNthTableLogOnInfo ( short tableN ,
                                   PELogOnInfo * logOnInfo ) ;

Get the SQL connection information for the nth table in this job's report.

 void SetNthTableLogOnInfo ( short tableN ,
                                   PELogOnInfo * logOnInfo ,
                                   BOOL propagateAcrossTables ) ;

Set the SQL connection information for the nth table in this job's report.

 void GetNthTableLocation ( short tableN ,
                                  PETableLocation * location ) ;

Get the location information for a given table in the report.

 void SetNthTableLocation ( short tableN ,
                                  PETableLocation * location ) ;

Set the location information for a given table in the report.

 int GetNDetailCopies ( ) ;

Returns the number of copies of each Details section in the report that are to be printed.

Return:

The number of copies to be printed.

 void SetNDetailCopies ( short nCopies ) ;

Change the number of detail copies

 void GetMargins ( short * left ,
                         short * right ,
                         short * top ,
                         short * bottom ) ;

retrieve the margin settings for this report.

 void SetMargins ( short left ,
                         short right ,
                         short top ,
                         short bottom ) ;

Set the margins for this report.

 int GetNPages ( ) ;

Get the number of pages in the report. This should only be called after the report has been run.

Return:

The number of pages in the report

 void GetReportSummaryInfo ( PEReportSummaryInfo * info ) ;

Retrieve the summary information for the report.

 void SetReportSummaryInfo ( PEReportSummaryInfo * info ) ;

Change the summary information for the report.

 void GetParameterField ( char * fieldName ,
                                PEParameterFieldInfo * output ) ;

Retieve the paramter information for a parameter with the specified name.

 BOOL SetParameterField ( char * fieldName ,
                                PEParameterFieldInfo * newInfo ) ;

Change the paramter information for a parameter with the specified name.

Return:

True if the update was made, false if the field couldn't be found, or any error.

 void GetAreaFormatFormula ( short areaCode ,
                                   short formulaName ,
                                   char * & text ) ;

 void GetGroupOptions ( short groupN ,
                              PEGroupOptions * groupOptions ) ;

 void SetGroupOptions ( short groupN ,
                              PEGroupOptions * groupOptions ) ;

 void GetSectionFormatFormula ( short sectionCode ,
                                      short formulaName ,
                                      char * & text ) ;