Home

Parallel Crystal Developers Manual

1. Property Name Purpose PEGat ewaySetHost Set the Report Server host for the G ateway Server PEGatewayGetHost Return the Report Server host running the G ateway Server PEGatewaySetName Set the name of the G ateway Server PEGatewayGetName Return the name of the G ateway Server PEGatewaySetWait Set G ateway Server timeout when starting a PCRE Server PEGatewayGetWait Return the G ateway Server timeout Table 9 6 In the following example the G ateway host and wait period are acquired from user interface dialogs and then set with property calls before completing the connection with a call to p string PCREAPI 1 The calls to P1 E_NO_CONNI P EConnect and P ECT EConnect Notice that you must follow the call to PEConnect with a call to PEInitapr to complete the client initialization The parameter to petnitapr must be the EInitAPI are only necessary because PEInitialize was called with Normally PEInitialize makes these calls internally Parallel Crystal D eveloper s Manual 261 Version 2 4 Revised 5 27 00 PEHANDLE gwHandle char pHost HostDialog DWORD dwWait WaitDialog Must call P PEInitialize N EInitialize with Pl ULL NULL 0 NULL E NO P Get Gateway handle and set host gwHandle PEGet Gateway if PEGatewaySetHost gwHandle ReportError goto close pHos PEGateway
2. API method calls catch PCREAPIError el el Report catch PCREError e2 e2 Report client Quit Will report all errors using the default pcrEApplicationConsole If your application has a graphical user interface or your client is an applet then the PCREApplicationConsole Class is inappropriate and you will require a graphical implementation of the pcreconsole interface Parallel Crystal D eveloper s Manual 96 Version 2 4 Revised 5 27 00 A typical graphical console might take the following form public class GUIConsole implements PCREConsole The console is installed in the client using a modified constructor call private void LogMsg String msg Log a message private void MessageBox 27 int kind Display a modal message box public void PCR MessageBox TI BOutputMsg EXT_ String m SG msg public void PCR BFAPIErrorMsg PCREEr LogMsg e getText public void PCR EServerErrorMsg PCRE MessageBox SE RV ER_MSG e getText public void PCR MessageBox GATI EGa EWAY_ tewayErrorMsg PC SG e getTex public void PCRE ClientErrorMsg PCRE MessageBox C IENT_ SG e getText public void PCRE Fa String msg a A sg rore Error e O REError e
3. getColumnType custom mapping s table above getCurrency getDouble for FLOAT REAL DOUBLE getBigDecimal for DECIMAL and NUMERIC getDate getDate for DATE getTime for TIME getTimeStamp for TIMESTAMP getDouble getDouble for FLOAT EAL DOUBLE getBigDecimal for DECIMAL and NUMERIC geLinteger getInt getMemo getString getShort getShort getString getString Next next Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Error Recovery The Parallel Crystal Java Client package provides a group of classes for handling and reporting errors These classes are arranged in the hierarchy shown in Figure 3 2 All classes are derived from pcrezError but PCREGatewayError PCREServerError and PCREAPIError are additionally derived from pcreserviceError in order to group errors that originate in the Report Server java lang Exception PCREInternalError PCREClientError PCREServiceError EServer EGatewayError Figure 3 2 Parallel Crystal D eveloper s Manual 92 Version 2 4 Revised 5 27 00 The six derived error classes are PCREClientError is used to identify errors that are detected by the Java client classes These errors are caused by an invalid argument to a client side method or an inappropriate use of such a method
4. public void start ConnectClient I Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Note that start calls connectClient that clearly does the real work On return to start client is areference to an instance of a connected pcreAppletClient Or is null if the call to the connect method failed The client is created by a call to the pcreappletCclient constructor that has the following signature public PCREAppletClient PCREConsole console java applet Applet applet Since the pcrEAppiet Class both implements the pcreconsole interface and extends the java applet Applet base class a reference to the current instance is supplied by passing the current class instance this for both arguments The first argument provides a reference to your implementation of the pcrEconsole and the second argument provides a reference to your applet The underlying client server CORBA substrate uses the applet reference to manage network connections in a manner that is consistent with restrictions imposed by the applet s Security Manager If the connect method returns correctly then the applet client will be connected to a Report Engine which is running on the same machine as the web server that served the applet to the browser So if you originally browsed to http www example host com applets pcreapplet html then your Report Engine will be running o
5. try client Connect PCREEngine engine client OpenEngine j PCREJob job engine gt OpenJob report API calls job gt Start engine gt Close catch PCREError amp e throw ReportError e Text This function declares an instance of the pcREAppclient Class as a local variable called client Because the client is instantiated locally its destructor will be invoked when we leave the function It is also possible to disconnect a client manually by calling the pcrEAppclient class Disconnect method This allows a single instance of pcrEAppClient to be connected to a given host then disconnected and re connected to another host For example Parallel Crystal D eveloper s Manual 267 Version 2 4 Revised 5 27 00 void RunReport PCREAppClient client try client gt getGateway gt setHost hos client gt Connect char host t PCREEngine engine client gt 0penEngine PCREJob job engine gt OpenJob report API calls job gt Start engine gt Close client gt Disconnect catch PCREError amp e client gt Disconnect throw ReportError e Text void main int argc char argv PCREAppClient client new PCREAppC try RunReport client example host com RunReport client example2 host catch ReportError e
6. 2 If your client appears to block indefinitely inside a method of the pcreEngine or PCREJob Classes or in an API function then a third party component used by the Crystal Print Engine D LL may have created an error dialog on the Report Server To diagnose this problem you need to get the System Administrator to run Parallel Crystal from the desktop so that all components are visible If a Crystal A PI call leads to an error dialog the Report Engine Server G UI will display the call and the dialog itself will be visible The Parallel C rystal System A dministrator s M anual describes how to run Parallel Crystal in desktop mode 3 Occasionally components of Parallel Crystal may crash or terminate abnormally To assist error diagnosis the Report Engine Server File Server and G ateway Servers generate log files that contain trace and error messages In addition components write error messages to the Windows NT event log The content of these log files is described in the Parallel Crystal System A dministrator s M anual 4 Occasionally your client may transfer to a catch clause and report the error CORBA Error CORBA UNKNOWN The most likely cause is a Report Engine Server crash rendering the remote method that you are trying to call unknown 5 Occasionally your client may transfer to a catch clause and report the error CORBA Error CORBA NOIMPLEMENT Parallel Crystal D eveloper s Manual 313 Version
7. JKKK Eet cpemasi 1 0 Type Library API Declaration Loader a C Application Performance Explorer Client Application Performance Explorer Expediter Priority _ Application Performance Explorer Instancer Help _ Application Performance Explorer Logger Application Performance Explorer Manager Application Performance Explorer Pool Manager Application Performance Explorer Queue Manager b pplication Performance Explorer Server cpemas1 1 0 Type Library Location C mas crystal cpemas1 Debug cpemas1 dll Language Standard Figure 5 3 Once the PCRE Automation Server is imported into your project you can access the properties and methods of the root rcrApplication interface through Visual Basic Dim statements Generating PostScript Reports with Visual Basic In this section we show how to construct a Visual Basic client that uses the Parallel Crystal Automation Server to generate PostScript reports The client has a very simple user interface which is shown in Figure 5 4 on page 155 The name of the Report Server host and the path name of the report file are entered into the respective text boxes When the Connect button is pressed the client is connected to the Report Server and the Run and Disconnect buttons are enabled When the Run button is pressed the report is generated and a pop up message box will confirm success The Disconnect button disconnects the client f
8. Print Job Execution The following group of methods controls the execution of a print job and returns its status Start Close CloseSubReport Cancel For example PCREJob job engine OpenJob MyReport rpt Customize job job Start job Close You should always call close OF CloseSubReport after the report has been generated to release resources in your Report Engine Server Parallel Crystal D eveloper s Manual 69 Version 2 4 Revised 5 27 00 Print Job Details The following group of methods allows you to manipulate details of your report GetReportTitle SetReportTitle SetPrintOptions HasSavedData DiscardSavedData GetPrintDate SetPrintDate For example int date new int 3 date 0 year date 1 month date 2 day job SetPrintDate date job SetReportTitle Monthly Sales January March job Start Print Job Outputs The methods in this group are amongst the most important in PCREJob and allow you to specify the format and destination of your report OutputToPrinter OutputToPDF ExportTo We have already given simple examples of calls to O utputT oPrinter and OutputToPD F in Chapter 2 In this section we ll show how to use Export To to generate reports in different output formats and for various storage media The ExportTo method takes a single parameter that is a reference to a helper class called PCREJobExport Info This
9. Problems with PDF Problems with the Report Server sc ctinc s scence ecceatgtselesssaccasetstvulesassecasetatvu desde unedconsa caste E A ET A aea A AAA EA REET EEEN 116 Chapter 5 Getting Started with ActiveX Clients scscssscsssssssssssssssssssssssesssssesssssssessssessssesesssssessssessessseessssessassesessesessesssseseses 119 Parallel Crystal and ACHVeX COM clients eriei E E cad dsivse dau EE N O E E RE 120 Microsoft COM syrit eneren erer EA ODENSE IA DAEA EAIN DO ENEN NA ES TAEAE T E ARASA AA E EENS I AA LEERSE 120 Microsoft COM Automation 3 The Parallel Crystal Object Modelis iessen eei EE OT NE E EE EE EE EA 124 The Parallel Crystal Automaton Server icsczccswcsvccccceacsseseussasesgesees save exesssise R Eini TRE AAEE RURE ONE EENS E EEA 126 Using Parallel Crystal with Visual CE Hahi i oninia rein anA ERNE EENE TE ERIRE AER AE ot eows Generating PostScript Reports with COM esise inn E AAEN AEE R i i Using Simple Wiapper Classes vi cisccssesasazcgosvsisssesesssascsnevesassvsncancsnsaneassvstsazcsnsevacnavatesacavasbaesuesesacoasanesntsdavansvsavasscnavsdatevesvensseseuatie Generating PDF and HTML Reports with COM is Generating PostScript Reports with Visual C and COM ccceseeccssseseeseeseceeceeceseeaeesecseceeeseesecsecsessecaeeaeeaesaeseeeeeeaeeaeeaeeaeeaees 134 Generating PDF and HTML Reports with VC and COM cceccsccssseseeseeseceecesceseeseesecsecaesaeesecseesecaeeaeeseesecaecaeee
10. 5 The report format is set to PDF and the path name c MyReports Box pdf specifies the output file on the client machine Parallel Crystal D eveloper s Manual 295 Version 2 4 Revised 5 27 00 6 The print job is started The report is generated on the Report Server machine and is retrieved to the file c MyReports Box pdaf on the client machine If the report is generated correctly then the file c MyReports Box paf Will be available on the client machine on retum from the start method at Step 6 The Report Retrieval feature requires your Parallel Crystal to be installed with a file transfer service If this service is not running then Step 5 above will throw a PCREServerError with the message PCREServerError Connect cannot connect to PCRE File Transfer Service The Report Retrieval feature can be dynamically switched on or off for a client by calling setRet rieveMode with the argument value TRUE Or FALSE Retrieval to C Clients Y ou activate the Report Retrieval Service for your C client by calling the API function PESetRetrieveMode with the argument value True You must do this after you call PEInitialize You then specify a path for the generated report on the diat s machine in one of the API calls pzeout put ToPDF PEOut put TOHTML PEStartParallelReport PEStartParallelPrintJob or in one of the format options structures supplied in a call to PEExportTo When you call pestar
11. Get last error code 0 implies no error if code PEGetErrorCode job return Retrieve and print last error message if PEGetErrorText job amp handle amp length if length gt sizeof buffer length sizeof buffer if PEGetHandleString handle buffer length printf API error d s n code buffer You should call this function after every API function that returns a failure code For example IE PEOpenPrintJob C SampleReports Box rpt Report Error 0 goto close_engine Even with the utility function ReportError in place this style of error reporting is tedious and error prone and leads to code sequences that are either artificially nested or polluted with goto statements 8 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Error Recovery in C Clients The Parallel Crystal C Client provides a collection of classes that allow API errors to be treated as exceptions When methods of the pcreEngine and PcrEJob Classes detect an error they throw an exception containing the API error code and message as instance data Y ou can catch these exceptions by including the method calls within try catch blocks in your program Exceptions are instances of the error handling classes shown in Figure 9 2 All classes are derived from PCREF rror but PCREGatewayError PCREServerError and PCREAPIError are additionally deriv
12. e Java does not have optional arguments so missing arguments have to be explicitly provided by the programmer Dispatch pointers are mapped to Java O bjects e The ICRApplication interface is derived from com ms com IUnknown However you do not have access to the tunknown methods and so you cannot call addref or Release manually Generating PostScript Reports with Visual J Once you have generated the Automation Server Java interfaces you can import them into your application with a normal import statement The following example shows you how to generate a simple report in PostScript import cpemasl a ae import com ms com 2 class PostScriptExample public static void main String args Variant none new Variant LL 3 none noParam try ICRApplication app hi Ay ICRApplication new CRApplication j app ConnectToReportServer example host com fe 23 ICRReport report if En ICRReport app OpenReport C MobileApps pcre SampleReports Box rpt none report PrintOut none none none none none none 7 app DisconnectFromReportServer 8 catch ComFailException e 9 System out printlin e getMessage 10 Example 5 3 Parallel Crystal D eveloper s Manual 7 Version 2 4 Revised 5 27 00 Each numbered paragraph below corresponds to the same numbered code statement 1 The Automation Server interfaces are imported with a packa
13. If there are no O SAgents running on your network clients will be unable to connect to any of the available Report Servers Y ou may find that your client hangs for around 15 seconds before connect ToReport Server returns with a general failure message You should ensure that at least one of the Report Servers on your network is running an O SAgent Y our client communicates with the O SA gent using UD P broadcast packets that are normally confined to a subnet of your LAN If you are trying to connect to a Report Server on a remote network you may need to supply the client with the IP address of the remote O SAgent In order to do this you must set the osagentAddress property before you call connect ToReport Server Parallel Crystal D eveloper s Manual 26 Version 2 4 Revised 5 27 00 For example Visual C app gt OSAgentAddress 123 456 654 321 app gt ConnectToReportServer 123 456 654 321 Visual Basic app OSAgentAddress 123 456 654 321 app ConnectToReportServer example host com Visual J app putOSAgentAddress 123 456 654 321 app ConnectToReportServer example host com The IP address supplied to the O SAgent and the host name supplied to Connect ToReport Server need not specify the same machine Y ou should get your System Administrator to supply you with the correct IP address for the Report Server running the O SA gent Finally the following connection pro
14. You can reduce the connection time to the Report Server by having the client CORBA framework connect directly to the IIO P GateK eeper using the following applet parameter lt param name ORBalwaysProxy value true gt The parameter name alludes to the fact that the IIO P G ateK eeper is called a proxy server since it stands in for the real server on the remote machine The HTTP tunneling feature can be similarly enabled by the following parameter lt param name ORBalwaysTunnel value true gt However you should be aware that HTTP tunneling introduces the overhead of adding and removing HTTP wrappers to each IO P request Therefore you should be sure that you actually need this feature before enabling it Bl Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Finally we combine the various applet attributes and parameters into a complete lt applet gt tag We assume that the HT ML page was originally loaded from http www acme com pages Travel html but the applets are to be loaded from http www acme com classes The applet tag has the form lt applet name Travel width 400 height 600 code Travel codebase http www acme com classes gt lt param name org omg CORBA ORBClass value com visigenic vbroker orb ORB gt lt param name ORBalwaysProxy value true gt lt applet gt The orBgatekeeperIor parameter has been omitted so the file gatekeeper ior should exist in the classes sub directory of t
15. pReport ExportToHTML outputPath pApp DisconnectFromReportServer End Sub Visual J caller must handle COMFailExceptions void RunSample String host String report String inputPath outputPath ICRApplication pApp ICRApplication new CRApplication j pApp ConnectToReportServer host ICRServer pConfig ICRServer pApp getServerSettings inputPath pConfig getSampleReportDir report rpt outputPath pConfig getWebServerDir report html pApp putRetrieveMode 1 Variant v new Variant v noParam ICRReport pReport ICRReport pApp OpenReport inputPath v pReport ExportToHTML outputPath pApp DisconnectFromReportServer Parallel Crystal D eveloper s Manual 214 Version 2 4 Revised 5 27 00 Parallel Crystal Report Retrieval When a report is generated using any of the file based formats the file is created on the Report Server If the client and the Report Server do not run on the same machine then the report file must be retrieved if the client wishes to view it locally The easiest way to do this is to use the Parallel Crystal Report Retrieval Service When report retrieval is enabled the report is copied back to a named file on the client machine If you have a local viewer on your client such as a web browser or a PD F Reader then you can display the report as soon as it is returned If your client is a VBScript application running on t
16. report error delete client lient com char report C Monthly rpt C Summary rpt If your C client application crashes due to a program error the Report Engine Server receives a client aborted notification and shuts itself down However you should not rely on program termination to close your servers and you should endeavor to disconnect your client by calls to Disconnect or the pcREAppClient destructor Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Connecting C Clients C clients are automatically connected to the Report Server when you call petnitialize and with a pz_po_connect argument value For example PEInitialize NULL example host com 0 NULL PE_DO_CONNECT The function returns true if the connection is established and rausz otherwise Y ou must call peGetErrorText to get the reason for the failure pzEtnitialize is declared with the following signature BOOL PCRE_API PEInitialize PEConsole console const char host int argc char argv int connect The parameters have the following meanings console host argc argv connect Specifies an application console for the client to use A console provides an abstract interface that insulates the client from the details of your user interface Y ou seldom need to provide a console in C clients and if you su
17. In the following example we use the Export To method to generate a file in Excel format and save it to disk PCREJob job PEExportOptions options UXFXlsOptions formatOptions UXDDiskOptions diskOptions engine gt OpenJob C SampleReports Box rpt strcpy options formatDLLName u2fxls dll options formatType UXFX1s4Type formatOptions bColumnHeadings FALSE options formatOptions void strcpy options destinationDLLName UXDDiskType C SampleOutputs Box xls void amp diskOptions options destinationType diskOptions fileName options destinationOptions job gt ExportTo amp options job gt Start amp formatOptions u2ddisk dl1 Notice that you must call start after ExportTo to actually generate the report Table 9 10 below enumerates the possible settings for the dest inat ionDLLName and the corresponding values for the destinat ionType and destinat ionOptions DLL Name Destination Sub type Destination Options u2ddisk dll UXDDiskType UXDDiskOptions u2dmapi dll UXDMAP IType UXDMAPIOptions u2dpost dll UXDExchFolderType UXDPostFolderOptions Table 9 10 Parallel Crystal D eveloper s Manual 278 Version 2 4 Revised 5 27 00 The following example shows how to mail a report using the MAPI mailer server interface PCREJob job engine gt OpenJob C SampleReports Box rpt PEExpo
18. In the section entitled Parallel Crystal and ActiveX CO M clients we explain the terms ActiveX and COM and describe how a related technology called Automation is used to enable compiled and interpreted Microsoft languages to access Parallel Crystal Then we describe how automation based clients control Report Customization through the methods and properties in the Parallel Crystal Report Engine O bject Model In the section entitled Using Parallel Crystal with Visual C we describe how to use the PCRE Object Model from C to produce simple reports in PostScript PD F and HTML First we show how the low level COM APIs are used and then we show how the Visual C COM extensions provide a more effective interface for programming automation clients in C In the section entitled Using Parallel Crystal with Visual J we describe how to use the PCRE Object Model from Microsoft Visual J to produce reports in PostScript PDF and HTML We show how the Visual J Type Library Wizard generates wrapper classes that eliminate the need for detailed knowledge of COM and make the programming of Java automation clients particularly easy In the section entitled Using Parallel Crystal with Visual Basic we describe how to use the PCRE Object Model from Visual Basic Many aspects of COM Automation were designed specifically for the Visual Basic development community and programming Visual Basic clients for Parallel Crystal is very simple Th
19. Start Close CloseSubReport For example PCREJob Jjob engine gt OpenJob MyReport rpt Customize job job gt Start job gt Close after the report has been generated close the job to release resources in your Report Engine Server Call close for jobs opened with openPrintJob Use closeSubReport for jobs opened with opensubReport Print Job Details The following group of methods allows you to manipulate details of your report GetReportTitle SetReportTitle SetPrintOptions HasSavedData DiscardSavedData GetPrintDate SetPrintDate For example job gt SetPrintDate year month day job gt SetReportTitle Monthly Sales January March job gt Start Print Job Outputs The methods in this group are amongst the most important in pcrEJob and allow you to specify the format and destination of your report OutputToPrinter OutputToPDF ExportTo We have already given simple examples of calls to O utputT oPrinter and OutputToPD F in Chapter 8 In this section we ll show how to use Export To to generate reports in different output formats and for various storage media Parallel Crystal D eveloper s Manual 275 Version 2 4 Revised 5 27 00 The ExportTo method takes a single parameter that is a pointer to a struct called PEExportOptions This struct encapsulates information about the format and the destination of the report as follows typedef struct
20. pReport OutputToPDF C MyReports Box pdf Fae Ds pApp DisconnectFromReportServer Hrs Parallel Crystal D eveloper s Manual 215 Version 2 4 Revised 5 27 00 Visual J ICRApplication pApp ICRApplication new CRApplication 1 pApp Connect ToReportServer example host com Lh v2 pApp putRetrieveMode 1 EP Variant v new Variant v noParam C SampleReports Box rpt on the Report Server machine ICRReport pReport ICRReport pApp OpenReport C SampleReports Box rpt v A C MyReports Box pdf on the client machine pReport OutputToPDF C MyReports Box pdf pp De pApp DisconnectFromReportServer EP 36s Each numbered paragraph below corresponds to the same numbered code statement 1 An Application O bject is created and a reference to the 1cRApplication interface is stored in papp 2 The client connects to the Report Server running on the host example host com 3 The client sets the ret rieveMode property to TRUE to enable the retrieval service 4 A Report Object is opened using the path name of the Box report on the Report Server machine The refererence to the rcrReport interface is stored in pReport 5 The outputToppr method is called to generate the report in PD F The argument specifies the path name of the PDF file for the client machine The method returns when the report has been retrieved to the client machine 6 The client is disc
21. t talErrorMsg PCRE MessageBox FATAL_MSG public void PCR MessageBox I EIn TE Error e e getText ternalErrorMsg P RNAL_MSG e getTe Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 CREError e REON The code fragment above then takes the following form PCREApplicationClient client null try client new PCREApplicationClient new GUIConsole example host com i client Connect try BPI method calls catch PCREAPIError el el Report Hi catch PCREError e2 e2 Report H2 client Quit The pcrREAPIError Caught in handler H1 will be reported with the pcrEaPIErrorMsg method of the cutconsole However all errors caught by the handler H2 will also be reported with the correct cutconsole method since e2 is actually a reference to derived error class whose Report method overrides the base class method So if e2 happens to be aPCREClientError it will be reported with the PCREC1lientE rrorMsg method of the GUIConsole Parallel Crystal D eveloper s Manual 98 Version 2 4 Revised 5 27 00 Parallel Crystal Report Retrieval When a report is stored in a disk file the file is generated on the Report Server machine using the path name you supplied in an
22. 00 Using Parallel Crystal in a C Application In this section we describe how to construct aC application program that generates a report as a PostScript PD F or HTML document For simplicity we assume that the C program has a simple character based user interface Once you ve mastered the material in this chapter you can refer to the section entitled Print Job Outputs in Chapter 9 to learn how to generate reports in other formats Generating a Simple PostScript Report The sample C program shown in Example 8 1 generates a report from the Box rpt report file and sends it to a PostScript printer We ll describe it line by line but note that if you try the program e actly as presented here it will neither compile nor execute include lt pcre h gt void main int argc char argv PCREAppClient client example host com try client Connect PCREEngine engine client OpenEngine PCREJob job engine gt OpenJob C MobileApps PCRE SampleReports Box rpt job gt OutputToPrinter 1 job gt Start job gt Close cout lt lt Report generated lt lt endl engine gt Close catch PCREError amp error error Report Example 8 1 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Ia A 10 11 12 Each numbered paragraph below corresponds to the same numbered code statemen
23. 27 00 Figure 2 1 on page 30 illustrates the following important points The Parallel Crystal Report Server is normally hosted within a single powerful multi processor server machine running Windows NT A Parallel Crystal Java A pplication Client normally runs in a less powerful client machine such as a desktop PC running Windows 95 Each Java Application Client is connected to a corresponding PCRE Report Engine in the Report Server machine Each Report Engine includes a copy of the Parallel Crystal Report Engine PCRE DLL An agent on the Report Server called the PCRE Gateway establishes Client server connections The Java Application Client performs report customization and generation by making calls to the PCRE DLL These calls are transmitted from the client to the server and then the results are transmitted back to the client Because report customization is performed within the Report Server the Crystal report files must be present on that machine or be available through networked file store Reports are produced on the Report Server machine However Parallel Crystal provides a number of mechanisms for viewing and then retrieving reports back to the client machine When a Java Application Client is started it is allocated a Report Engine when it connects to the Report Server The Report Engine is terminated when the client disconnects from the Server Multiple Report Engines execute in parallel on the Report Server Ho
24. End If report PrintOut If Err Number lt gt 0 Then sgBox PrintOut amp report LastErrorString Exit Sub End If Neither of these solutions is entirely satisfactory Trouble Shooting Simple Visual Basic Clients In this section we ll take a look at the most common errors that occur when programming simple clients using Visual Basic We ll assume that errors are reported by accessing the appropriate Get LastErrorSt ring property in the Automation Server e The call to the Application O bject method connect ToReport Server may fail and report the error No connection to a Server Report Engine has been made There are two possible reasons for this error either the argument string does not specify a valid host name or the Parallel Crystal Report Server was not running on the specified host Check that the string you supplied is either a valid host domain name or IP address and then check that Parallel Crystal is installed and running on that host If the problem persists check Chapter 7 Trouble Shooting ActiveX Clients Parallel Crystal D eveloper s Manual 160 Version 2 4 Revised 5 27 00 The call to the Application O bject method openreport may fail and report the error Invalid file name This error occurs when the report file specified by the argument string does not exist on the Report Server Check the location of the file and then supply its full path name tO OpenReport The
25. PCREGatewayError is used to identify errors that are detected in the G ateway Server and are reported back to the client These errors can arise when the client tries to connect to the G ateway or when the G ateway tries to start your Report Engine Server PCREServerError is used to identify errors that are detected in the Report Engine Server but are not specifically related to the PCRE customization API For example they could be generated by a network failure PCREAPIError is used to identify errors that are detected by the Crystal Reports Print Engine in the Report Engine Server The Server transforms the error into an exception containing the Crystal error number and message and then returns it to the client PCREFatalError and PcREInternal error are used internally by the PCRE package to report catastrophic errors An internal error usually indicates a logic failure within the code while a fatal error indicates an external condition that makes it impossible to continue When handling these errors you should normally terminate your application in an appropriate way In addition to its constructors each error class has a set of methods for throwing and reporting errors The report methods use a corresponding method in the pcrEconsole class to display the error message So if you call the Report method of PCREAPIError then this method will in turn call the pcre API
26. SelectPrinter Parent CancelPrinting Application PrintOut StartParallelPrint PDFOutputOptions ConvertPSTOPDF RunScript ViewLocalPDFFile ClearError Table 6 4 Parallel Crystal D eveloper s Manual 191 Version 2 4 Revised 5 27 00 Interface acquisition Dim reportl As ICRReport report2 As ICRReport reportl app OpenReport C SampleReports Box rpt reportr reportl OpenSubreport Studio one Method and property calls report Title Sample run report RecordSelectionFormula Employee Employee ID lt 10 report OutputToPDF C SampleOutputs Box pdf ICRArea s ICRAreas S the collection interface exposed by the Areas Collection Object The methods and properties are listed in Table 6 5 An Areas Collection O bject is obtained from the Areas property of the parent Report O bject Each item in the collection is an Area O bject representing an area within the parent report and the number of Area Objects is returned by the count property Individual Area Objects are obtained by the 1tem method that takes an index or string argument identifying the area required Visual Basic clients may iterate through all items with the ror Each Statement that calls the Newznum property to create an enumeration of Area Objects Methods Custom Properties N avigation Item Count Parent _NewEnum Report Application Table 6 5 ICRArea s the custom interface exposed by each Area Object in
27. The Parallel Crystal PD F library is the primary method for outputting a report to PDF format This library provides several distinct advantages for a server environment The advantages include e PDF library is completely scalable e PDF library is faster than Acrobat Distiller with the exception of charts e The library maintains accurate page placement of objects e The library will soon support linearized PDF output PDF Output via Adobe Acrobat Distiller MAS also supports PD F generation via Adobe s Acrobat Distiller Support for Distiller is being phased out Distiller has several issues that have prompted the migration to the MAS PDF library The Distiller issues include e Installation Issues If you do not have a PostScript printer driver installed and set to default then Distiller will not install on your computer e Stability issues Distiller is not designed to operate in a server environment where you need to run as a service have multiple instances of Distiller running on separate jobs or multiple Distiller s running on a single job to speed output e Formatting issues The page placement of objects is sometimes inaccurate e Thread Safety Distiller is a single threaded application which means that no matter how many Distillers are started they serialize the output This slows everything down e Size Limitations There seems to be a size limit to the postscript file that can be created by Crystal This is i
28. The important line of code here is in bold PCREApplicationClient client null YourDataObject implements the DORDataSet interface DORDataSet dataObj try connect clien DORDataSet new YourDataObject t to report server client new CREApplicationClient reportserver host com client Connect create engine and job objects PCREEngin ngine client OpenEngine open the repo rt that you created in the previous steps PCREJob job engien OpenJob report_filename rpt set your data object as the data source job SetPrivateData data0bj set the output type and start the report generation job OutputToPDF job Start output_filename pdf null close down and clean up job Close engine Close catch PCREError ex do some error finally handling here disconnect from report server if client null client Quit Parallel Crystal D eveloper s Manual 87 Version 2 4 Revised 5 27 00 Tips for Using DOR Limits on Data Object Size DOR in PCRE 2 3 and 2 4 supports small to medium sized data objects under 25 000 rows of data Using DOR with larger data sets can cause excessive memory usage which can lead to system instability Actual limits of data object size will depend on hardware configuration user traffic and resources available to the program This is an issue o
29. The outputToppr method call uses the D ynalivery PD F Library that extends the Parallel Crystal Report Engine with facilities to render reports directly in PD F It is possible to provide a set of PDF output options as a second argument to output Toppr Further discussion is deferred to Chapter 9 In practice the default operating options are sufficient for most purposes and are automatically selected when the second argument to Output ToPDF is set to NULL Generating a Simple HTML Report If the reports you wish to generate are web based and intended for display exclusively through web browsers then it may be appropriate to generate the report as an HT ML file Example 8 3 below illustrates how the Box Office report can be generated in HTML Again the code only differs slightly from the preceding examples include lt pcre h gt Phd void main int argc char argv PCREApplicationClient client example host com 2 try client Connect Ff S PCREEngine engine client OpenEngine 4 PCREJob job 3 engine gt OpenJob C MobileApps PCRE SampleReports Box rpt PCREHTMLJobExportOptions options C MobileApps PCRE SampleOutputs Box htm1 6 job gt ExportTo amp options 6a job gt Start Vi uae is job gt Close 8 cout lt lt HTML report generated lt lt endl Ld Os engine gt Close 10 catch PCREErro
30. This conversion is possible via an ICRReportPtr Constructor but it has the hidden side effect of increasing the reference count on the report object by 1 You must therefore call Release to return the count to its correct value So the conversion to the smart pointer type must take the form ICRReportPtr report pApp gt OpenReport name vefcount 2 Report gt Release vefcount 1 Report gt PrintoOut e A smart pointer will always call release when its destructor is executed This means that either you have to create artificial scopes or call the destructor manually in order to release the rcrReport interface If you combine these two requirements they imply that you have to restructure the example as follows in order to use the rcrReportPtr type try pApp gt ConnectToReportServer flea acme com Artificial scope to ensure implicit report gt Releas ibp strt name ICRReportPtr report pApp gt OpenReport name refcount 2 report gt Release vefcount 1 report gt PrintoOut Implicit Release call by ICRReportPtr destructor pApp gt DisconnectFromReportServer catch const _com_error amp The example avoided the use of smart pointers by using a static_cast to convert the value returned by openReport from an 1Dispatch pointer to an IcRReport pointer Since IDispatch is the only base class of rcrReport this cast is benign a
31. and these are supplied through helper classes called uxp_xxxOptions For example if you specify the dest inat ionDLLName u2ddisk which saves a report to a disk file then the dest inat ionOptions member should be an instance of the class uxp_piskoptions that holds the path name of the file to be created In Table 3 6 on the next page we list the possible values for format DLLNanme their corresponding sub type values and the format dependent helper class name Then entry none means that the formatopt ions member should be set to nu11 Parallel Crystal D eveloper s Manual 71 Version 2 4 Revised 5 27 00 DLL Name Format Sub type Format Options u2fer dll UXFCrystalReportType one u2fdif dll UXFDIF Type UXF_DIFOptions u2frec dll UXFRecordType UXF_RecordsStyleOptions u2frtf dll UXFRichTextFormatType one u2fsepv dll UXFCommaSeparatedType UXF_CommaTabSeparatedOptions UXF TabSeparatedType UXF_CommaTabSeparatedOptions UXFCharSeparatedType UXF_CharSepatedOptions u2ftext dll UXFTextType UXF_PaginatedTextOptions UXFTabbedTextType UXFPaginatedTextType u2fwks dll UXFLotusWksType None UXFLotusWkilType UXFLotusWk3Type u2fwordw dll UXFWordWinType None u2fdoc dll UXFWordDosType None UXFWordPerfectType u2fgqp dll UXFOP5Type None u2fxls dll UXFX1s2Type UXF_XlsOptions UXFX1s3Type UXFX1s4Type UXFX1s5Type UXFX1ls5TabType u2fodbc dll UXFODB
32. e Report Y our client only has access to a single Report Engine Server so successive calls to OpenEngine Will return the same value When you are finished you should call the close method to release resources in the Report Engine Server If you call openzngine when your client is not connected to a Report Server it will throw a pcREClientError exception Parallel Crystal D eveloper s Manual 272 Version 2 4 Revised 5 27 00 The most important methods of the pcreEngine Class are summarized in Table 9 8 Method Purpose OpenJob Open a print job OpenSubReport Open a sub report PrintReport Start a report run LogOnServer Log on to database server LogOff Server Log off from database server Open Open a print engine Close Close print engine Table 9 8 The ecreEngine Class allows you to produce your report in one of three ways e You can generate the report directly using the printReport method The single argument to the method specifies the name of the report file on the Report Server No report customization is possible with this method e You can open a print job with the opengob method The method takes a single argument specifying the name of the report file on the Report Server and returns a reference to an instance of the pcrEJob Class representing the print job Y ou can call methods of pcrEJob to customize the report and then generate it by calling the
33. function returns FALSE Report to Step 10 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 EOpenEngine opens the print engine in the Report Engine Server If the Error prints the error message and control transfers 5 Once the print engine has been opened we can customize our report by calling PEOpenPrint Job with the full path name of the report file If the function succeeds it returns a positive integer that acts as a handle for the job We pass this handle in all subsequent A PI calls for the job If the function fails ReportError prints the error message and control is transferred to Step 9 6 The call to PEoutputToPrinter tells the Report Engine to send the report to a PostScript printer when the job is started in Step 7 The second argument specifies the number of copies to print 7 The call to pestartPrintJob runs the print job and generates the report document The second argument is required for consistency with the original Seagate API and should always have the value rruz When the function returns the report will be generated but it may not necessarily have finished printing 8 The statement at the label c1ose_job Closes the print job opened in Step 5 Notice that control is transferred here if preceding API calls made after Step 5 failed 9 The statement at the label close_engine Closed the print engine opened in Step 4 Control also transfers here if
34. lt CENTER gt lt H2 gt Choose Report to Process lt H2 gt lt TABLE gt lt TR gt lt lt TR gt lt TD gt lt INPUT TYP VALUE bu lt TR gt lt TR gt lt lt TR gt lt TD gt lt INPUT TYP VALUE C lt TR gt lt TR gt lt lt TR gt lt TD gt lt INPUT TYP VALUE FTE lt TR gt lt TR gt lt TD gt lt b gt Ou lt TR gt lt TD gt lt INPUT TYP VALUE C lt TR gt lt TR gt lt TD gt lt b gt Ou lt TR gt lt TD gt lt INPUT TYP VALUE FT lt TR gt lt TABLE gt lt TABLE gt lt TABLE gt lt FORM gt lt CENTER gt lt BODY gt lt HTML gt SIZE 40 E text NAME OutputFolder SIZE 40 MobileApps PCRE SampleOutputs gt lt TD gt E text NAME OutputName SIZE 40 lt TR gt lt TID gt lt INPUT TYPE submit VALUE Run Report gt lt TD gt lt TR gt When the Run Report button is pressed the browser posts the lt rorm gt to the Web Server The Web Server analyzes the HTTP Post Request and passes it to the SimpleAPICalls asp page When the page is loaded the VBScript interpreter recovers the entries in the form runs the report and returns the results page shown in Figure 5 9 on page 169 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 168 Ej Simple ASP Report Generator Microsoft Internet Explorer of Xx File Edit View Go Favorites Help la 2 Gees Back Forward Stop Refresh Home Search Favorites Print amp ra Address http ww
35. parent report and the number of SortField O bjects is returned by the count property Individual sort fields are obtained by the ttem method that takes an index or argument identifying the field required Visual Basic clients may iterate through all items with the For Each Statement that calls the _NewEnum property to create an enumeration of SortField O bjects Methods Custom Properties Navigation Item Count Parent _NewEnum Report Application Table 6 14 ICRSortField is the custom interface exposed by each SortField O bject in the collection The methods and properties are listed in Table 6 15 They provide access to the number and sort direction for the field Methods Custom Properties Navigation Field Parent SortDirection Report Application Table 6 15 Interface acquisition Dim sfldsc As ICRSortFields field As ICRSortField Set Set Set sfldsc report RecordSortFields field field sfldsc Item 1 sfldsc 2 Collection iteration For Each field In report RecordSortFields field SortDirection crAscendingOrder Next Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 B iCRDataBase ICRDataBase S the custom interface exposed by the Database O bject The methods and properties are listed in Table 6 16 They provide access to the database tables and parameters used in the report A DataBase O bject is obtained from the D atabase pro
36. rather than on the Report Server Therefore we must change the call to Export ToHTML to Report ExportToHTML WebRoot amp amp OutputPath If webRoot is set as Shown output Folder S SampleOutputs and OutputName is PTE rpt then the HTML report will be retrieved to the file C InetPub wwwroot SampleOutputs FTE html 4 Rather than return this path name in the response we can return a hyperlink so that the user can navigate directly to the FTE ntm file We can do this with the following modification to Step 16 If bOK Then Anchor lt A HREF amp Chr 34 amp amp OutputPath amp Chr 34 amp gt Response write lt br gt lt br gt lt b gt Report generated in amp Anchor amp OutputName amp lt A gt lt b gt End If This generates the following HT ML and writes it to the response sent to the user lt br gt lt br gt lt b gt lt A HREF SampleOutputs FTE html gt FTE html lt A gt lt b gt When the user clicks on the hyperlink the FTE ntm1 file will be displayed in the browser 5 If you want the report to open automatically without an intermediate page you can do it by using various page redirection techniques like using Response Redirect in ASP 2 0 or server Transfer in ASP 3 0 If you are using ASP 2 0 and you do not want to use Response Redirect then you can use a javascript client side script to open this new page Parallel Crysta
37. such as data access properties varrants and BSTRS were borrowed from the Visual Basic language The Visual Basic interpreter also hides the low level details of COM so that you need only understand how to access the methods of the tcrapplication and IcRReport interfaces in order to generate simple reports If you re curious to learn more about COM from a Visual Basic perspective then we recommend the book by Ted Pattison Visual Basic Preliminaries In order to access the PCRE Automation Server you must import the Type Library into your Visual Basic D evelopment Project using the Project References display shown in Figure 5 3 on page 154 e First check that PCRE Automation Server has been installed AND registered on the machine running Visual Basic e Start the Visual Basic D evelopment Environment and create or select your VB project e Select the VB menu entry Project References The list box shown in Figure 5 2 appears e Locate the entry cpemas1 1 0 Type Library and check the box to the left e Click on OK 1 Ted Pattison Programming Distributed Applications with COM and Microsoft Visual Basic 6 0 Parallel Crystal D eveloper s Manual 153 Version 2 4 Revised 5 27 00 References Simple vbp Available References Cancel visual Basic For Applications visual Basic runtime objects and procedures visual Basic objects and procedures OLE Automation Browse
38. 3 Parallel Crystal D eveloper s Manual 58 Version 2 4 Revised 5 27 00 Argument Purpose verbose Switch on Report Engine Server tracing This is useful if you are running Parallel Crystal on the desktop and you wish to see full tracing in the Report Engine s G UI folder directory directory Specify the Report Engine Server working directory This lets you specify report files with path names relative to this client name Specify the name of the client If you are running Parallel Crystal on the desktop the Report Engine will display this string to help you identify your server amongst many Table 3 4 Here are two example fragments that specify the same arguments in equivalent ways Supply arguments in a single call try PCREServer server client getServer server setArguments client toby folder C MonthlyReports The server will be started with arguments supplied client catch Add argumen Connect PCREError error error Report ts in multiple calls Argument values are supplied through calls to user interface dialogs ay try PCREServer server client getServer String name ClientNameDialog server addArgument client name String folder ClientFolderDialog j server addArgument folder folder The server will be started with the arguments supp
39. 6 VADs 8 9 10 11 12 13 Each numbered paragraph below corresponds to the same numbered code statement 1 Parallel Crystal Java clients use the Parallel Crystal Client package called com mobileapps pcre In order to access the public classes in this package you must import it into your Java program by means of the import statement shown You must also ensure that the form of the import statement is consistent with the setting of the CLASSPATH in your Java development environment The PCRE package is currently distributed as a jar file whose full path name assuming installation on drive C is C MobileApps PCRE jars PCREjavaclient jar Your CLASSPATH must include this path name to access the package The correct adjustments to your CLASSPATH are normally made during installation 2 The declaration creates an instance of the PCREA pplicationClient class The constructor call specifies the host name of the machine running the Parallel Crystal Report Server as an argument string This constructor assumes that the gateway is broadcasting its initial reference to the default port Note Thevalue example host com is only an example and must be replaced with a valid host name 3 This statement connects the client to the Report Server running on the machine specified in Step 2 It is included in a try catch block so that if the call to connect fails an exception will be raised and control will transfer
40. 6 specified that the final report was to be sent directly to a PostScript printer rather than be stored in a file If this call is omitted then the Print Engine DLL will raise an exception when the client executes the pest artPrintJob Call on Step 7 and ReportError will print the following message no print destination specified We ll look at other ways to specify the output for a print job in the next two sections S Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Generating a Simple PDF Report Adobe s Portable D ocument Format PD F is widely used as an alternative to PostScript or HTML on the Internet It provides PostScript quality reproduction using a more compact document encoding format Example 8 5 on page 234 illustrates a simple C client that outputs a version of the Boxoffice report to PD F We have omitted the Report include lt pcre h gt include lt stdio h gt void main int argc char argv short job BOOL bOK PEInitialize NULL example host com argc argv PE_DO_CONN if boK J 4 ReportError 0 goto close_app if PEOpenEngine ReportError 0 goto close_app job PEOpenPrintJob C MobileApps PCRE SampleReports Box rpt if job al ReportError job goto close_engine if PEOutputToPDF job C MobileApps PCRE SampleOutputs Box pdf NULL ReportEr
41. CONSOLE ITAA LAETTE ATE E E A E E E ET 96 Parallel Crystal Report Retrieval Are eri i r ea a STA ORT ens wate cen aaa wa LR S ETEA AERA AEE EE Nase 99 Retri valito Application CU ents icc vcieses geni eerie o Ea E E EA ERE REETA AOE ET everedisonescdhe 99 Retrieval to Applet Cent wi ssc sccasesceavevissecaatevevssscccsssancevavesavea Ta KO REET ODARE OSE ERE EEEIEE OOOPS SSE EEROR EEE RESTEREN EEEREN EASES 100 Parallel Crystal Configuration Servet mirerien osii a ea ea nioe ieS EEE E EENDE ERREA OTER EE ARSENE NEO CSS AE EETA EE 101 Parallel Crystal Load BQlancetsccciciscaieiscavusdcscusvtadeivendccnceasusscsvenddessuasesecuvcedeasebesedasetendeacuvosuvedevssddiasucatiedevedadse Eeoa oE Ae EETAS EE 103 Automatic Mode i Manual Mode sonnii innsti aane TANS EAIA EAI ETE LDS EEEE ES EO EEA WEES AT ASA TIES EEEE ENEE ETEEN M lti threaded CHentS oirr ea e E ARANOREN ESEE AEN NE SGS 106 Chapter 4 Trouble Shooting Java Clients cscsssssssssssscssssssssssssssssesssssssesssessessessessesessessssessssessssessesessessssasscsessassesessessssesssseseses 109 Problems with CLASSPATH yess far as o aah d aerate asd eee Sas ADA NTS Ned N estilo etal AM Stas 109 Common Problems with Client Connections ccceccecescescesccescseeecsecseesessesesecseescsesseecssssesessseessesecsesseessessseeseseesseseeeeeseeaeeges 110 Problems withiA pplets iniisa REESE EERE OOE AA AEAEE EERE eSEE TEER EEEE DEVEL KEEA AENEASE TENS 112 Problems with Export Formats 114
42. Connecting to the Automation Server Connecting tothe Report Server vsssessccessccacevevsescccsssszasusvea ceca TE SEEE NEEESE ERETO NETET EEEE NEIERE E RS Disconnecting from the Report Server a Disconnecting from the Automation Server cce cece eceecseescsecseeecsessesessesecseeecsessesecsssessesassecseecsscaesesssssesesaseessesaeessaeeeseges 185 Report Generation vaca saccsdasesscesvasdecisdaes ss i saht ra raS Ve RESE re SEBESEN SEENED ESCEA SORES EEST r SEPRE SVA TORSK ERARE cess Saacpscadssasecsdoateseaigveiesstaat eae OFE TETERE 186 ICRApplication l TCRG ob al Options aise eaaa eonia ARa AEAEE OA AERE EE OEA e E A AEA E AAEE EAE EERENS 190 ENS BUE E A E E E N E AEE E E E T E S 190 ICRReport 191 ICRArea s 192 ICRAreaOptions 193 IGRGroupArea Options o coiros reisai EE a EE EEE ERRETES ESIA ETEISEEN EEEE T SEEE Ua CTE NEIERE EEEO NINETEEN SEES 194 TERS ECOG errre eerte chee savy casaeweyeetateny NEEE ENESTI AEAEE EN REER OS EENE NI AENEA 194 ICRSectionOptions 4 I RREPOMtOD Set S eieae riisi aste EEE as vacates unas vata vsdanvunedacbusurdectsuedseonduucdsavecieavseuncecuesnaccevreuncaiessa get EAEE IGRSortPield s ee oseere VeeS E O EOE EANET EEO ween sean seed Eia ICRDataBase ICRDataBaseTable s ICRDataBaseFieldDefinition s 201 IGRDataB aseParariieter s cssccveciseeovecavexosscavvosssqabeezesecsvazeusayvacssdevvatsddenvutes EEE TEA EA OEE saree OESE EES EEO EAEN 202 ICRPrintin eSta
43. Crystal Automation Server that is described in the next section 1 The terms O bject Model and Object Library are equivalent Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 ICRApplication ICRGlobalOptions ICRArea s ICRAreaOptions ICRGroupAreaOptions ICRSection s ICRSectionOptions ICRReportObject s ICRSubReportOb ject ICRSection s ICRSortField s ICRDataBase ICRDataBaseTable s ICRDataBaseFieldDefinition s ICRDataBaseParameter s ICRPrintingStatus ICRPrinterInfo ICRReportSummaryiInfo ICRExportOptions ICRReportOptions ICRFormulaFieldDefinition s ICRSummaryFieldDefinition s ICRParameterFieldDefinition s Figure 5 1 Parallel Crystal D eveloper s Manual 125 Version 2 4 Revised 5 27 00 The Parallel Crystal Automation Server The Parallel Crystal Automation Server is a D LL that provides the hierarchy of Automation O bjects in the PCRE O bject Model Although it is referred to as a server the DLL must reside on the same machine as your client automation controller If the controller is VBScript embedded in an ASP page then the DLL should be installed on the Web Server s host D etails of the installation are given in the section Connecting to the Automation Server in the next Chapter When the Automation Server D LL is loaded it uses the Parallel Crystal C C client to establish a connection to the Report Server
44. D esigner Parallel Crystal D eveloper s Manual 81 Version 2 4 Revised 5 27 00 Installing DOR to RPT Utility The DOR to RPT Utility should be installed on the machine that will be used to design DOR reports This may be a different machine than the one used as a Client to run reports This utility is installed using an automatic install program called D O RReportUtility exe This program is placed into the MobileA pps PCRE DataO bjectReporting folder during a Parallel Crystal installation Determine which computer will be used to design DOR reports and copy the DO RReportUtility exe onto that machine Then run the DO RReportUtility exe install program and the utility will be automatically installed Analyze the Data Source It is important to identify and analyze the data source before attempting to use DOR The process of preparing report templates requires knowledge of the type of data source involved If your data source is a database then you can use the ResultSet adapter If not or your data is being generated calculated or exists in an object or a set of objects then you need to implement the D O RD ataSet interface Implementing the DORDataSet Interface The DORDataSet interface is used by the PCRE Java Client to examine a data object The interface has two main parts e A set of data type constants which provide a way of specifying what data types an object contains in a manner that is compatible with C
45. D eveloper s Manual Version 2 4 Revised 5 27 00 aA 3 The procedure set Buttons is a utility that is used to set the Enabiea property of each of the command buttons Private Sub setButtons cb As Boolean rb As Boolean db As Boolean cmdConnect Enabled cb cmdRun Enabled rb cmd Disconnect db End Sub 4 The procedure rorm_Load is called when the application form is loaded for the first time Private Sub Form_Load On Error GoTo fail bConnected False Set app New CRApplication setButtons True False Fals Exit Sub fail sgBox Failed to connect to PCRE Automation Server Set app Nothing End Sub The procedure creates a new instance of the PCRE Application O bject and stores a reference to it in the variable app If the call to new fails the COM error is automatically detected by Visual Basic and control will transfer to the error label fail If the call to new is successful the Connect button is enabled N ote that the argument to New is the name of crapplication co class that provides the ICRApplication interface 5 The procedure Form_un1oaa is called when the application is terminated Private Sub Form_Unload Cancel As Integer If bConnected Then cmdDisconnect_Click Set app Nothing End Sub If the client is still connected to the Report Server the cmadDisconnect_Click procedure is called to disconnect Then the variable app is reset to Nothing that releases
46. D eveloper s Manual 217 Version 2 4 Revised 5 27 00 Note that the automat icLoadSharing property must be set before the call to Connect ToReport Server If you forget to set the property then each of the calls to Connect ToReport Server Will locate a Report Server somewhere on your network without involving the Load Balancer If you do supply a host name when aut omat icLoadSharing is true then ConnectToReport Server Will try to use the Load Balancer on the specified host However if there is no Load Balancer running on the host connect ToReportServer Will fail and LastErrorString will retum the message Server error cannot connect client to Load Balancer Service In general it s simplest just to use the automatic mode as shown If the Load Balancer is unable to locate any Report Servers calls to ConnectToReport Server Will fail and LastErrorstring Will return the message Server error Load Balancer failure no available Report Servers This error can occur either because no Report Servers were running or because the installed Report Server have not been configured to use the Load Balancer Service You should check with installation and configuration of Parallel Crystal if this error persists Using the Load Balancer in Manual Mode When you use manual mode the Load Balancer returns a list of available Report Servers You apply your own selection criteria to the list and then call the Connect
47. ErrorMsg method of the client s console The hierarchy of error classes allows you to distinguish between various kinds of errors and to handle them individually or as a group For example in most of the programming examples we have used a simple try catch block in the following way PCREApplicationClient client try null client new PCREApplicationClient example host com client Connect PCREOpenEngin ngine client Open Open job do API calls engine Close xj catch PCREError e e Report Parallel Crystal D eveloper s Manual 93 Version 2 4 Revised 5 27 00 Although this code is correct errors with very different causes will transfer control to the same exception handler and this may leave your program in an uncertain state We can be more discriminating in the treatment of errors by using specialized try catch blocks in a variety of ways PCREApplicationClient client try client Add client customization code here client Connect catch PCREError e Handle all connection errors here null try PCRE try PCREJob job Engin ngine client OpenEngin engine Open C ACM job processing phase 1l try Customization method calls catch PCREAPIError el E ua Handle API errors in this phase here
48. ExportTo OF Output To API call If you wish to view the file then you will normally have to retrieve it back to the client machine The way in which you do this depends upon the report file format PostScript PD F HTML or other the nature of your Java client application or applet and the configuration of your Parallel Crystal installation We ll explore all these possibilities in the following sections Retrieval to Application Clients If you have an application client you can use the Parallel Crystal Report Retrieval Service to return your report Y ou activate this service by calling the client s setRetrieveMod property method with the argument value t rue and you specify a path for the report file on the dient s machine rather than the Report Server machine The following example shows how the Report Retrieval Service is used to return a PDF report to the client machine client setRetrieveMode true Mehadi client Connect LI Rs PCREEngin ngine client OpenEngine PCREJob job engine OpenJob JA a C MobileApps pcre SampleReports Box rpt job OutputToPDF C MyReports Box pdf null Aelg job Start LP Ba job Close engine Close Each numbered paragraph below corresponds to the same numbered code statement 1 The automatic Report Retrieval Service is activated by calling setRetrievemoae with the value true 2 The client is connected to the Report Server on ex
49. FormulaField D efinition O bject representing information stored in a formula field in the report and the number of FormulaField D efinition Objects is returned by the count property Individual FormulaField D efinition O bjects are obtained by the rt em method that takes an index or argument identifying the parameter required Visual Basic clients may iterate through all items with the For Each statement that calls the _NewEnum property to create an enumeration of D atabase Parameter O bjects Methods Custom Properties Navigation Item Count Parent _NewEnum Report Application Table 6 28 ICRFormulaFieldDefinition S the custom interface exposed by each FormulaField Definition O bject in the collection The methods and properties are listed in Table 6 29 They provide access to the name kind and content attributes of the field Methods Custom Properties Navigation Properties Check Kind Parent FormulaFieldName Report Name Application Text Table 6 29 Parallel Crystal D eveloper s Manual 208 Version 2 4 Revised 5 27 00 Interface acquisition Dim ffldc As ICRFormulaFieldDefinitions Dim field As ICRFormulaFieldDefinition Set ffldc report FormulaFields Set field ffldc Item 1 Set field ffldc 2 Collection iteration For Each field In report FormulaFields If field Kind crParameterField Then field Text field Text amp 10 If Not field Check Then Exit For End
50. Manual 241 Version 2 4 Revised 5 27 00 job PEOpenPrintJob if job xf ReportError job if PEOutputToPrint ReportError job if PEStartPrintJob ReportError job C MobileApps PCRE SampleReports Box rpt goto close_engine er job 1 goto close_job job TRUE goto close_job printf Report generated n close_job if PEClosedJob job close_engine PECloseEngine close_app PEUninitialize ReportError job Example 8 5 10 Each numbered paragraph below corresponds to the same numbered code statement 1 Parallel Crystal C clients use a Parallel Crystal Client Library called cppclient dll In order to access the classes in the library you must include the header file pcre h into your program at compile time and you must ensure that the installation directories C MobileApps pcre CppClient include C MobileApps pcre Visigenic vbroker include are on the include path in your development environment The call to p the Report Server on host example host com If the function returns rats e the function Report Initialize initializes the Client Library and establishes a connection to Error retrieves and prints the error message on the standard output stream and control is transferred to Step 10 The call to p
51. PCREJob job engine OpenJob C MobileApps pcre SampleReports Box rpt PCREJobExportJobInfo info new PCREExportJobInfo info formatDLLName u2ftext dll info formatType PCREJob UXFTextType info formatOptions null info destinationDLLName u2dmapi dll info destinationType PCREJob UXDMAPIType UXD_MAPTIOptions options new UXD_MAPIOptions options toList director reporthost com options ccList options subject Box Office Report options message Here is your Box Office Report r n n info destinationOptions options job ExportTo info job Start Early releases of Parallel Crystal use the export To method to generate reports in PDF When the Report Engine Server receives export information specifying UXFPDFDistillerType as the output type it generates the report in PostScript and then invokes the A dobe Acrobat Distiller utility to convert the PostScript into the final PD F file A helper class called pcREPpDF JobExport Info generates the required PCREJobExport Info by specifying the output file in a simple constructor call The following example shows how to use this class PCREJob job engine OpenJob C MobileApps pcre SampleReports Box rpt PCREPDFJobExportiInfo info new PCREPDFJobExportiInfo C MobileApps pcre SampleOutput Box pdf job ExportTo info job Start Although PDF gen
52. Server The constructor argument orb allows you to install a customized O bject Request Broker in your client If this argument is null the client uses an O RB that is created using the argv and props arguments Applet Client Instantiation The pcrREAppletClient Class allows Java applets to connect to the Parallel Crystal Report Server The client has connect and disconnect methods and acts as a container for service provider classes that enable client side access to Report Server services Y ou must install a console in the client to adapt error reporting to the user interface provided by your applet A PCREAppletClient is instantiated using a constructor like this PCREAppletClient PCREConsole console String host int port java applet Applet applet Properties props org omg CORBA ORB orb throws PCREClientError All arguments have the same meaning as their equivalents in the PCREApplicationClient constructor with the exception of app1et that identifies the applet instance that contains your client It is not possible to supply default values for either the console or the applet since each is specific to your applet For example the console you supply must adapt the abstract pcreconsole interface to the specific user interface requirements of your applet It is not appropriate to supply a default instance of the character based pcREApplicationConsole in this case Parallel Crystal D evelop
53. Sub S gt lt bOK True Err Clear v0 ReportServer Request Form ServerName ile a ReportFolder Request Form ReportFolder ReportName Request Form ReportName ReportPath ReportFolder ReportName OutputFolder Request Form OutputFolder OutputName Request Form OutputName OutputPath OutputFolder OutputName lt TR gt lt TD gt lt b gt Report Server name lt b gt lt TD gt lt TD gt lt b gt lt Report Server gt lt b gt lt TD gt lt TR gt lt TD gt lt b gt Report Path Name lt b gt lt TD gt lt TD gt lt b gt lt ReportPath gt lt b gt lt TD gt lt TR gt lt TD gt lt b gt Output Path Name lt b gt lt TD gt lt TD gt lt b gt lt OutputPath gt lt b gt lt TD gt lt TR gt lt TABLE gt A oe Oo On Error Resume Next I0 Dim PCREApp Set PCREApp Server CreateObject MAS CRApplication 1 11 If Not IsObject PCREApp Then 12 ReportError Report Server not available End If Example 5 4 cont on next page Parallel Crystal D eveloper s Manual 170 Version 2 4 Revised 5 27 00 If bOK Then n s PCREApp ConnectToReportServer ReportServer If Err Number lt gt 0 Then ReportError Cannot connect to Report Server on amp _ ReportServer End If End If If bOK Then 14 Dim Report Set Report PCREApp OpenReport ReportPath I
54. a particular instance of the Server on that host The connections are established by a component called the O SA gent as follows e If both host and name are specified the O SAgent looks for a named server on the host e If only the host is specified the O SA gent looks for any server on the host e If neither host nor name is specified the O SA gent looks for any server on any host The Report Engine Servers are assigned unique names by the G ateway so that they can be identified to their clients The G ateway Server is normally assigned the default name pcre A client is always connected to G ateway and Report Engine Servers on the same host Occasionally it may be more appropriate to make connections based on logical Server names rather than Report Server hosts In order to do this you must omit the host from the client constructor call and use the pcrEGat eway S setName property method as follows PCREAppClient client try client getGateway gt setName purple client Connect Use report server catch PCREError amp e e Report This code will then try to connect your client to a Report Server running the G ateway named purple If the connection is made the G ateway will start a Report Engine Server on the same machine and return its name and host to the client You must ensure that the argument supplied to the setName method matches the name of a Gateway running o
55. a pcreapierror with the message PCRE API error Logon failure This is a standard Crystal Reports failure message It occurs if the password and or username requested by the data source are not supplied correctly They are normally incorporated into the report file at design time but you can override the entries when you call the togonserver method of pcreEngine You should check that the details of the ODBC or other data source administrator on the Report Server match the settings on the machine where the report was designed To help prevent this problem we recommend that whenever possible you design your reports in the same environment in which you expect to run them e A call to the start method of pcregob may report a pcrREAPIError with the message PCRE API error Request cancelled by user This is a standard Crystal Reports failure message that can occur if the report cannot be sent to the nominated printer You should check the availability of the printer or the print settings established by any calls to the selectPrinter method of PCREJob Parallel Crystal D eveloper s Manual 17 Version 2 4 Revised 5 27 00 Chapter 5 Getting Started with ActiveX Clients This chapter describes how to write Parallel Crystal clients using Microsoft ActiveX COM development tools such as Visual C Visual J Visual Basic and Active Server Pages The chapter is divided into six sections
56. an error occurs in any of the preceding method calls We will discuss error handling in detail in Chapter 9 but for the present its sufficient to note that by specifying the base class pcreError in the handler we can trap all exception classes raised by the C Client In this simple example we choose to handle the error by calling its Report method that prints the error on the current output stream The pcrREAppClient destructor will be automatically invoked on the ciient instance before returning from the function main The destructor will close the client s connection to the Report Server and release resources If you create the client dynamically on the heap then you should terminate it with a corresponding call to delete For example PCREAppClient client new PCREAppClient example host com client gt Connect delete client We ll try to summarize this example as a set of rules that you can use to develop your own applications Access the Parallel Crystal C Client Library by including the header file pcre h Create an instance of the pcrzappclient Class using the host name or IP address of the machine hosting the Report Server Call the connect method to connect your client to a Report Engine running in the Server Open a print engine by calling the openEngine method of your client Use the PCREEngine instance returned by openEngine to open one or more print jobs Each job is sp
57. and its Report Server can be tested independently of other production environments Whenever the O SA gent port is changed you must supply the new value to your client and your Report Server must also be re configured by the System Administrator You can supply the O SA gent port number to your client by setting the osacENT_PORT environment variable to the required value or you can use the orBagentPort command line argument and pass this to the client constructor For example given int main in argc char argv PCREAppClient client example2 host com argc argv try client Connect catch PCREError amp e e Report If the O SAgent is running on port 17000 then you must start the application with the command line MyApp exe ORBagentPort 17000 If your application is a C client then you can use the same command line and pass the argument in the call to pEtnitialize PEInitialize NULL host argc argv Y our client communicates with the O SA gent using UD P broadcast packets that are normally confined to a subnet of your LAN If you are trying to connect to a Report Server on a remote network you may need to supply the client with the IP address of the remote O SA gent Parallel Crystal D eveloper s Manual 310 Version 2 4 Revised 5 27 00 You can supply the O SAgent IP address to your client by setting the osacENT_ADDR environment variable to the correct va
58. arguments The wrapper s method calls the real openReport method as follows inline HRESULT ICRReport PrintOut cons cons cons cons cons cons _variant_t amp PromptUser _variant_t amp NumberOfCopy _variant_t amp Collated _variant_t amp StartPageNumber _variant_t amp StopPageNumber _variant_t amp OutputFileName HRESULT _hr raw_PrintOut PromptUser NumberOfCopy Collated StartPageNumber StopPageNumber OutputFileName if FAILED _hr com_issue_errorex _hr this _uuidof this return _hr The wrapper class declares the printout method with six optional arguments If the caller omits an argument the wrapper supplies a missing parameter value 8 The ICRReport interface is discarded by calling its Release method The reference count is reduced to zero that deletes the Report O bject and in tum closes the associated print job in the Report Engine Server 9 The DisconnectFromReportServer method is called as before 10 Calls to the _com_issue_errorex function raise exceptions of type _com_error that are trapped at this handler In this example we use the body of the catch clause to extract text of the last recorded error message by calling ICRApplication GetLastErrorString This method returns a BstrR but the wrapper class automatically provides the conversion to a char 11 The papp smart pointer destructor is executed here causing the release method to be called on the
59. by the Report Engine when it is unable to locate a suitable printer This is either because the printer has become inaccessible because of network problems or because the printer settings inserted into your report at design time are no longer valid You may need assistance from either your System Administrator or Dynalivery Technical Support Staff to fix this problem Parallel Crystal D eveloper s Manual 178 Version 2 4 Revised 5 27 00 Chapter 6 Using the PCRE Automation Server This chapter provides detailed information on how Automation Server clients access and use the Parallel Crystal Report Server The chapter is divided into the following sections The section entitled Automation Server Clients describes how clients connect and disconnect to and from the Report Server via the Automation Server The relevant methods of the tcrapplicat ion interface are described in detail for clients using Visual C Visual Basic VBScript and Visual J and for local and remote connections The section entitled Report G eneration describes hierarchy of Automation O bjects in the PCRE Object Model Each object is described by listing the methods and properties of its interface and giving simple examples showing how objects are created and methods and properties are invoked For brevity these examples are given in Visual Basic and you are referred to the Automation Server s online documentation for the syntax for other languages Th
60. call to the Report O bject method export TontTmL may fail and report the error Disk full This highly misleading message is actually returned by the Report Server and means that it was unable to create the HTML file to hold the generated report It does not mean your disk is full Check the argument string for Export ToHTML specifies a valid drive and path name and that access permissions on the Report Server file store allow the file to be created The call to the Report O bject method printout may fail and report the error Cancelled by user This message is returned by the Report Server when it is unable to locate a suitable printer This is either because the printer has become inaccessible because of network problems or because the printer settings inserted into your report at design time are no longer valid You may need assistance from either your System Administrator or D ynalivery Technical Support Staff to fix this problem Parallel Crystal D eveloper s Manual 161 Version 2 4 Revised 5 27 00 Using Parallel Crystal with Active Server Pages This section describes how to write an Active Server Pages client to generate simple reports in PostScript PD F and HTML The contents apply to ASP 2 0 running under Microsoft s IIS 4 0 Web Server Active Server Pages is a web development technology that allows HT ML pages to be composed dynamically using a scripting engine that executes inside the IIS Web Server Pag
61. calls the target method VBScript uses this mechanism in all its method calls Scripting languages that are partly compiled like Visual Basic and Visual J are able to use disp interfaces in an early bound fashion by performing the name to DISPID look up at compile time However the latest versions of Visual Basic5 and 6 incorporate a compiler which allows compiled VB clients to access custom interfaces through their v tables If Parallel Crystal is to be accessible to automation controllers such as VB or VBScript its functionality must first be exposed in some CO M compatible way This is achieved through the Parallel Crystal O bject Model that we describe in the next section 1 The terms automation controller and automation client are used interchangeably in this manual Parallel Crystal D eveloper s Manual 123 Version 2 4 Revised 5 27 00 The Parallel Crystal Object Model The Parallel Crystal O bject Model exposes the PCRE customization interface through a hierarchy of automation objects shown in Figure 5 1 on page 125 The hierarchy is designed to reflect the internal organization of a Crystal Report as a collection of areas sections and fields and is managed through interfaces that conform to Microsoft s conventions for document centric automation enabled applications In particular e The hierarchy is rooted at an Application O bject offering the interface ICRApplication This interface allows clients to connect to
62. cannot execute PCRE Server the PCRE G ateway was unable to start a Report Engine Server process for your client The most likely reason is that the path configured for the server s executable at installation has become invalid Y ou should check the Parallel Crystal installation with your System Administrator or D ynalivery Technical Support Staff If the LastErrorstring property returns the message PCRE Gateway error timeout after 15 secs PCRE Server not started the PCRE G ateway was not able to start a report Engine Server process within the allotted 15 second timeout period This occurs when the Report Server is particularly busy If the problem persists you should get your System Administrator to re configure the G ateway with an extended timeout period You tried to connect using the Load Balancer but it was unable to locate any Report Servers In this case it is possible that the Report Servers were not configured to use the Load Balancer Service or there is an inconsistency in the way the Load Balancer is configured Y ou should get your System Administrator to check the current Load Balancer configuration If problems connecting to the Report Server persist the causes may be more obscure First you should check the status of the O SA gent that administers client server connections by keeping a dynamic record of the CORBA servers running on your network The following problems can arise with O SA gents 9 10
63. class encapsulates information about the format and the destination of the report For example public class PCREJobExportiInfo public String formatDLLName public int formatType public Object formatOptions public String destinationDLLName public int destinationType public Object destinationOptions Parallel Crystal D eveloper s Manual 70 Version 2 4 Revised 5 27 00 The report format is defined by the format DLLName and format Type members The DLL name specifies a D LL which must be supplied with the Parallel Crystal Installation and which generates the report in the appropriate format Some formats have minor variations and so the format Type name is used to hold a numeric value specifying sub typing information For example there are five variants of Excel format available represented by constants called uxrx1s2Type UXFX1s3Type etc Some output formats take additional format dependent data and these are supplied through a variety of helper classes called uxF_xxxOptions Each options helper has a constructor that makes it easy to instantiate the class with the appropriate additional information The report destination is supplied in a similar way through the dest inat ionDLLName dest inationType and dest inat ionOptions members The destination DLL specifies a DLL that is responsible for dispatching the report The dest inat ionOptions member supplies additional destination dependent data
64. client programming In fact because of the nature of the Java programming language you will not be able to construct client programs without including try catch blocks around most API calls We ll describe the error handling facilities in the PCRE package in more detail in the next chapter Parallel Crystal D eveloper s Manual 36 Version 2 4 Revised 5 27 00 Generating a Simple PDF Report Adobe s Portable D ocument Format PD F is widely used as an alternative to PostScript or HTML on the Internet It provides PostScript quality reproduction which is far superior to HTML using a more compact document encoding format Example 2 2 on page 37 illustrates a simple Java client that outputs a version of the Boxoffice report to PDF It is in fact identical to Example 2 1 with the exception of the single line highlighted import com mobileapps pcre Ld ds class PDFExample public static void main String args PCREApplicationClient client null try client new PCREApplicationClient example host com client Connect Th Bs PCREEngin ngine client OpenEngine A PCREJob job engine OpendJob C MobileApps PCRE SampleReports Box rpt ET Ds job Output ToPDF C MobileApps PCRE SampleOutputs Box pdf null E E job Start 7 job Close LTB System out println Report generated JOE engine Close LL AO catch PCREError e
65. don t need to worry about memory management because the underlying CO M interface handles this automatically Disconnecting from the Automation Server Y our client is disconnected from the Automation Server when the rcrapplication interface is released In practice this is performed automatically by all clients except those using bare COM from C In that case following the call to DisconnectFromReport Server you should call Release as follows app gt DisconnectFromReportServer app gt Release This causes a final release of memory resources in the Automation Server R Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Report Generation The Parallel Crystal Automation Server provides a collection of Automation O bjects whose interfaces may be used to customize and generate reports Collectively they are a subset of those provided in Seagate s Crystal O bject Library since they omit functionality relating to report design However they include extra properties and methods for controlling aspects of the Parallel Crystal Report Server such as Client Connections Report Retrieval and Load Balancing These topics are described in more detail later in this Chapter The interfaces in the Automation Server form a hierarchy called the PCRE Object Model which is shown in Figure_5 1 on page 125 in the previous chapter and is reproduced here in amore compact form ICRApplication ICRGlobalOptions I
66. error No connection to a Server Report Engine has been made There are two possible reasons for this error either the argument string does not specify a valid host name or the Parallel Crystal Report Server was not running on the specified host Check that the string you supplied is either a valid host domain name or IP address and then check that Parallel Crystal is installed and running on that host If the problem persists check Chapter 7 Trouble Shooting ActiveX Clients Parallel Crystal D eveloper s Manual 177 Version 2 4 Revised 5 27 00 The call to the Application O bject method openreport may fail and report the error Invalid file name This error occurs when the report file specified by the argument string does not exist on the Report Server Check the location of the file and then supply its full path name tO OpenReport The call to the Report O bject method export TontTmL may fail and report the error Disk full This highly misleading message is actually returned by the Report Engine and means that it was unable to create the HTML file to hold the generated report It does not mean your disk is full Check the argument string for Export ToHTML specifies a valid drive and path name and that access permissions on the Report Server file store allow the file to be created The call to the Report O bject method printout may fail and report the error Cancelled by user This message is returned
67. generate a report in PDF and save the results replace the call to printout with the following call to output ToPDF Step 12 CRStr file C MobileApps pcre SampleOutputs Box pdf hr report gt OutputToPDF file if FAILED hr throw CRError report When the method returns the PDF report will be stored in the file Box pa in the SampleOutputs directory B Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 To generate a report in HTML and save the results replace the call to printout with the following call to Export TOHTML Step 12 CRStr file C MobileApps pcre SampleOutputs Box html hr report gt ExportToHTML file if FAILED hr throw CRError report When the method returns the HTML report will be stored in the file Box htmi in the SampleOutputs directory If the report has embedded images the corresponding JPEG files will be stored in the same directory The tcrReport interface has a number of other methods that you can call in the same way to generate reports in Excel or Microsoft Word format There is also an Export ToppF method that generates PDF using a PostScript to PDF conversion utility called Adobe Acrobat Distiller To generate a report in PostScript and save it in a file replace the call to printout with the following call to output Tops Step 12 CRStr file C MobileApps pcre SampleOutputs Box ps
68. handle to the PCRE Configuration Server PEGetCustomServer Retum a handle to the PCRE Custom Server Table 9 5 You must call pztnitialize before calling any of these functions For example PEHANDLE gateway PEHANDLE config BOOL bO bOK P K EInitialize NULL example2 host com 0 NULL PE_DO_CONNECT gateway PEGetGateway config PEGetConfigServer j The handles returned by these accessory functions can be used in calls to get or set properties for the associated servers We ll describe these calls in the next two sections Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Accessing PCREGateway Properties from C You can access the G ateway Server properties through the API functions listed in Table 9 6 Each function takes the handle returned by a previous call to pEGet Gateway as its first parameter and gets or sets a property associated with the connection to the G ateway The functions return the value True if they succeed and Fase if there was an error The error message can be retrieved with a call to peEGetErrorText If you want to set a property you must call petnitialize with aPz_no_connect argument then call the set function then call p EConnect to make the connection using the modified property value The set functions return rarse if they are called after pEconnect
69. hr report gt OutputToPS file if FAILED hr throw CRError report The report will be generated in the file Box ps in the sampleoutputs directory Note that you cannot depend upon the file being completely generated when you return from the method call This is because the file must be generated by the Windows Printer Spooler that does not run synchronously with the Report Engine Server Notice that all these methods cause the print job to be started Therefore you must complete all necessary customization in previous method calls Generating PostScript Reports with Visual C and COM In the previous sections we showed you how to call the PCRE Automation Server with the low level COM APIs The examples showed that CO M programming can involve much repetitive boilerplate code and we used some wrapper classes to try to conceal this overhead The wrappers were designed to address the following problems Parallel Crystal D eveloper s Manual COM disp interfaces use a Visual Basic string type called a nstr C automation controllers need classes that allocate and de allocate storage for this type and manage the conversions between C style and VB style string formats The COM API is intended to be language independent and it is not possible to throw exceptions from a method of a CO M class However COM does possess APIs that allow a caller to retrieve error information deposited by the method and to reconstruct a
70. if number lt 0 handle error Select the Report Server host MySelection servers number Connect to selected Report Server if PEConnectWithReportServerInfo amp host handle error Make API calls Disconnect from Report Server PEUninitialize The call to PERequestReport ServerInfo returns the number of elements in the vector If this number is less than or equal to zero an error has occurred and you should call PEGetErrorText he comments at the end of the previous section apply to the C client as well g Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Multi Threaded Clients The Parallel Crystal C and C clients are designed to enable you to build multi threaded applications Thread safety is provided using thread local storage and synchronized access to C class instance variables The performance impact on the customization methods of the pcrEEngine and pcREJob Classes is minimized by managing their instance data with a write once read many access protocol When you initialize aC or C client you create a context that includes the thread on which the constructor was invoked the console for the client the set of service provider classes and the connection to the Report Server Since each client has its own Report Engine Server you can create applications in which multiple c
71. in the ANSI C API If your preference is for object oriented languages like C or Java then it is more likely that you will want to use the simple C class library or the Java package Finally if you are familiar with Visual Basic or Microsoft Active Server Pages then the scripting interface offered by the Automation Server will most likely be the simplest option In order to convey the general flavor of working with the PCRE customization API Example 1 1 shows a simple Java program that generates a report using one of the well known sample Crystal report files Even if you don t know the Java programming language the example should convey the notion of connecting to a print engine specifying the details of a print job that is to run on that engine and finally starting the job The final report will be sent to an available printer Parallel Crystal integrates the various versions of the customization API into client frameworks that allow Report Engines to be accessed on networked Report Servers In the next section we explain the Report Server concept in greater detail and describe how the client frameworks may be used within the context of the modern networked environments Parallel Crystal D eveloper s Manual 17 Version 2 4 Revised 5 27 00 import com mobileapps pcre class Simple public static void main String args PCREApplicationClient client null try client new PCREApplicationClient e
72. info strcpy info graphTitle New Title job gt SetGraphText section 0 amp info Parallel Crystal D eveloper s Manual 285 Version 2 4 Revised 5 27 00 Report Generation for C Clients The Report Customization API for C clients is provided through the Parallel Crystal Report Engine Functions accessed through the pcre n header file These functions are identical to the original Print Engine interface provided with Seagate Crystal Reports and are described in the developr h1p file included in the distribution Assuming installation on drive C this is located in the directory c MobileApps pcre docs The Customization API for C is summarized in Table 9 11 on page 286 The Print Window Management and Customization functions are not currently available with Parallel Crystal Category Customization Functions Data Functions PEDiscardSavedData PEHasSavedData Engine Functions PEOpenEngine PECloseEngine PECanCloseEngine PEGetVersion Error Functions PEGetErrorCode PEGetErrorText Formula Functions PEGetFormula PESetFormula PECheckFormula PEGetNFormulas PEGetNthFormula Graph Functions PEGetGraphData PESetGraphData PEGetGraphOptions PESetGraphOptions PEGetGraphText PESetGraphText PEGetGraphType PESetGraphType Group Functions PEGetNGroups PEGetGroupCondition PESetGroupCondition String Functions PEGetHandleString As EGetNthPar
73. job processing phase 2 try Customization method calls catch PCREAPIError e2 y Handle API errors in this phase here job Close catch PCREServiceError e3 Handle server errors here engine Close catch PCREError e Handle all remaining errors here ara Disconnect client client Quit new PCREApplicationClient example host com fife Ale E sales rpt Ef He ff Hs H4 H5 Handler H1 handles all possible connection errors Since the actual errors thrown could be instances of the pcREGatewayError PCREServerError OF PCREClient the handler uses the pcre Error Classes Error base class to trap all three possibilities You might want to evolve the handler so that a limited number of retries is allowed before terminating the application Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Handlers H2 and H3 handle pcreapterrors that occur within separate report customization phases If any other server side errors occur they will be handled by the outer handler at H4 This arrangement allows us to proceed with confidence from phase 1 to phase 2 If an API error occurs in phase 1 then the H2 handler can decide whether to allow a retry or to proceed on some alternative control path The handler at H5 catches
74. last method call on the interface In most cases this string will have been returned from the Report Server BI Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 3 Handling Optional varrant arguments We used a third wrapper class called crnoarg that provides missing argument values for optional method arguments The crnoarg class does this by constructing a special kind of varrant value struct CRNoArg public VARIANT CRNoArg VariantInit this V_VT this VT_ERROR V_ERROR this DISP_E_PARAMNOTFOUND CRNoArg VariantClear this PARAMNOTFOUND Values are generated internally by Visual Basic controllers but must be passed explicitly when you use C The destructor clears the variant tag and de allocates any storage In the example the variants initialized at steps 9 and 12 are not released until the try block is exited at Step 15 The helper classes used in the example are not provided as part of Parallel Crystal largely because Visual C now provides sophisticated CO M support through extensions to the C compiler and through the ATL template library We ll show you how you can use these features in the section entitled G enerating PostScript Reports with VC and COM Generating PDF and HTML Reports with COM Fortunately only trivial modifications are required to the example to generate reports in different output formats such as PD F and HTML To
75. ll assume that errors are reported using the ReportError from the previous section or something similar that uses the LastErrorString from the Automation Server e The call to the Application O bject method connect ToReport Server may fail and report the error No connection to a Server Report Engine has been made There are two possible reasons for this error either the argument string does not specify a valid host name or the Parallel Crystal Report Server was not running on the specified host Check that the string you supplied is either a valid host domain name or IP address and then check that Parallel Crystal is installed and running on that host If the problem persists check Chapter 7 Trouble Shooting ActiveX Clients e The call to the Application O bject method openreport may fail and report the error Invalid file name This error occurs when the report file specified by the argument string does not exist on the Report Server Check the location of the file and then supply its full path name tO OpenReport e The call to the Report Object method export Toutmi may fail and report the error Disk full This highly misleading message is actually returned by the Report Engine and means that it was unable to create the HTML file to hold the generated report It does not mean your disk is full Check the argument string for Export ToHTML specifies a valid drive and path name and that access permissions on th
76. locally thrown exception A Version 2 4 Revised 5 27 00 e The methods of disp interfaces can specify arguments using a Visual Basic type called a VARIANT C automation controllers need classes that manage values of this type and supply default values for optional arguments To alleviate these problems Microsoft have made substantial improvements to their Visual C Development Environment In particular e Versions 4 5 and 6 of Visual C provide a collection COM support classes together with wizards that generate wrapper classes for CO M interface definitions The wrappers use smart pointers to eliminate the need to call the unknown methods e Versions 4 5 and 6 of Visual C provide the Active Template Library ATL that implements a complete framework for programming COM servers and clients e The Microsoft Foundation Classes provide support for programming CO M ActiveX visual controls It is not possible to include information on all of these support facilities in this manual In the examples that follow we will show how the VC compiler extensions and wrapper classes can be used to simplify access to the Automation Server If you are interested in ATL we suggest you consult a good introductory text such as the book by Richard Grimes The book by Mike Blaszczak is one of several that covers MFC COM programming 1 Richard Grimes et al Beginning ATL COM Programming Wrox Press 1998 ISBN 1 861000 11 1 2 Mik
77. method setHost In the example no host has been supplied so the client will attempt to connect to any available Report Server host running a G ateway e If aconnection to the G ateway is established the client issues a request to the Gateway to start a Report Engine Server on the same host The G ateway starts the Server with a command line that includes server arguments packaged in the request together with a server name that is unique for the Report Server If the Server is started within a timeout period usually 30 seconds the G ateway returns the host and server name to the client e The client establishes a connection to the Report Engine Server using the name and host returned by the G ateway Once these connections have been established you can call the client s openEngine method to open the print engine in the Report Engine Server The Report Engine is assigned exclusively to your client and cannot be accessed by other clients connected to the same Report Server These connections last until you call the client s ouit or Disconnect methods If any of the preceding steps fail the connect method will throw an exception whose type and content identify the nature of the error A pcREGatewayError indicates a failure to connect to the G ateway on the specified host or a failure to launch the Report Engine Server correctly a PcREServerError indicates a failure to connect to the Report Engine Server Both exceptions are derived fr
78. name C MobileApps pcre SampleReports Box rpt CRNoArg method hr if FAIL ED hr pDispa if ED FAI throw CRI pDispatch gt pApp gt OpenReport name hr thro method amp pDispatch w CRError pApp tch gt Queryl hr Release Generate report nterface IID_ICRReport void amp pReport Error ICRReport object not found CRNoArg prompt copies collated start stop hr pReport gt PrintOut prompt copies collated start stop file if FAILED hr throw CRError pApp pReport gt Release hr pApp gt DisconnectFromReportServer catch const CRError amp error error Report if pApp NULL pApp gt Release CoUninitialize return 0 Example 5 1 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 file phe Os 10 fife TAs 12 ff U3 14 15 16 17 B Each numbered paragraph below corresponds to the same numbered code statement 1 In order to use the O bject Model interfaces their definitions must be included from a header file called pereauto n This file is normally located in the installation directory C MobileApps pcre AutomationServer include so you must ensure this directory is on your development environment s INCLUDE path 2 All COM API calls return an uresuxt containing a 32 bit resul
79. network you may need to set the osagentaddress property The O SAgent is a Report Server component that services client connection requests O SA gents are normally reached by UD P broadcasts made from the client However when the Report Server is remote the UDP mechanism does not work and you must supply the IP address to enable the connection to be established 1 UDP is the Internet s User D atagram Protocol B Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 The osagentaddress property is declared as follows Visual C HRESULT put_OSAgentAddress BSTR ipAddr Visual Basic Property Let OSAgentAddress ByVal ipAddr As String Visual J void putOSAgentAddress java lang String ipAddr You must set this property before calling connect ToReport Server For example Visual C app gt OSAgentAddress 123 456 654 321 app gt ConnectToReportServer example host com Visual Basic app OSAgentAddress 123 456 654 321 app ConnectToReportServer example host com Visual J app putOSAgentAddress 123 456 654 321 app ConnectToReportServer example host com Note that the arguments to osAgentAddress and connect ToReportServer need not specify the same host address This is because multiple Report Servers can be serviced by a single O SAgent You should check the required addresses with your System Administrator When the call to
80. of load factors is necessarily correct The manual interface to the Load Balancer is intended to allow Report Server selection to be based on application dependent information used in conjunction with or instead of simple load factors Parallel Crystal D eveloper s Manual 219 Version 2 4 Revised 5 27 00 Using Manual Load Balancing with Visual C In this example we show how to use the Load Balancer in manual mode using Visual C with COM support Client connection is performed by the method connect of some application class cmyApp For simplicity we assume that the A pplication O bject reference is held in amember variable m_papp void CMyApp Connect ICRReportServers pSvrList static_cast lt ICReportServers gt m_pApp gt ReportServers 1 int nServers pSvrList gt Count 2 ICRReportServer pSelected NULL 3 double minLoad 1000 Tterate through the list of servers for int i 1 i lt nServers i ee ICRReportServer svr static_cast lt ICRReportServer gt pSvrList gt Item i 5 double svrLoad svr gt Loadfactor if svrLoad lt minLoad 6 minLoad svrLoad if pSelected NULL pSelected gt Release pSelected svr else svr gt Release If server selected connect to it if pSelected NULL FE Tx m_pApp gt ConnectToSelectedReportServer pSelected MsgBox Connected to Report Server on host pSelected gt ReportServerAd
81. output Toppr method first If problems arise try the Export To method that generates PDF using Acrobat Distiller If problems persist and you have access to Crystal Reports D esigner load your report into the D esigner and check for errors in the report itself When the Report Engine Server receives a call to Export To it saves the name of the PD F output file Once the report has been generated in PostScript the Report Engine starts the conversion to PDF by running a Parallel Crystal command line utility called pdfdistiller This program performs the following functions e It checks the input PostScript file exists e It checks that the output PD F file can be created e Itruns Adobe Acrobat Distiller e It prevents multiple instances of Acrobat Distiller from running concurrently e It deletes the PostScript input file after conversion If you experience problems in generating PD F using export To check with your System Administrator that A crobat Distiller has been installed correctly on your Report Server The pdfdistiller utility searches the registry for the Acrobat D istiller s executable and expects to find an entry in HKLM Software Microsoft Windows CurrentVersion AppPaths AcroDist exe If the entry no longer points to a valid file pafdistilier will not be able to execute the AcroDist program If there is no registry entry then pdfdistiller will attempt to run a program called acropist and will rely on the System PA
82. package by importing com mobileapps pcre Create an instance of the pcREApplicationClient Class using the host name or IP address of the machine hosting the Report Server Call the connect method to connect your client to a Report Engine running in the Server Open a print engine by calling the openEngine method of your client Use the PCREEngine instance returned by openEngine to open one or more print jobs Each job is specified by supplying the full path name of the report file on the Report Server Perform customization and report generation calls for each print job using the methods of the pcrEJob Class Close all your print jobs when they have completed using the close method for each job Close your print engine Call the ouit method to terminate your Report Engine and disconnect from the Report Server LI Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Trouble Shooting the Simple Client This section details some of the most common problems in programming a simple client Refer to the sample code from Example 2 1 on page 32 Incorrect Host Name Declaration Suppose you supplied an incorrect host name in the declaration of the pcrrapplication client variable For example suppose you typed client new PCREApplicationClient bad host name This statement will be executed correctly but the subsequent call to connect on line 3 will throw an except
83. separate report customization phases If any other server side errors occur they will be handled by the outer handler at H4 This arrangement allows us to proceed with confidence from phase 1 to phase 2 If an API error occurs in phase 1 then the H2 handler can decide whether to allow a retry or to proceed on some alternative control path The handler at H5 catches all errors ignored by the inner handlers In addition if we fail to open a print job we transfer to this point and subsequently call the client s destructor to disconnect from the Report Server Parallel Crystal D eveloper s Manual 291 Version 2 4 Revised 5 27 00 Table 9 12 shows how each error class s Report method calls a corresponding method of the pcrEconsole interface Error Class Console interface reporting method PCREClientError Cals PCREClientErrorMessage PCREGatewayError Cals PCREGatewayErrorMsg PCREServerError Calls PCREServerErrorMsg PCREAPIError Cals PCREAPIErrorMsg PCREFatalError Cals PCREFatalErrorMsg PCREInternalError Cals PCREInternalErrorMsg Table 9 12 This association means that whenever you call the Report method on an error class be it a base class like pcrEError or a derived class like pcrEapterror the correct PCREConsole interface method for the actual error is always called Of course you don t need to call the Rep
84. server architecture While there are many advantages in the two tier arrangement each client must have its own copy of the original report file and must run its own copy of the customizing application When an application such as this is deployed on a largescale the cost of duplicating the reporting capability in each client becomes significant Within a corporate environment it may also be difficult or even impossible to deploy multiple copies of report files to each client PC or to schedule regular report runs Parallel Crystal solves many of the problems associated with two tier systems by moving the report files and the Print Engine DLL to a Report Server machine This arrangement is shown in Figure 1 4 on page 20 Sl Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Parallel Crystal Report Server IGP IGP IOF Parallel Crystal Client Parallel Crystal Client Parallel Crystal Client Figure 1 4 In this three tier architecture each client is connected to a Parallel Crystal Report Engine running in the Report Server The report engine performs the customization commands for that client but necessarily shares available processors and memory with other report engines running in the same server The report files are also located within the report server but the data records are retrieved from the database server The three tier Parallel Crystal architecture provides may advantages including e The duplication
85. the required information in the helper classes pPcREGraphOpt ions PCREGraphDataInfo and PCREGraphText Info GetGraphType retums an integer valued type code identifying the type of the graph The corresponding set methods use the same helper classes when resetting a property of the graph Parallel Crystal D eveloper s Manual 79 Version 2 4 Revised 5 27 00 The following fragment shows how the formatting options and title string for a graph in the n th section are retrieved and reset int section job GetSectionCode n PCREGraphOptions options job GetGraphOptions section 0 options verticalBars true job SetGraphOptions section 0 options PCREGraphTextiInfo info job GetGraphText section 0 info graphTitle New Title job SetGraphText section 0 info Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 S Data Object Reporting Overview Data O bject Reporting allows users of Parallel Crystal to have more control over the data used in their reports Until now users could only report on data that was in files or databases Web Application Server users had to allow Parallel Crystal to bypass some of the access control and database connection pooling features of their Application Server With D ata O bject Reporting Parallel Crystal users can push data from data objects into Parallel Crystal servers and generate reports From simple data objects which perform
86. the Report Engine Server and the most likely cause is that your C C Client version is inconsistent with the Server version You should check the installation of Parallel Crystal components on the client and Report Server machines with your System Administrator 6 A method may fail an report the error PCRE API error Logon failure This is a standard Crystal Reports failure message It occurs if the password and or username requested by the data source are not supplied correctly They are normally incorporated into the report file at design time but you can override the entries when you call the PELogOnServer function or the LogOnServer method of pcreE ngine You should check that the details of the OD BC or other data source administrator on the Report Server match the settings on the machine where the report was designed To help prevent this problem we recommend that whenever possible you design your reports in the same environment in which you expect to run them 7 A call to the printout method may report a pcREAPIError with the message PCRE API error Cancelled by user This is a standard Crystal Reports failure message that can occur if the report cannot be sent to the nominated printer You should check the availability of the printer or the print settings established by any calls to the selectPrinter method of PCREJob Parallel Crystal D eveloper s Manual 230 Version 2 4 Revised 5 2
87. the Report Server then open a print engine on the Report Server 5 The Parallel Crystal Report Engine allows reports to be customized and started by running print jobs Each job is opened initially by specifying the name of the report file that is to be used to generate the report document In the example we specify the file using a full path name for a typical Parallel Crystal installation 6 Once a print job is opened it may be customized with calls to the methods of the PCREJob Class This statement calls the output ToPrinter method to send the output to a printer The argument value specifies the number of copies to be printed 7 The call to the start method generates the report document When the call returns the report document will be complete but printing will not necessarily have finished 8 When you are finished with a print job you should call the ciose method to release resources held in the Report Server 9 If an error occurs in an API call the corresponding method of the pcreEngine or PCREJob Class will throw an exception and control will transfer to the exception handler at statement 11 If we reach this print statement we know the report has been generated Parallel Crystal D eveloper s Manual 235 Version 2 4 Revised 5 27 00 10 11 12 13 When we are done with all print jobs the print engine is closed with a call to its close method The exception handler is executed if
88. the full path name of the HTML file to the constructor Then call the ExportTo method and pass the export info object as an argument Report output files are not generated until the start method is called You must enclose most PCRE method calls within try catch blocks in order to catch and handle exceptions raised by the PCRE Java package and the Print Engine DLL l Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Using Parallel Crystal in a Java Applet In this section we describe how to write Java applets that connect to a Parallel Crystal Report Server and how to retrieve the generated report back to your browser You are probably familiar with the applet concept but we will clarify the rules for applet programming and then show how they are extended to Parallel Crystal clients In programming terms a Java applet is a class that extends a user interface Panel called java applet Applet This class has four methods called init start stop and destroy that are called as you navigate from page to page When an HTML page containing an lt applet gt tag is loaded into your browser the class file for the applet is loaded into the browser s Java virtual machine and the init method is called If you subsequently browse to another document using the left or right arrow keys or by entering anew URL then the browser calls the stop method before leaving the page containing your applet Conversely if y
89. the single reference to the Application Object and causes it to be deleted 1 Setting a VB object reference variable to Nothing is equivalent to calling Release on the associated interface S Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 6 The procedure cmdconnect_Click is executed when the Connect button is pressed Private Sub cmdConnect_Click On Error GoTo fail If Len txtHost Text 0 Then sgBox Enter Report Server host name Exit Sub End If app ConnectToReportServer txtHost Text setButtons False True True bConnected True Exit Sub fail sgBox app LastErrorString End Sub The procedure checks that a host name has been specified and then calls the Application O bject s connect ToReport Server method If the connection is established the Run and Disconnect buttons are enabled and the bconnected variable is set to True If the client cannot connect to the Report Server the LastErrorString method is called to return the error message 7 The procedure cmadRun_click is executed when the Run button is pressed Private Sub cmdRun_Click On Error GoTo fail Dim report As ICRReport Check report file path name If Len txtReport Text 0 Then sgBox Enter report file path name Exit Sub End If Generate report Set report app OpenReport txtReport Text report PrintOut sgBox Report generated Exit Sub fail
90. to the server and perform report customization and generation tasks using the standard Crystal Report APIs and a variety of client environments Parallel Crystal may be used in a variety of client environments including e Microsoft ActiveX products such as Active Server Pages and Visual Basic e Pure Java applications and applets e Conventional C or C applications e Parallel Crystal may also be accessed from a number of Java based Web A pplication Servers In the sections that follow we ll describe some basic concepts about report creation and customization We ll also explain why it is productive to migrate the process from a desktop computer to a more powerful networked Report Server Report Basics A report that is designed with Crystal Report Designer is created as a template that is stored in a report file The template holds all the information necessary to integrate selected data records perform appropriate calculations and integrate the results into a formatted document Report files are usually identified with an rpt suffix Normally data is first added to a report as part of a print preview process that allows a mock up of the final report to be viewed within an inspection window If the results are satisfactory then either the template or the template and data may be re saved in the report file If the first option is chosen the report is said to possess saved data Report pre viewing is illustrated in Fig
91. to the exception handler at statement 11 We ll discuss connection failures in greater detail in the next chapter but the most common reasons are that the Parallel Crystal Report Server is not running on the machine identified by the host name or you specified an incorrect host name 4 This statement declares a variable that represents a PCRE print engine The variable is initialized with the value returned by the call to the openEngine method of the client In statements 2 through 4 you can see a progression get a client connect the client to the Report Server then open a print engine on the Report Server 5 The Parallel Crystal Report Engine allows reports to be customized and started by running print jobs Each job is opened initially by specifying the name of the report file that is to be used to generate the report document In the example we specify the file using a full path name for a typical Parallel Crystal installation 6 Once a print job is opened it may be customized with calls to the methods of the PCREJob Class This statement calls the output ToPrinter method to send the output to a PostScript printer The argument value specifies the number of copies to be printed 7 The call to the start method generates the report document When the call returns the report document will be complete but printing will not necessarily have finished 8 When you are finished with a print job you should call the close method to re
92. use from VB dialects almost as easy from Visual J and surprisingly hard from Visual C We ll examine each language interface in the following sections Parallel Crystal D eveloper s Manual 126 Version 2 4 Revised 5 27 00 Using Parallel Crystal with Visual C This section describes how to write Visual C clients that use the PCRE Automation Server to generate simple reports in PostScript PD F and HTML In Generating PostScript Reports with CO M we show you how to use the low level COM API to access the Automation Server In the next section entitled G enerating PostScript Reports with VC and COM we show how Visual C COM support classes make it easier to develop automation clients in C In order to understand the material in this section you must be familiar with the COM function CoCreatelInstance and the addr f Releas and QueryInterfac methods of tunknown If you don t know COM at this level of detail we suggest that you consider a simpler language such as Visual J or Visual Basic where much of this complexity is hidden If you really want to learn COM using C we recommend first that you read a good introductory text such as E ssential COM by Don Box Generating PostScript Reports with COM When you use the PCRE Object Model you must first connect your client to the Automation Server then use the rcrapplication interface on the root Application Object to connect to the Report Server O nce you
93. we failed to open the print job in Step 5 10 The call to Peuninitialize terminates the client s Report Engine Server and disconnects the client from the Report Server machine 11 The function ReportError Calls pEGetErrorText to get a handle to an error message string and then calls pzeGetHandlestring to retrieve the message string into a buffer In practice these calls access a message cache in the Client Library that stores the error message and code returned by the Report Engine server Example 8 4 on page 241 indicates that only two extra statements at steps 2 and 10 are necessary when using the C API to the Parallel Crystal Report Server The remaining code conforms to the original Seagate Print Engine API Trouble Shooting the Simple C Client Let s examine what happens when things go wrong in the simple C client First suppose you supplied an incorrect host name in the call to pztnitialize and that instead of line 2 you typed PEInitialize NULL bad host name argc argv PE_DO_CONNECT This statement will initialize the Client Library but will fail to connect to the nominated host and will return the value ranse The call to ReportError will then print the following line PCRE Gateway error Connect cannot connect client to Gateway Service on host bad host name Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 5 The error message i
94. 2 4 Revised 5 27 00 This message means the method you are trying to call cannot be found in the Report Engine Server and the most likely cause is that your C C Client version is inconsistent with the Server version You should check the installation of Parallel Crystal components on the your client and Report Server machines with your System Administrator Your client may report a pcREAPIError with the message PCRE API error Logon failure This is a standard Crystal Reports failure message It occurs if the password and or username requested by the data source are not supplied correctly They are normally incorporated into the report file at design time but you can override the entries when you call the PELogOnServer function or the LogOnServer method of pcre ngine You should check that the details of the O D BC or other data source administrator on the Report Server match the settings on the machine where the report was designed To help prevent this problem we recommend that whenever possible you design your reports in the same environment in which you expect to run them A call to the start method of pcresob may report a pcREAPIError with the message PCRE API error Cancelled by user This is a standard Crystal Reports failure message that can occur if the report cannot be sent to the nominated printer You should check the availability of the printer or the print settings e
95. 7 00 lt Applet gt Tag Details In order to use the PCRE package from an applet your HTML lt applet gt tag must specify certain mandatory attributes For example the applet in Example 2 4 on page 42 should be accessed with the following sequence of HTML tags lt applet name PCREApplet code PCREApplet id PCREApplet width 600 height 400 gt lt param name title value PCRE Applet Example gt lt param name org omg CORBA ORBClass value com visigenic vbroker orb ORB gt lt param name ORBalwaysProxy value true gt lt applet gt The initial lt applet gt tag must include the code attribute that identifies the applet s class file relative to the web server s root directory For example if the web server root is C InetPub wwwroot then the applet code will be retrieved from the file C InetPub wwwroot PCREApplet class The remaining attributes of the lt applet gt tag are optional The width and height define the size of the bounding rectangle in which to display the applet s user interface display panel The name and ia attributes identify the applet to the browser In addition to the lt applet gt tag you must supply at least two lt param gt tags that are necessary to enable the browser with the CORBA IIOP protocol The first lt param gt tag has the form lt param name org omg CORBA ORBClass value com visigenic vbroker orb ORB gt and identifies a specific O bject Request Broker to implement the II
96. 7 00 Chapter 8 Getting Started with C C Clients In this chapter we describe how to customize and generate reports using C or C On Windows 95 and Windows NT systems you may use any C C development environment capable of loading 32 bit Windows DLLs You should refer to Chapter 5 for information on how to program a Parallel Crystal ActiveX automation client using Microsoft Visual C ActiveX COM extensions This chapter is divided into two major sections e In the first section entitled Using Parallel Crystal in a C Application we describe how to build a Parallel Crystal client that runs as aC application program The section contains example code fragments that show you how to use C classes to connect to the Parallel Crystal Report Server and how to generate reports formatted as PostScript PD F and HTML documents e Inthe second section entitled Using Parallel Crystal in a C Application we describe how to build a Parallel Crystal client that runs as a C application program The section contains code fragments that show you how to use equivalent C API function calls to connect to the Parallel Crystal Report Server and how to generate reports formatted as PostScript PD F and HTML documents Both C and C applications are constructed using the Parallel Crystal C C Client Distribution Library and its accompanying header files In C environments the headers provide a class based interface to this library In C environm
97. ADS handles TRUE INFINITE cout lt lt All workers terminated lt lt endl It is possible to adapt this example so that all client threads are connected to Report Servers via the Load Balancer Y ou simply omit the nost parameter in the constructor call and call connect with the argument value rrue It is also possible to have the multiple client threads connect to the same host possibly to produce different reports In each case bear in mind that the actual performance of your client depends upon the number of processors you have available on your client s host If there is only one then your threads will execute concurrently but with interleaving in time In this case performance would not be improved it might even be decreased A multi threaded C client can be constructed on very similar lines by adapting the ClientWorker function as follows DWORD WINAPI ClientWorker LPVOID l1pArg LPTSTR host LPTSTR 1lpArg PEInitialize NULL host 0 NULL PE _DO CONNECT PEOpenEngine BPI calls PECloseEngine PEUninitialize return PCRE_OK Notice that it is very important to ensure that pzuninitialize is called before the ClientW orker function exits If this is not done the connection to the Report Server will persist until the application terminates Parallel Crystal D eveloper s Manual 306 Version 2 4 Revised 5 27 00 A Par
98. API PCREAPI ReportError goto close Other API calls close PEUninitialize Parallel Crystal D eveloper s Manual 264 Version 2 4 Revised 5 27 00 Connecting C Clients When you construct a Parallel Crystal C application you must first create a PCREAppClient Class then connect it to the Report Server and then access the client s Report Engine Typically this requires a code sequence such as PCREAppClient client try client Connect PCREEngine engine client OpenEngine engine gt Close catch PCREError amp e e Report When the connect method is called the following events occur in sequence e The client tries to establish a connection to a G ateway running on the Report Server The Report Server is identified by the host name or host address supplied in the PCREAppClient constructor call or in a call to the pcreGateway method setHost In the example no host has been supplied so the client will attempt to connect to any available Report Server running a G ateway e If aconnection to the G ateway is established the client issues a request to the Gateway to start a Report Engine Server on the same host The G ateway starts the Server with a command line that includes server arguments packaged in the request together with a server name that is unique for the Report Server If the Server is started within
99. Box Connectd to Report Server at host amp _ ae oe selected ReportServerAddress Else MsgBox No Report Servers available End If End Sub Each numbered paragraph below corresponds to the same numbered code statement 1 6 Selected holds a reference to an 1cRReport Server interface and identifies the most lightly loaded Report Server mintoad holds the load factor for the currently selected server The variables are initialized to represent a state in which no server has been selected The loop iterates through the collection returned by the report servers property of the Application O bject The load factor for the current server in the collection is compared with mintoad and if it is smaller mintoad and selected are updated If selected references an object in the server s collection it is passed as an argument to the connect ToSelectedReportServer method that then makes the client connection If the client is connected to the selected Report Server a message box is displayed identifying the server s host address The above example can easily be adapted for VBScript by deleting the As clauses from the Dim statements Parallel Crystal D eveloper s Manual 222 Version 2 4 Revised 5 27 00 Using Manual Load Balancing with Visual J In this example we show how to use the Load Balancer in manual mode using Visual J For simplicity we assume that the class member app holds a referenc
100. C Automation client connection and disconnection is essentially a four step process 1 The client connects to the Automation Server In practice connects means that the Automation Server D LL is loaded into the client s process an instance of the Application O bject is created and a reference to the object s rcrapplication interface is returned to the client No network activity is involved at this stage The client calls the connect ToR portServer method of the ICRApplication interface to connect to the Parallel Crystal Report Server If the Report Server runs on the same machine as the client the connection will cross a process boundary However if the Report Server runs on a different machine the connection will cross whatever networks are involved When the connection is established the client is connected to a Report Engine Server that does report customization and generation The client calls the Disconnect FromReport Server method to disconnect from the Report Server When the connection is severed the client s Report Engine Server is terminated and memory resources in the client are freed The client disconnects from the Automation Server by calling the release method of the rcrRapplication interface This causes residual memory to be recovered by the Automation Server and may cause the DLL to be unloaded from the client process In practice only C clients using the bare COM API need to make an explicit call t
101. CRReportServers ICRServer ICRReport ICRArea s ICRAreaOptions ICRGroupAreaOptions ICRSection s ICRSectionOptions ICRReportObject s ICRSubReportObject ICRGraphObject ICRTextObject ICRSection s ICRSectionOptions ICRReportObject s ICRSubReportObject ICRSortField s ICRDataBase ICRDataBaseTable s ICRDataBaseFieldDefinition s ICRDataBaseParameter s ICRPrintingStatus ICRPrinterInfo ICRReportSummaryInfo ICRExportOptions ICRReportOptions ICRFormulaFieldDefinition s ICRSummaryFieldDefinition s ICRParameterFieldDefinition s ICRPDFOutputOptions ICRPDF Image ICRReportSaver s The nature of the hierarchy and its properties and methods conform to Microsoft s guidelines for automating document oriented applications S Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 These guidelines apply to the PCRE Object Model ICRApplication is the interface on the root Application O bject created when your client first connects to the Automation Server The openReport ServerSettings and options methods properties on this interface allow you to create Report Server and G lobal O ptions O bjects and to acquire their respective interfaces IcRReport ICRServer and ICRGlobalOptions Each object is a parent of the objects created by its methods or properties For example the Application O bject is a parent of the Report Server and G lobal O ptions Objects Every interface has two properties pa
102. CType UXF_ODBCOptions u2fhtml dlil UXFHIML3Type UXF_HTML30ptions u2fmaspdf dll UXFPDFDistillerType UXF_PDFOptions Table 3 6 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 In the following example we use the Export To method to generate a file in Excel format and save it to disk PCREJob job engine OpenJob C MobileApps pcre SampleReports Box rpt PCREJobExportiInfo info new PCREJobExportiInfo info info info info info info job formatDLLName u2fxls dll formatType PCREJob UXFX1s4Type formatOptions new UXF_XlsOptions false destinationDLLName u2ddisk dll1 destinationType PCREJob UXDDiskType destinationOptions new UXD_DiskOptions C MobileApps pcre SampleOutput Box xls ExportTo info job Start Notice that you must call start after ExportTo to actually generate the report Table 3 7 below enumerates the possible settings for the dest inat ionDLLName and the corresponding values for the dest inationType and destinationOptions DLL Name Destination Sub type Destination Options u2ddisk dll UXDDiskType UXD_DiskOptions u2dmapi dlil UXDMAPIType UXD_MAPIOptions u2dpost dll UXDExchFolderType UXD_PostFolderOptions Table 3 7 Parallel Crystal D eveloper s Manual 73 Version 2 4 Revised 5 27 00 The following example shows how to mail a report using the MAPI mailer server interface
103. ClientThread NTHREADS Create and start the client threads for int i 0 i lt NTHREADS i clients i new ClientThread hosts i clients i start Wait for workers to terminate for int i 0 i lt NTHREADS i try clients i join catch Exceptione System out printin Client i e System out printin All clients completed It is especially important that each client thread calls the ouit method to disconnect from the Report Server If you omit the call and let the thread die then the connection to the Report Server will persist until the application as a whole terminates and the server process will remain on the server Parallel Crystal D eveloper s Manual 107 Version 2 4 Revised 5 27 00 It is possible to adapt this example so that all client threads are connected to Report Servers via the Load Balancer Y ou simply omit the nost parameter in the constructor call and call connect with the argument value t rue It is also possible to have the multiple client threads connect to the same host possibly to produce different reports In each case bear in mind that the actual performance of your client depends upon the number of processors you have available on your client s host If there is only one then your threads will execute concurrently but with interleaving in time so there will be no performance gain Parallel Crystal D e
104. D eveloper s Manual PCREAppClient client try client Connect char samples client getConfigServer gt getSampleReportDir client getServer gt SetFolder samples PCREConfigServer StrFree samples PCREEngine engine client OpenEngine PCREJob job engine gt OpenJob Box rpt job gt Close engine gt Close catch PCREError amp e e Report The sample report file Box rpt is part of the standard Parallel Crystal installation However its full path name is likely to be installation dependent We therefore use the get SampleReportDir to return the path name of the sample reports directory and then call the setFolder method of the pcreserver Class to change the working folder of the Report Engine Server accordingly Thereafter we can refer to all report files by their names relative to the sample directory Configuration Server for C Clients C clients are automatically connected to the Configuration Server when you call PEConnect directly or indirectly through PEInitialize Thereafter you must call PEGet ConfigServer to get a handle to the pcreconfigServer Class and then call one of the functions listed in Table 9 14 Each function retrieves the configuration string copies it into a buffer and returns a value true If the string could not be obtained the function returns FALSE and you must call pecetErrortext to determine the reason for fa
105. DF Repott 238 Generating a Simple HTML Report iicssssesscsvssssasscsscasssssasescssaevanesavacevisssdancsvessaascescsanesnasnsavessacoscnasedecesasavavsesabanssuenessesraaseeseaeaz es 239 SUMMATIVE NEEN EEE O EDON NEEE EEIE EEE NEEE EA EE EEEa 240 Usinge Parallel Crystal in aC Application uieii E A A a a 241 Generating a Simple PostScript Report issii EE REEDE TAES SIEEN EAEE EIIN ESES 241 Trouble Shooting the Simple C CHEN e seseseisaii ie ii ni Ei E a A EEEE EN ERRER E 243 Generating a Simple PDF Report k Generating a Simple HTML Report i ccccevcasccesvveccncovcascevsesnuseovvesstevsvuevseossagassseveevesseaarsceveasevevcnacscbnedhacecontesdeasvenccadeveasevervencsueeveusete 246 Chapter 9 Using the C C Client Library scscssccssssssssssscssscsssssssscssscsssscssssesenssesessssssscssssessssessesessessssesscssssassesessssessessseeseeses 249 Parallel Crystal GU enn sexsiscaifccaccsceasescaicsssdediee sit casissevasdaeectiasaeseva S OE Vua bE send ssnavcsies asina RERE u soa ciei sdaavceaisastucaahaveseaicisoeaaakasendieietoseass 251 Services for Clients ees i C Application Client Instantiation vivccssccscssssssccscsatascuvseeascssssdaccsecsszcsnasncasavansiaeanseieistessvacevs avetsotssusaansevedasesavadecnaveaznevansadecsoenstts 252 ANSI C Application Client Initialization isceesecsccessecscceesecareusasecencuecsccessyeascecuvacesevesgestevee EERE E S EOR REEE EA ae 253 C Client Configuration 0 ee 255 Accessin
106. Disconnection The connections established between a Java application or applet client and the Report Server are severed when you call the client s quit method e The client s connection to its Report Engine Server is severed and the server is terminated e Outstanding connections from the client to the G ateway are severed It is illegal to make a call to any of the pcreEngine OF PCREJob methods after you have disconnected from the Report Server Once you have called ouit you must re call Connect and acquire a reference to the new Report Engine Server Parallel Crystal D eveloper s Manual 66 Version 2 4 Revised 5 27 00 Report Generation In Parallel Crystal the Report Customization API is exposed through the methods of the PCREEngine and PCREJob Classes These classes partition the API into two parts methods that are report engine related and methods that are print job related In this section we ll give a general overview of each class and provide some additional information on how to generate reports in particular formats To understand the class interfaces in depth you should consult the documentation supplied online with Parallel Crystal Assuming installation on drive C this is located in the directory c MobileApps pcre docs The following files should be present e JavaAPIDocumentation index html is the root index to the PCRE package documentation The documentation is formatted and cr
107. DiskFile supplied to the constructor allow PEExportOptions Struct to be initialized with the correct format and destination values for Excel format and disk storage Y ou only have to call the setbiskFileName property to specify the name of the output file Parallel Crystal D eveloper s Manual 279 Version 2 4 Revised 5 27 00 The example of emailing a report can also be re written with similar ease PCREJob job engine gt OpenJob C SampleReports Box rpt PCREExportOptions options PCREExportOptions crEFTText PCREExportOptions crEDTMailMAPTI options setMailToList director reporthost com options setMailCCList options setMailSubject Box Office Report options setMailMessage Here is your Box Office Report r n n job gt ExportTo amp o0ptions job gt Start The property methods of the pcrEExportOptions apply consistency checks to ensure internal consistency of the underlying pEExportoOptions struct that is built If these calls generate conflicting values then the method will throw a pcreclientError exception U It is also possible to use the pcrEExportOptions helper to generate reports in PDF When the resulting pzExport Options struct is passed to the Report Engine Server the export format is noted and then changed internally to PostScript When the print job is started wi
108. EServer PCREInternalError PCREGateway PCREClientError PCREConfigServer PCREGatewayError PCREServerError PCREAPIError Client Management PCRE API Helpers PCRE API PCREClient PCREGroupCondition PCREEngine PCREApplicationClient PCREJobExportiInfo PCREJob PCREAppletClient PCREHTMLJobExportiInfo PCREPDFJobExportiInfo PCREPDFOutputOptions PCREMargins Figure 3 1 Parallel Crystal D eveloper s Manual 51 Version 2 4 Revised 5 27 00 This chapter describes the facilities provided by the Java Client Package including The section entitled Parallel Crystal Clients describes how to use the PCREApplicationClient and PCREAppletClient Classes and particularly how to specify the connection to your Report Server Having established a connection to a Report Server the section entitled Report Generation describes how to use the pcrEEngine and PCREJob Classes to perform report customization and generation The methods of the PCREJob class are arranged in groups and illustrated with sample code fragments When a report is stored in a file it may be necessary to retrieve the file from the Report Server back to the machine hosting the client The section entitled Report Retrieval describes facilities for automatic return of reports to the client The section entitled Error Recovery describes how to use the error handling classes to detect and hand
109. I programming error you should go straight to the Reference Documentation to get help The Parallel Crystal A PI Reference D ocumentation is automatically installed with Parallel Crystal and is available from the Start Programs Parallel Crystal D ocumentation option on the Windows Start Menu Parallel Crystal D eveloper s Manual 11 Version 2 4 Revised 5 27 00 Getting Help Dynalivery Corp provides a variety of sources of information for problem solving We would invite you to visit our website or email us with questions comments suggestions and problems Using our Web Site Our web site contains links to the latest online versions of this documentation and many other helpful resources http www dynalivery com Email Tech Support Technical Support for products of Dynalivery Corp starts with an email to TechSupport dynalivery com In your email to Tech Support please include e A copy of the Report File filmameRPT e A copy of the Server Log file server log is usually found in the MobileA pps Pcre logs folder e A small sample of the code being used to call the execution of the report file e A detailed description of the problem e A detailed description of the configuration environment being used including e The Parallel Crystal version number e Operating System e Web Application Server if applicable e The client development package ASP Visual Basic Visual J Visual C
110. If Next ICRParameterFieldDefinition s ICRParameterFieldDefinitions is the collection interface exposed by the ParameterFieldD efinitions Collection O bject The methods and properties are listed in Table 6 30 A ParameterFieldD efinitions Collection O bject is obtained from the ParameterFields property of the Report Object Each item in the collection is a ParameterField D efinition O bject representing information stored in a parameter field in the report and the number of ParameterField D efinition Objects is returned by the count property Individual ParameterField D efinition O bjects are obtained by the rt em method that takes an index or argument identifying the parameter required Visual Basic clients may iterate through all items with the ror Each statement that calls the Newznum property to create an enumeration of D atabase Parameter O bjects Methods Custom Properties Navigation Properties Item Count Parent _NewEnum Report Application Table 6 30 ICRParameterFieldDefinition s the custom interface exposed by each ParameterField Definition O bject in the collection The methods and properties are listed in Table 6 31 They provide access to the name kind and content attributes of the field Parallel Crystal D eveloper s Manual 209 Version 2 4 Revised 5 27 00 Methods Custom Properties Navigation Properties SetCurrentValu CurrentValue Parent SetDefaultValue Cu
111. If you supply the optional commana argument then error messages will be written to the standard output stream as well Parallel Crystal D eveloper s Manual 15 Version 2 4 Revised 5 27 00 Since Acrobat Distiller relies on the existence of the PostScript file you should take care to ensure that the file does indeed exist before calling padfdistiller When you generate PDF via the export To method the Report Engine Server applies checks to ensure that the PostScript file has been completely generated before returning control to the server This is because the PostScript file is not generated directly by the Server but by the Windows Print SubSystem This process can take several seconds on a busy machine processing large files Problems with the Report Server The following problems can arise with the Report Server e The Load Balancer and Report Retrieval Service can be turned on and off in the Report Server If you get connection errors when trying to use either of these services check with the System Administrator that the Report Server is configured to run them e If your client appears to block indefinitely inside a method of the pcreEngine or PCREJob Class then a third party component used by the Crystal Print Engine D LL may have created an error dialog that you are unable to see To diagnose this problem you need to get the System Administrator to run Parallel Crystal from the desktop so that all components are visibl
112. In turn this allows you to connect your controller to a Report Server on the same machine or to a different possibly remote machine A remote connection allows you to off load the report processing load but necessarily introduces a small overhead in making customization A PI calls across a network If your controller is VBScript running inside the IIS Web Server this may be an acceptable price to pay to preserve the web server s performance The interfaces provided by the PCRE Automation Server are described in the online documentation that is normally located in the directory C MobileApps pcre docs AutomationServer HTMLReference If you inspect the Automation Server s type library with the O LE COM Object Viewer that is available with Visual C then you may notice that the interfaces are described with ID L declarations such as the following odl uuid AC73A0C1 BCDD 11D1 8C6B 000000000000 helpstring ICRApplication Interface dual oleautomation interface ICRApplication IDispatch method declarations The attribute dual is important since it allows an interface to be accessed either as a disp interface or as a custom interface This means that the PCRE Automation Server can support automation controllers that can use efficient v tables such as VC and later versions of VB as well as controllers such as VBScript that must use the slower disp interface In general the Automation Server is easiest to
113. LastErrorString End Sub The procedure disconnects the client from the Report Server and re sets the command buttons If the Connect button is pressed again the client will be re connected to the Report Server on the host currently entered in the Host text box Generating PDF and HTML Reports with Visual Basic The rcrReport interface provides several methods that make it easy for you to generate reports in other formats In each case the call to printout in procedure cmdRun_Click is replaced with one that generates the report in the appropriate format In particular e To generate a report in PDF and save the results replace the call to Printout with the following call to output ToPDF report OutputToPDF C SampleOutputs Box pdf When the method returns the PDF report will be stored in the file Box pdf in the SampleOutputs directory e To generate a report in HTML and save the results replace the call to printout with the following call to Export ToHTML report ExportToHTML C SampleOutputs Box html When the method returns the HTML report will be stored in the file Box htmi in the SampleOutputs directory If the report has embedded images the corresponding JPEG files will be stored in the same directory B Version 2 4 Revised 5 27 00 e To generate a report in PostScript and save it in a file replace the call to printout with the following call to output Tors report OutputToPS C S
114. NT 4 0 O ptions Pack Microsoft Internet Information Server Internet Service manager e Select the directory e Right click and select Properties e Fill in the form see the example below Select the Isolate Process check box and click OK Note of Explanation If you do not tick the Isolate Process box then the MA S dient is run in the main IIS process Y ou can see this process in the Task M anager It is called InetInfo xe Should there be any kind of program error in this process then the whole W eb Server is brought down T here is no need to take this risk Select Isolate Process and your application will be run in a separate proxy process called MT S exe This is designed that should the application crash then the next user to connec simply gets a new copy of the application Parallel Crystal D eveloper s Manual 322 Version 2 4 Revised 5 27 00 In the Event of a Failure In the event of a failure you are going to see some large numbers coming back from the Automation Server as error numbers These are standard COM error codes Failure codes in COM lead off with the top bit set so they appear as very large negative numbers Always print them in hexadecimal form and then you can look them up in lt winerror h gt in extremis Normally these are one of two generic COM errors to let you know something is wrong and then we provide a means to obtain further information on the problem The two COM codes that you
115. OP protocol The second lt param gt tag has the form lt param name ORBalwaysProxy value true gt and ensures that all IIO P exchanges can be routed through firewalls A full technical description of these terms is too lengthy to include here Y ou ll find additional information in the section entitled Applet Client Connection in Chapter 3 If you have difficulty in getting your applets to load check with your System Administrator that your Parallel Crystal installation has been configured to run a component called the IIO P GateK eeper amp Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Remarks on Applet Programming In the previous section we outlined a framework for constructing Parallel Crystal applet clients that uses the init start stop and destroy methods to manage the connection to the Report Server The connection is maintained while the browser is displaying the HTML page containing the applet s tag and is broken on navigating to a different page If the browser returns to the applet s page the connection is re established but the client is connected to a new instance of the Report Engine It is possible to create an applet with different Report Server connection lifetimes by using the init start stop and destroy methods in different Ways For example the following version of init creates a connection that only lasts until the end of the method public void init PCREAppletClient cl
116. PCREJob job engine OpendJob C MobileApps PCRE SampleReports Box rpt PCREHTMLJobExportiInfo info new PCREHTMLJobExportInfo C MobileApps PCRE SampleOutputs Box html job ExportTo info job Start job Close System out println Report generated engine Close catch PCREError ex System out printin Exception ex finally if client null client Quit Example 2 3 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Ts 10 pls T24 13 39 Summary The preceding four sections have described how to construct simple Java clients that connect to a Parallel Crystal Report Server running on a named host An exception will be generated if you give an incorrect host name or Parallel Crystal is not in fact running on that machine Reports are generated by getting access to a print engine and then opening a print job When the print job is opened you supply the full path name of the report file on the Report Server You must tell the Print Engine what to do with the report once it is generated If you want to print a PostScript report call the output Toprinter method of the PCREJob Class If you want to generate a PD F report call the output Toppr method and specify the full path name of the PDF file If you want to generate an HTML report create an instance of a PCREHTMLJobExportInfo Class and supply
117. PEExportOptions char formatDLLName PE_DLL_NAME_LEN WORD formatType oid FAR formatOptions har destinationDLLName PE_DLL_NAME_LEN WORD destinationType oid FAR destinationOptions PEExportOptions lt G0Q lt v8U The report format is defined by the formatDLLName and format Type members The DLL name specifies a D LL which must be supplied with the Parallel Crystal Installation and which generates the report in the appropriate format Some formats have minor variations and so the format Type name is used to hold a numeric value specifying sub typing information For example there are five variants of Excel format available represented by constants called uxrxis2Type UXFX1s3Type etc Some output formats take additional format dependent data and these are supplied through a variety of helper structs called uxFxxxOptions When a helper struct is supplied it is referenced through an opaque pointer held in the formatopt ions field The report destination is supplied in a similar way through the dest inat ionDLLName destinationType and dest inationOptions members The dest inat ionDLLName specifies a DLL that is responsible for dispatching the report The dest inationOptions member supplies additional destination dependent data provided through pointers to helper structs called uxpxxxOptions For example if you specify the dest inat ionDLLName u2ddisk which saves a repor
118. Parallel Crystal Version 2 4 Developer s Manual ee ae eloper s Manual 2 4 Revi AS 27 00 The information given in this manual refers to Version 2 4 of Parallel Crystal by Dynalivery Corp Dynalivery Corp endeavors to ensure that the information in this manual is correct but does not accept liability for any error or omission The development of D ynalivery Corp products and services is continuous and published information may not be up to date Any particular issue of a product may contain part only of the facilities described in this manual or may contain facilities not described here Specifications and statements relating to performance in this manual are D ynalivery Corp estimates intended for general guidance They may require adjustment in particular circumstances and are therefore not formal offers or undertakings Statements in this manual are not part of a contract or program product license save insofar as they are incorporated into a contract or license by express reference Issue of this manual does not entitle the recipient access to or use of the products described and such access or use may be subject to separate contracts or licenses Copyright This manual is copyrighted with all rights reserved Under copyright laws this manual may not be copied in whole or in part without the written permission of D ynalivery Corp Copyright 2000 D ynalivery Corp Trademarks Parallel Crystal is a trademark of D ynalive
119. Parallel Crystal D eveloper s Manual 290 Version 2 4 Revised 5 27 00 PCREAppClient client example2 host com try Add client customization code here client Connect catch PCREError amp e AI HL Handle all connection errors here try PCREEngine engine client OpenEngine try PCREJob job engine gt Open C ACME sales rpt job processing phase 1 try Customization method calls catch PCREAPIError el fd H Za Handle API errors in this phase here job processing phase 2 try Customization method calls catch PCREAPIError e2 H3 Handle API errors in this phase here job gt Close catch PCREServiceError amp e3 H4 Handle server errors here engine gt Close catch PCREError amp e i H5 Handle all remaining errors here Handler H1 handles all possible connection errors Since the actual errors thrown could be instances of the pcrEGatewayError PCREServerError OF PCREClientError Classes the handler uses the pcrEError base class to trap all three possibilities You might want to evolve the handler so that a limited number of retries is allowed before terminating the application Handlers H2 and H3 handle pcreapterrors that occur within
120. Release when they acquire and release interfaces and use QueryInterface to make runtime queries for other interface pointers For example if a client has a reference to ICat that is provided by a co class that also implements tpog and 1Fish the client can call QueryInterface through Icat to get a reference to either 1Dog OF IFish This allows clients to discover new interfaces as they are added to existing objects e Every COM interface and co class is identified by a universally unique identifier that is designed to prevent name clashes However each UUID has a symbolic representation in much the same way as an internet IP address has an a user friendly domain name When clients request an interface using QueryInterface they use the symbolic form of the interface UUID For example the interface 1Dog is denoted by IID_IDog e Although COM interfaces are expressed in Microsoft COM IDL the COM Specification is designed to allow COM classes and their clients to be programmed in a variety of conventional programming languages However COM specifies that clients must be able to call the methods of an interface through a runtime structure called a vtable which is designed to eliminate language and linker implementation dependencies that impede binary re usability in traditional programming environments e Software modules that implement CO M classes are called servers Servers are generally referred to as in process local or remote d
121. Server These properties are summarized in Table 9 2 Property N ame Purpose setHost Set the Report Server host for the G ateway Server getHost Return the Report Server host running the G ateway Server setName Set the name of the G ateway Server getName Return the name of the G ateway Server setWait Set G ateway Server timeout when starting a PCRE Server getWait Return the G ateway Server timeout Table 9 2 Here is a simple example in which the setHost property is used to specify the Report Server machine running the G ateway Server PCREAppClient client try char hostName HostNameDialog client getGateway gt setHost hostName client Connect catch PCREError amp error error Report It only makes sense to use a set property before you call the client s connect method If you call a set property after connecting the client the method will throw a PCREClientError exception For example Parallel Crystal D eveloper s Manual 257 Version 2 4 Revised 5 27 00 PCREAppClient client example3 host com try client Connect Connect to grub char hostName HostNameDialog client getGateway gt setHost hostName Exception thrown catch PCREError amp error error Report Accessing PCREServer Properties from C The pcreserver Class provides client access to t
122. SetWait gwHandle dwWa ReportError goto close host LE Connect to Report Server on PEConnect ReportError goto close Lt te initialization FAPI to close Comple PEInitAPI PCR ReportError go Other API calls y close PEUninitialize E_NO_CONNI ECT ECT CONN wait properties t it bed The set functions set properties that affect the client connection to the Report Server Therefore it makes no sense to call them after a call to p will generate an error message PEHANDLE BOOL bO gwHandle K butterfly host EInitRemote butterfly acme com Connect to P EGetGateway Get Gateway handle gwHandle P Following call generates an error if PEGatewaySetWait gwHandle 120 ReportError goto close Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 EConnect S0 the following code 262 Accessing PCREServer Properties from C You can access the Report Server properties through the API functions listed in Table 9 7 Each function takes the handle returned by a previous call to r parameter and gets or sets a command line argument that is to be supplied by the Gateway when its starts the Report Engine Server for the client The command line argument strings are shown in Table 9 4 on page 258 The functi
123. TH environment variable to locate this program You can run pdfdistiller manually on the Report Server to check its operation The command line is pdfdistiller command input psfile output pdffile Parallel Crystal D eveloper s Manual 32 Version 2 4 Revised 5 27 00 By default the program runs silently and writes its error messages to the Windows NT Event Log Check this log file before you do anything else If you supply the optional command argument then error messages will be written to the standard output stream as well Since Acrobat Distiller relies on the existence of the PostScript file you should take care to ensure that the file does indeed exist before calling pafdistiller When you generate PDF via the export To method the Report Engine Server applies internal checks to ensure that the PostScript file has been completely generated before returning control to the client This is because the PostScript file is not generated directly by the Server but by the Windows Print SubSystem This process can take several seconds on a busy machine processing large files Problems with the Report Server The following problems can arise with the Report Server 1 The Load Balancer and Report Retrieval Service can be turned on and off in the Report Server If you get connection errors when trying to use either of these services check with the System Administrator that the Report Server is configured to run them
124. ToSelectedReportServ r to make the connection The list of Report Servers is accessed through a ReportServers Collection O bject whose interface is called tcRReport Servers The methods and properties of this interface are shown in Table 6 33 You obtain a ReportServers Collection O bject from the Report Servers property of the Application O bject Each item in the collection contains information about a particular Report Server and the number of available Report Servers is returned by the count property Individual Report Servers are obtained by the rtem method that takes an index or argument identifying the parameter required Visual Basic clients may iterate through all items with the For Bach statement that calls the Newznum property to create an enumeration of ReportServer O bjects Methods Custom Properties Navigation Properties Item Count Parent _NewEnum Report Application Table 6 33 Parallel Crystal D eveloper s Manual 218 Version 2 4 Revised 5 27 00 The details of each Report Server O bject are available through the rcrreportServer interface whose methods and properties are listed in Table 6 34 Methods Custom Properties Navigation Properties Loadfactor NumberOfReportServerProcessors NumberOfReportEngines ReportServerAddress Table 6 34 ReportServerAddress Is the IP address for the Report Server host If you select this Report Server your client will
125. Trouble Shooting ActiveX Clients to learn how to solve the problems that occur most often with ActiveX clients Are you using aC or C client development environment Or are you using Visual C but without the ActiveX COM extensions If so Go to Chapter 8 entitled G etting Started with C C Clients to get started Go to Chapter 9 entitled Using the C C Client Library to learn how to use the Parallel Crystal C C Client Library Go to Chapter 10 entitled Trouble Shooting C C Clients to learn how to solve the problems that occur most often with C C clients Parallel Crystal D eveloper s Manual 10 Version 2 4 Revised 5 27 00 Things Not Included in this Manual If the Roadmap did not help you locate an appropriate chapter maybe the facilities you require are not currently available in this volume Information this manual does not contain e Installation instructions e System Administration information and trouble shooting e Networking information and trouble shooting Note The Parallel Crystal System Administrator s Manual is bang designed and developed to describe these items PRCE Customization APIs If you re looking for detailed descriptions of the PCRE Customization APIs you should consult the online Paralld Crystal A PI Reference D ocumantation The API Reference contains detailed descriptions of all the API classes and methods that comprise the various PCRE client packages Whenever you get an AP
126. UBLE java sql Types DECIMAL java sgql Types NUMERIC Number INTEGER java sql Types INTEGER java sql Types BIGINT w truncation Blob BLOB java sql Types BINARY java sql Types VARBINARY java sql Types LONGVARBINARY short SHORT java sql Types SMALLINT Byte BYTE java sql Types TINYINT Memo MEMO java sql Types LONGVARCHAR string STRING java sql Types CHAR java sql Types VARCHAR java sgql Types NUMERIC java sql Types DECIMAL The behavior for types NUMERIC and DECIMAL depend on the settings by setN umeric andD oubleConversionType Use the constants REPRESENT AS DOUBLE OR CURRENCY or REPRESENT AS STRING See the PCRE Java Quick Reference for additional details Types not listed which includes types introduced in Java 2 will cause an exception to be thrown by the adapter However we have done testing with Access SQL Server and Oracle and DOR handles all the data types returned by their drivers Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 8 Method Mapping Reference DORDataSet ResultSet types listed are java sql Types close close getBlob getBinaryStream for LONGVARBINARY get Bytes for BINARY VARBINARY getBoolen getBoolean getByte getByte getColumnCount getMetaData getColumnCount getColumnDisplaySize getMetaData getColumnDisplaySize getColumnLabel getMetaData getColumnLabel
127. _MSG e getText void PCREFatalErrorMsg const PCREError e essageBox FATAL_MSG e getText void PCREInternalErrorMsg const PCREError e essageBox INTERNAL_MSG e getText private Implementation void LogMsg const char msg void MessageBox int kind char msg The console is installed in the client in the constructor call The code fragment above then takes the following form GUIConsole myConsole PCREAppClient client amp myConsole example3 host com try client Connect API method calls catch PCREError amp e e Report Errors caught by the handler will be reported with the correct cutconsole method since e is actually a reference to a derived error class whose Report method overrides the base class method So if e happens to be a pcreclientError it will be reported with the PCREClientErrorMsg method of the cutconsole Parallel Crystal D eveloper s Manual 294 Version 2 4 Revised 5 27 00 Report Retrieval When a report is stored in a disk file the file is generated on the Report Server machine using the path name you supplied in an ExportTo OF Output To API call If you wish to display the report you will have to retrieve the file back to the client machine before invoking an appropriate viewer The easiest way to do this is to use th
128. a reference to the pcrECconfigServer Class by calling the client s getconfigServer method Method Purpose GetPCREVersion Returns the Parallel Crystal version string getPCREHostName Returns the Parallel Crystal Report Server host name getPCREHostAddress Returns the Parallel Crystal Report Server host address getPCREInstallDir Returns the Parallel Crystal installation root directory getSampleReportDir Returns the Parallel Crystal sample reports directory getSampleOutputDir Returns the Parallel Crystal sample output directory getPCREWebServerDir Returns the Web Server s root directory getPCREGatewayName Returns the name of Parallel Crystal G ateway Server Table 3 9 Here is a simple example that shows how to retrieve the host name of your Report Server and the version of Parallel Crystal that it is running client Connect PCREConfigServer config client getConfigServer System out printin Connected to PCRE version config getPCREVersion on config getPCREHostName Parallel Crystal D eveloper s Manual 101 Version 2 4 Revised 5 27 00 The Configuration Server returns information that you can use with other service providers The next example shows you how to connect to a Report Server and then set the Report Engine Server s working folder to the sample reports directory client Connect String samples
129. a timeout period usually 30 seconds the G ateway returns the host and server name to the client e The client establishes a connection to the Report Engine Server using the name and host returned by the G ateway Once these connections have been established you can call the client s openEngine method to open the print engine in the Report Engine Server The Report Engine is assigned exclusively to your client and cannot be accessed by other clients connected to the same Report Server These connections last until you call the client s Disconnect method or execute its destructor If any of the preceding steps fail the connect method will throw an exception whose type and content identify the nature of the error A pcREGatewayError indicates a failure to connect to the G ateway on the specified host or a failure to launch the Report Engine Server correctly apcREServerError indicates a failure to connect to the Report Engine Server Both exceptions are derived from the pcreError Class so the easiest way to catch both is to specify pcrEError in the catch clause Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 265 Connections to both the G ateway and Report Engine Servers are established using the host and name strings that are supplied through the service provider property methods The host specifies a particular Report Server on your network and the name identifies
130. ad If the Automation Server D LL has not been installed on the client machine or the registry entries have been corrupted or accidentally destroyed or you have changed the file store location of the DLL then each of the calls to create the Application O bject will fail with a COM error whose RESULT code is 0x80040154 If you use one of the COM error reporting mechanisms to print the error description you will get the message Class not registered which indicates that the CO M runtime layer was unable to locate the crapplication s in process server DLL The Visual J runtime will also provide its own error message Java lang UnsatisfiedLinkError Failed creation of cpemas1 CRApplication because CLSID is not properly registered To rectify this error you should first unregister the Automation Server D LL with the command regsvr32 u cpemasl dll and then re register it with the command regsvr32 cpemasl dll Note that the DLL must also be on your PATH for these commands to work BI Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Connecting to the Report Server Once you have a reference to the Application O bject s tcrapp1 ication interface you can connect to a Report Server by calling the method connect ToReport Server This method is declared as follows Visual C HRESULT ConnectToReportServer BSTR host Visual Basic Sub ConnectToReportServer ByVal host As S
131. all errors ignored by the inner handlers In addition if we fail to open a print job we transfer to this point and subsequently call the client s ouit method to disconnect from the Report Server Table 3 8 shows how each error class s Report method calls a corresponding method of the pcrEConsole interface Error Class Console interface reporting method PCREClientError Cals PCREClientErrorMessage PCREGatewayError Cals PCREGatewayErrorMsg PCREServerError Calls PCREServerErrorMsg PCREAPIError Cals PCREAPIErrorMsg PCREFatalError Cals PCREFatalErrorMsg PCREInternalError Cals PCREInternalErrorMsg Table 3 8 This association means that whenever you call the Report method on an error class be it a base class like pcrEError or a derived class like PcREAP tError the correct PCREConsole interface method for the actual error is always called Of course you don t need to call the Report method at all If you have trapped the error with an appropriate try catch block then how you handle it thereafter is entirely within your control In Java it is not possible to omit a try catch block when calling a PCRE package method that throws an exception If you forget the Java compiler will report the inconsistency in your program Parallel Crystal D eveloper s Manual 95 Version 2 4 Revised 5 27 00 Console I
132. allel Crystal C or C client is owned by the thread which creates the PCREAppClient instance or which calls pzetnitialize Thereafter API calls for this client can be made only on the owner thread For example the following will fail DWORD WINAPI ClientWorker LPVOID lpArg PCREAppClient client reinterpret_cast lt PCREAppClient gt l1pArg try client gt Connect Error her worker thread did not create client PCREEngine engine client gt OpenEngine j catch PCREError amp e e Report return PCRE_FAIL return PCRE_OK void main int argc char argv PCREAppClient client argv 0 DWORD dwThreadId HANDLE handle CreateProcess NULL 0 ClientWorker PCREAppClient amp client 0 amp dwThreadId WaitForSingleObject handle INFINITE cout lt lt worker finished Here the pcrEAppClient instance is owned by the thread executing the constructor The worker thread created by the call to createProcess Cannot access this client because it does not own the client You should always structure multi threaded client applications to ensure that pcrEAppCclient instances are created and accessed within the same thread Moreover a single thread can only own one client at a time Parallel Crystal D eveloper s Manual 307 Version 2 4 Revised 5 27 00 Chapter 10 Trouble Shooting C C Clie
133. allel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 S The following code fragment shows some typical calls to the pcrEEngine methods client Connect PCREEngin ngine client OpenEngine j Generate the Box Office report engine PrintReport Box rpt Customize Box Office report PCREJob job engine OpenJob Box rpt job OutputToPDF C MobileApps pcre SampleOutput Box pdf null job Start job Close Customizing Print Jobs The pcreJob Class provides methods to perform a wide range of report customization tasks Each time you call the pcreEngine S OpenJob method you create a PCREJob instance representing a print job opened on the nominated report file You can have multiple print jobs opened simultaneously and you may customize and run each job independently of the others Each call to the pcregob s start method will run the job and generate a copy of the report When you are finished with the print job you should call the pcrEJob S Close method to release resources in the Report Engine Server In the following sections we present groups of related pcregob methods together with sample code fragments illustrating typical calls For brevity we omit the surrounding try catch block but you must include it in real applications For more realistic examples you should consult the sample code distributed with Parallel Crystal
134. allel Crystal and Web Application Servers Parallel Crystal Client and Server Components Parall l Crystal PDE Labtary wicsciccciedeseshs catsscces rei censssiaicvea eaves saviatabaaavaaes visa cess naaessiseiseviaanaansseuatevisiaaasssistaieaviad nis easbaneversinecaelaneens 27 Chapter 2 Getting Started with Java Clients ssscssssssscssssssssssssssssessesssssssssssesssssssssessesssssssssesessessesscssssessessscssseassssessassssessees 29 Using Parallel Crystal in a Java Application sccccceccsceeseeseeseceseeseeseeseesecsceeseeseeseeseesececeeseesecaecseceesaeseseeeaeeseesesseceeeseseeaeeaecneseeeeaeenees 30 Generating a Simple PostScript Report Trouble Shooting the Simple Client 35 Generating a Simple PDF Report is csciscsscascscdescenssasesscnesascsssavassncoasanes cases scscsavansstavcascevsavevevadvsavdevasandsdeaaezanesavassvessaazanenapaaseossecadasye 37 G ner ting a Simple HTML Report iiccsaiceccccgssencesgssvececaasunciasbucous oasenecasavevscgeseenccnhovacecdoveancsuay inde soaseundesausdensessvevescteaseec cgbevevectuseecaaye 38 SUMMAT casa EEE es sven E E OIEI ER NTa ETSE anaes EEEE EITE R ETTEI EERE SEEE EENE EEEIEI SEEE TIETEET TENETE aS 40 Using Parallel Crystal in G Java Applet ch c cvisccssscocsscuseuseek s n aOR RERUN E ENE EAER EENE EE EE 41 lt Applet gt Tas Details sne EEEE AEEA ESEE eat SEAE EETA Av taeda eta wh cate aoe ese 48 Remarks on Applet Programming 5 s scscssves sesies sevasncesesszavs seve s
135. allelPrintReport Start a parallel report run The PCREEngine Class allows you to produce your report in one of three ways e You can generate the report directly using the printReport method The single argument to the method specifies the name of the report file on the Report Server No report customization is possible with this method e You can open a print job with the opengob method The method takes a single argument specifying the name of the report file on the Report Server and returns a reference to an instance of the pcrEJob Class representing the print job Y ou can call LogOnServer Log on to database server LogOffServer Log off database server Open Open a print engine Close Close print engine Table 3 5 methods of pcrEJob to customize the report and then generate it by calling the start method If your report requires access to a database server then you must call the Logonserver method before calling any of the methods opengob PrintReport OF ParallelPrintReport Since you only have access to a single report engine it is only possible to open a single database connection at a time You should call the corresponding LogOf Server method when your report has been generated The ciose method closes the engine and releases resources within your Report Engine Server You cannot subsequently call any of the report management methods unless you re open the engine with another call to open Par
136. ame which is installation dependent they should be the same as those given in the section Connecting to the Automation Server e Use the Visual Basic O bject references dialog to locate an entry for the cpemasl dll e Use the Visual J Type Library Wizard to locate an entry for cpemas1 a11 e Use the Visual C OLE COM Object Viewer and use the Type Library folder to locate an entry for cpemas1 a11 2 The registry entries under xxEY_cLassEs_Root have become corrupted 3 You have moved the cpemasi di1 DLL so that the path name is no longer valid To fix these problems you should uninstall the Automation Server with the command regsvr32 exe u cpemasl dll and then re check the registry to ensure the entries have been completely purged Then re install the Automation Server with the command regsvr32 exe cpemasl dll and check the registry entries again Parallel Crystal D eveloper s Manual 225 Version 2 4 Revised 5 27 00 When the Automation Server is correctly installed and you can get a reference to the root application interface 1cRApplication Calls to connect ToReport Server can fail for the following reasons 4 5 The argument string does not specify a valid host IP address or domain name The argument string is valid but Parallel Crystal is either not installed or not running on the host you specified If the LastErrorstring property returns the message PCRE Gateway error
137. ameterField ESetNthParameterField Parameter Functions PEGetNParameterFields PEGetNthParamInfo ue PEConvertPFInfoToVInfo PEConvertVInfoToPFInfo Destination Functions PESelectPrinter PEGetSelectedPrinter PEOutputToPrinter PEOutputToPDF PEGetExportOptions PEExportTo Parallel Crystal D eveloper s Manual 286 Version 2 4 Revised 5 27 00 Formatting Functions PEGetReportTitle PESetReportTitle PEGetPrintOptions PESetPrintOptions PEGetSectionFormat PESetSectionFormat PEGetMargins PESetMargins PESetFont PEGetNDetailCopies PESetNDetailCopies PEGetPrintDate PESetPrintDate PEGetMinimumSectionHeight PESetMinimumSectionHeight Print Job Functions PEPrintReport PEGetNPages PEOpenPrintJob PEClosePrintJob PEStartPrintJob PESetJobStatus PECancelPrintJob PEIsPrintJobFinished PEParallelPrintReport PEStartParallelPrintJob Selection Functions PEGet SelectionFormula PESetSelectionFormula PECheckSelectionFormula PEGetGroupSelectionFormula PESetGroupSelectionFormula PECheckGroupSelectionFormula Server Functions PELogOnServer PELogOffServer PEGetSOQLQuery PESetSQLQuery Sorting Functions PEGetNSortFields PEGetNthSortField PESetNthSortField PEDeleteNthSortField PEGetNGroupSortFields PEGetNthGroupSortField PESetNthGroupSortField PEDeleteNthGroupSortField Subreport Functions PECloseSubreport PEGetNSubreportsInSelecti
138. amp succeeded lt BR gt Else Response write lt B gt amp comment amp failed lt BR gt lt B gt End IE end sub On Error Resume Next response write lt H3 gt Tutorial One Application started lt H3 gt Set App Server CreateObject MAS CRApplication 1 App ConnectToReportServer Tampa CheckResponse Connection set Report App OpenReport c mobileapps pcre sampleReports box rpt CheckResponse OpenReport Report ExportToHTML c temp out html CheckResponse ExportToHtml App DisconnectFromReportServer response write Finished lt BR gt lt SCRIPT gt lt HEAD gt lt BODY gt lt BODY gt lt HTML gt Now all we have to do is place these scripts in a Web Server directory register them with ITS as an application and hit the tutorialO ne asp URL with a browser to test it Parallel Crystal D eveloper s Manual 321 Version 2 4 Revised 5 27 00 Setting Up Your First ASP Application An ASP Web Application is a collection of scripts and possibly HTML files and Activex components which live in a directory on the Web Server This directory must be identified to the Web Server in order to create the application Go to your Web Server root usually something like c inetpub wwwroot and create a tutorialO ne folder Place in it the global asa and the tutorialO ne asp files supplied e Start the MMC Microsoft Management Console Program Windows
139. ample host com 3 A print job is opened for c MobileApps pcre SampleReports Box rpt 4 The report format is set to PD F and the path name c MyReports Box pdf specifies the output file on the client machine 5 The print job is run The report is generated on the Report Server machine and is retrieved to the file c MyReports Box paf on the client machine Parallel Crystal D eveloper s Manual 99 Version 2 4 Revised 5 27 00 If the report is generated correctly then the file c MyReports Box paf Will be available on the client machine on return from the Start method at Step 6 The Report Retrieval feature requires your Parallel Crystal to be installed with a file transfer service If this service is not running then Step 5 above will throw a PCREServerError with the message PCRE ServerError Connect cannot connect to PCRE File Transfer Service The Report Retrieval feature can be dynamically switched on or off for a client by calling setRetrieveMode with the argument value true OF false Retrieval to Applet Clients If you have an applet client then the easiest way to retrieve the file is to use the browser itself However this restricts the output format of the report to HTML or PDF In Chapter 2 in the section entitled Using Parallel Crystal from a Java Applet we described a ShowReport method that retrieves a report using a URL composed from the report file name and the Web Server host address Nat
140. ampleOutputs Box ps The report will be generated in the file Box ps in the sampleoutputs directory Note that you cannot depend upon the file being completely generated when you return from the method call This is because the file must be generated by the Windows Printer Spooler that does not run synchronously with the Report Engine Server Remember that all these methods cause the print job to be started Therefore you must complete all necessary customization in previous method calls Handling Errors from Visual Basic When an error occurs in the Automation Server it stores an error message internally and returns a generic COM error called _rari When Visual Basic detects a CO M error it posts a message box containing the error code and the name of the Automation Server method that raised the error For example if the connect ToReport Server method fails Visual Basic will produce the message shown in Figure 5 5 The run time error code is the value amp _Faru that is returned by connect ToReport Server when it is unable to connect to the Report Server specified by the argument string In order to display error messages generated by the Automation Server you must access the LastErrorString property of the rcrapplication and IcRReport methods In the example the on Error Goto Statement transfers control to the labeled error handler whenever the Automation Server returns an error You can choose at that point whether to re
141. ampleoutputs directory Note that you cannot depend upon the file being completely generated when you return from the method call This is because the file must be generated by the Windows Printer Spooler that does not run synchronously with the Report Engine Server Remember that all these methods cause the print job to be started Therefore you must complete all necessary customization in previous method calls Parallel Crystal D eveloper s Manual w9 Version 2 4 Revised 5 27 00 Handling Errors from Visual J Although the generated wrapper classes allow you to use Java s exception handling idiom to trap errors the messages returned by the comrailexception getMessage method describe generic CO M failures For example if a method in the Automation Server fails it stores a failure message internally and returns a COM result called z_rar When you print the message corresponding to this error you get the rather terse and uninformative string Unspecified error In order to recover the message stored in the Automation Server you must call the getLastErrorString method of either the tcrapplication OF IcRReport interfaces The following static method shows how a general error reporter can be written to take a reference to either interface and recover the error message appropriately public static void ReportError Object iref ComFailException e String msg e getMessage if iref null if ire
142. anager that imposes constraints on the external interfaces offered by the applet In particular your applet is only permitted remote communications with the network host running the web server and this in turn means that your Web Server and Report Server must be running on the same machine This restriction applies to all Parallel Crystal thin clients that are implemented using Java applets In practice it is possible to build browser based Parallel Crystal thin clients that are not subject to this restriction by integrating with other technologies For example Microsoft s Active Server Pages technology described in Chapter 6 Using PCREAutomationServer allows HTML pages to be dynamically composed by a Web Server using information retrieved from a Report Server running on a different network host S Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Chapter 3 Using the Java Client Package The Parallel Crystal Java Client Package is a collection of classes providing a range of report management functions that you can access from Java applications or applets The classes are arranged in functional groups shown in Figure 3 1 but are normally imported collectively into your program Within each group base classes are marked with an asterisk Enor Handling Console Management Service Providers PCREError PCREConsole PCREService PCREFatalError PCREApplicationConsole PCR
143. anual 317 Version 2 4 Revised 5 27 00 An IP address can be used instead of a machine name If the report server is not on the local network it could be half way across the world then you need to make an additional call to App OSAgentAddress Some reasons the connect call could fail include e Giving an illegal name e The machine might be down e There might not be a MAS PCRE product running on that machine For more information see the section below entitled Diagnosing Server Side Problems You can check for the success of this and other commands like this If Err Number 0 then Response write Connected to server lt b gt amp lt b gt lt BR gt Else Response write lt B gt Connection to report server error lt B gt End If For more information about the response code and how to elicit further diagnostics see the section below entitled Handling Error information The act of connecting to the Report Server has e Established a set of CORBA objects on client and server ready to handle any supported API call e Gotten the server side PCREG ateway to create a personal PCRE Server Process e Opened a Report Engine in the PCREServer Process The next thing to do is to open a report file which loads that report into the server side report engine The report file has to be accessible to the server side machine set Report App OpenReport c sampleReport box rpt lt Check for Errors
144. apper classes are saved in files called cpemas1 tih and cpemas1 tli that are created in your project s Debug OF Release directories The cpemasi tih file contains the class definitions for the wrappers and the cpemas1 t1i contains the inline wrapper methods In a stable environment these files will normally be created once when you import cpemas1 t1b for the first time The wrapper classes perform four main functions e They declare smart pointer types for every CO M interface These pointers automatically manage object lifetimes by making calls to addref and Release from overloaded assignment operators The constructors also handle calls to CoCreateInstance to bind a pointer to the implementation provided by its co class e They allow properties to be treated as variable accesses If the property identifier occurs as an I value the put property is called with the value expression as argument If the property identifier occurs as r value the get property is called e They allow method calls to omit optional arguments and internally supply the correct default values e They retrieve COM error information and incorporate it into a locally thrown exception 2 The Application O bject is created and destroyed from the constructor and destructor of a smart pointer type called tcrapplicationptr The example is restructured to provide a function RunReport that creates the smart pointer on entry and destroys it on return 3 The declara
145. application client and connect to a PCRE Report Server on the specified host The client will use the default character based PCREAppConsole to report errors The call will return FALSE if Parallel Crystal is not running on the specified host BOOL bOK PEInitRemote butterfly acme com F F e i 7 Initialize an application client with a user specified console and connect to a Parallel Crystal Report Server running on an unspecified host The call will return FALSE if there are no Parallel Crystal Report Servers running on your network BOOL bOK PEInitialize amp myConsole NULL 0 NULL PE_DO_CONNECT F F F me BOOL bOK PEInitialize amp myConsole Combine examples 2 and 3 above The client is initialized with a user defined console and connected to a Parallel Crystal Report Server on the specified host The call will return FALSE if Parallel Crystal is not running on the host ant acme com 0 NULL PE_DO_CONNECT C Client Configuration Each pcrEAppClient instance acts as a container for a number of service provider classes that grant clients access to the various Parallel Crystal servers running on the Report Server machine The service providers are created when you call the client s constructor and are available through get property methods in the client When the client calls the connect method connections are established between each serv
146. ataSet interface is closely modeled after the java sql ResultSet interface Parallel Crystal has its own interface which is simpler than using the java interface The ResultSet interface provides additional capabilities which were unnecessary for DOR and make implementing the interface more difficult For those users who either prefer to code to the ResultSet interface or who use JD BC to retrieive data we have provided an adaptor class so that the ResultSet interface can be used with DOR Using the ResultSet Adapter If your data source is aJD BC database then the result of your query will be returned as an object that implements the java sql ResultSet interface Since DOR expects its input to be of the form of the DO RDataSet interface the adaptor DO RSQ LResultSetA dapter was created This class implements the D ORD ataSet interface and takes a java sql ResultSet object in its constructor The datatype and method mapping of the adapter are listed in the appendix Below is an example of use See the javadoc comments in the Java API Quick Reference for additional details on the adapter get ResultSet from jdbc connection vesSet is the ResultSet Instantiate the adapter and pass it the ResultSet DORSQLResultSetAdapter adapt new DORSOLResultSetAdapter resSet do other PCRE calls make call specifying adapted ResultSet as data source for report aJob SetPrivateData DORDataSet adapt continue with PCRE ca
147. ates Report Engines to clients and can balance the requests from multiple clients across multiple Report Servers The PCRE Gateway also has an interface that is expressed in CORBA IDL and is implemented as a CORBA server e The PCRE Service Control Manager The Service Control Manager SCM allows Parallel Crystal to be run on the desktop or as an NT Service The SCM also provides a number of intrinsic services to Parallel Crystal clients Normally a Parallel Crystal installation will include a PCRE Service Manager a G ateway an O SAgent and an ITO P GateK eeper In addition there will be a PCRE Report Engine Server for each connected client Parallel Crystal has distinct client packages for use with Java Microsoft ActiveX and C development environments The choice of which package to use depends upon your preferences for development languages and technologies The principal features of each Parallel Crystal client include e The Parallel Crystal Java Client is provided as a single Java package called com mobileapps pcre It contains an object oriented interface to the customization API and acollection of supporting classes that provide server location and connection management and error reporting and recovery The package may be used within Java applications or applets Parallel Crystal D eveloper s Manual 24 Version 2 4 Revised 5 27 00 e The Parallel Crystal C C Client is a simple class library that offers dual interfaces
148. ation of the call and freeze your G UI You can make your GUI more responsive by making the Report Engine call on a background thread This frees up the AWT callback thread allowing it to process other G UI events Parallel Crystal D eveloper s Manual 113 Version 2 4 Revised 5 27 00 Problems with Export Formats In Chapter 2 in the section entitled Print Job Outputs we described how to control the output format of the report with a variety of export formats A problem that can arise with report formats e Not all of the formatting D LLs may be available on your Report Server If you experience problems with formats other than HTML or PDF then check with your System Administrator that the corresponding D LL is on your system and accessible to the Report Engine Server through the PATH environment variable Problems with PDF This section describes the problems with PD F production using the D ynalivery library and Acrobat Distiller In Chapter 2 we described how to generate PD F reports using the output ToPDF ExportTo and startParallelPrintJob methods of the pcruob class and the ParallelPrintReport method of the ecrez ngine class The Output ToPDF method generates PDF using the Dynalivery PD F Library which is loaded directly into the Report Engine Server and which renders the report directly in PDF in a single step The remaining methods produce PD F indirectly by generating a PostScript version of the report first of all an
149. ava lang java lang java lang java lang java lang Where Version HostName HostAddress InstallDir SampleReportDir SampleOutputDir WebServerDir EP SOP GP A chy Cr ict tring getVersion NNNNNWNNG WebServerDir As String tring getHostName tring getHostAddress tring getInstallDir tring getSampleReportDir tring getSampleOutputDir tring getWebServerDir Returns the Parallel Crystal version string Returns the Parallel Crystal Report Server host name Returns the Parallel Crystal Report Server host address Returns the Parallel Crystal installation root directory Returns the Parallel Crystal sample reports directory Returns the Parallel Crystal sample outputs directory Returns the Web Server s root directory In the following example the procedure Runsamp1e takes the name of a Report Server host and a report file in samp1eReportDir and retrieves the generated HT ML report to the webServerDir For example if we call RunSample with RunSample flea acme com FTE it will connect to the ReportServer on flea acme com run the report FTE rpt export the result to FTE htmi and retrieve the HTML file back to Web Server s root directory Runsample is shown below using Visual C Visual Basic and Visual J 1 Well discuss report retrieval in more detail in the next section Parallel Crystal D eveloper s Manual 213 Version 2 4 Revised 5 27 00 interfaces to t
150. ay returned by RequestReportServerList describes a Report Server The pcrEReport Serverinfo structure is defined as follows typedef struct PCREReportServerlInfo double LoadFactor int NumberOfReportEngineServers int NumberOfReportServerProcessors char GatewayName PE_REPORT_SERVER_INFO_LEN char ReportServerAddress PE_REPORT_SERVER_INFO_LEN The Report Server s load factor is given by the value of the toadFactor member and is currently equal to NumberOfReportEngineServers NumberOfReportServerProcessors The information in the pcreReport Serverinfo is correct when the call to RequestReportServerList returns However if you delay making your choice other clients could connect and render the information obsolete If you supply a host in the pcreappclient constructor call then your client will use the Load Balancer service running on that host However the host settings for the G ateway and Configuration Servers are revised automatically whenever the client completes the connection to the selected Report Server In order to use the Load Balancer your Parallel Crystal installation has to be configured to run this service If the Load Balancer is not running then calls to RequestReportServerList and connect will throw a pcreserverError exception with the message Server error cannot connect client to Load Balancer service Parall
151. bals asa For simple projects the globals asa file should just contain the following empty procedures lt SCRIPT LANGUAGE VBScript RUNAT Server gt Sub Session_OnStart End Sub Sub Session_OnEnd End Sub Sub Application_OnStart End Sub Sub Application_OnEnd End Sub lt SCRIPT gt When the Web Server loads a page from an ASP project for the first time it creates an Application Context to represent the project application and a Session Context to represent the client Thereafter each new client that joins the Application gets its own Session Context Application and Session Contexts maintain global and local state information that can be accessed by all the pages in a project The information in an Application Context is accessible to all the clients whereas the information in the Session Context is only accessible to the client that owns the Session A Session Context is maintained until it is explicitly destroyed by the client or until it times out The Application Context is maintained until the Web Server is terminated When the ASP files have been created we recommend that you use the Microsoft Management Console to isolate the execution of the embedded VBScript from the Web Server Y ou do this as follows 1 From the Program Manager select Windows NT Server 4 0 O ption Pack and then select Microsoft Internet Information Server Internet Service Manager 2 Use the left hand scope pane to navigat
152. be generated in the file identified by the outputpath Note that you cannot depend upon the file being completely generated when you return from the method call This is because the file must be generated by the Windows Printer Spooler that does not run synchronously with the Report Engine Server All these methods cause the print job to be started so you must complete all necessary customization in previous method calls You can also retrieve the files back to the Web Server by setting the Ret rieveMode property to TRuE and setting outputPath for the Web Server rather than the Report Server Parallel Crystal D eveloper s Manual 15 Version 2 4 Revised 5 27 00 Handling Errors from ASP 2 0 When an error occurs in the Automation Server it stores an error message internally and returns a generic COM error called amp _ratx Unfortunately when the VBScript interpreter detects the error it writes the hexadecimal value of _rarx together with the COM description string Unspecified error to the response page and terminates without disconnecting the client from the Report Server In order to handle errors satisfactorily in VBScript you must adhere to the following guidelines 1 Insert an on Error Resume Next Statement at the start of the script When an error occurs the VBScript interpreter will return control to the statement following the call to the Automation Server method or property 2 After every method or
153. blem can occur on networks with badly configured Domain Name Servers 11 You may find that calls to connect ToReport Server succeed when the host is specified with an IP address but fail when the host is specified with a domain name You should check with your System Administrator that the D NS servers on all machines are configured correctly and can handle both forward and reverse lookups Problems with Export Formats In Chapter 7 the section entitled ICRExportO ptions describes methods and properties for controlling the output format and destination of the report Two problems can arise when specifying the export options 1 Not all of the formatting capability provided through ICRExportoptions may be available on the Report Server In practice the Report Engine Server relies on a set of external D LLs provided with your Parallel Crystal Installation to provide reports generated in formats such as Word Excel and Lotus If you encounter problems in generating reports in anything other than PDF PostScript or HTML check with your System Administrator that the D LL is available on the Report Server and accessible through the PATH environment variable The names of the formatting DLLs are listed in the section Print Job Outputs in Chapter 9 When the Export method of the ICRReport interface is called your current export property settings are packaged and sent to the Report Engine Server The packaging is complicated an
154. calls from the browser to the Report Server via the Web Server Instead all customization code is executed within the WebA S Report Server framework and only the final report is returned to the browser Figure 1 6 illustrates the role of each component when Parallel Crystal is integrated with Microsoft s A ctive Server Pages technology Parallel Crystal D eveloper s Manual 22 Version 2 4 Revised 5 27 00 1 Client navigates to 6 Report retrieved to client ASP page browser Client browser HTTP 2 Web server receives HTTP request and runs ASP page 3 Customization calle made fram VBScript weithin 5 Report retrieved to web Server ASP page Web Server IGP 4 Customization calls executed wih Parallel Crystal Report Engine Parallel Crystal Report Server Database Server Figure 1 6 When the client browser navigates to an ASP page the Microsoft IIS Web Server loads the page and runs the VBScript interpreter on the VBScript tags embedded in the page The VBScript statements make customization calls to the Report Engine and then the generated report is retrieved to Web Server The report itself or its URL is then returned to the client s browser You should bear in mind that the Web Server Report Server and D atabase Server need not all run on different machines However the configurations shown in Figures 1 5 and 1 6 allow maximum opportunity for performance tuning Parallel Crystal provides a networke
155. ces A client can connect to all servers using a single API call or can customize individual connections by setting properties through the service providers In the following sections we describe how clients are created how they connect to the Report Server and how they can customize their connections We begin with a short overview of the server programs running on the Report Server and the services they provide Services for Clients When a Parallel Crystal Report Server is started it makes a range of services available though special purpose servers e The Gateway Server provides an initial point of contact for your client and is responsible for starting a Report Engine Server to generate your report All clients share access to a single G ateway running on the Report Server To connect to the Gateway you must specify the Report Server host and optionally the name of the Gateway e The Report Engine Server provides report customization and generation facilities The Report Engine is allocated to your client by the G ateway and is terminated when you disconnect from the Report Server Report Engine Servers are not shared amongst clients e The Configuration Server allows clients to retrieve configuration information about their Parallel Crystal installation on the Report Server For example you can obtain the name of the directory containing sample reports or the name of the directory to contain sample output All clients share acc
156. chronization primitives and their implementation in the Java Runtime Environment usually relies on the platform s native threads Because threads are built in to the Java language you often have to be thread aware even when building programs that you believe to be single threaded For example if you build a G UI into your application the underlying Abstract Windowing Toolkit will execute your event handlers on an internally allocated callback thread Normally this thread does not run concurrently with your program s main thread and so you do not have to worry about synchronization problems However very subtle problems can arise when multiple client threads contend for AWT resources In order to support multi threaded client applications the PCRE Java classes provide instance level thread safety This is achieved by making most property methods synchronized and by structuring the pcrEEngine and PCREJob Classes in such a way that their instance data is managed with a write once read many access protocol This allows multiple client threads to share instances of these classes without suffering undue synchronization overhead When you declare an instance of a PcREApplicationClient Or PCREAppletClient it holds a context that includes the thread on which the constructor was invoked the console for the client the set of service provider classes and the connection to the Report Server Since each client has its own Report E
157. client getConfigServer getSampleReportDir client getServer SetFolder samples PCREEngin ngine client OpenEngine j PCREJob job engine OpenJob Box rpt job Close engine Close The report Box rpt is part of the standard Parallel Crystal installation However its full path name is likely to be installation dependent We therefore use the get SampleReportDir to return the path name of the sample reports directory and then call the setFolder method of the pcreserver Class to change the working folder of the Report Engine Server accordingly Thereafter we can refer to all report files by their names relative to the sample directory Parallel Crystal D eveloper s Manual 102 Version 2 4 Revised 5 27 00 Parallel Crystal Load Balancer When your client has access to a group of Report Servers you can use the Parallel Crystal Load Balancer service to ensure that the report processing load is distributed appropriately across the available server machines The load balancer provides two interfaces for e Automatic use e Manual use Automatic Mode When you use automatic mode the client is connected to a Report Server chosen by the Load Balancer The choice is made by a selection algorithm that is normally configured by the System Administrator The two algorithms most commonly used are e Load factor compares all the Report Servers in the group and returns the one with the s
158. clients may iterate through all items with the For Each Statement that calls the _NewEnum property to create an enumeration of Subreport O bjects Methods Custom Properties Navigation Item Count Parent _NewEnum Report Application Table 6 12 ICRSubReportObject s the custom interface exposed by each Subreport O bject in the collection The methods and properties are listed in Table 6 13 They provide access to the sub report s name and kind and parent report and allow a Report O bject to be created for the sub report Methods Custom Properties Navigation Kind Parent Links Report Name Application Table 6 13 Interface acquisition Dim srptc As ICRReportObjects srpt As ICRSubReportObject Set srptc section ReportObjects Set srpt srptc Item 1 Set srpt srptc 2 Collection iteration Dim report As ICRReport subreport As ICRReport For Each srpt In section ReportObjects report srpt Report subreport report OpenReport srpt Name Next Sl Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 ICRSortField s ICRSortFields is the collection interface exposed by the SortFields Collection O bject The methods and properties are listed in Table 6 14 A SortFields Collection O bject is obtained from the recordsortFields property of the Report O bject Each item in the collection is a SortField O bject representing a record sort field within the
159. com PCREAppClient 111 222 333 444 If you supply nut or the empty string oruse an abbreviated constructor call PCREAppClient then your client will be connected to a Report Server somewhere on your network This is okay if you know that there is only one Report Server and you don t necessarily care about its location However if you have multiple Report Servers and you leave the host unspecified you cannot predict which server the connect Call will select Therefore you must take steps to ensure that your report files are accessible on all of the Report Servers to which you could possibly connect This may not be easy so we recommend that you specify a host whenever possible The constructor arguments argc and argv are normally derived from the application s command line arguments and are used to provide fine control over the connection of the client to the Report Server In practice they are only required when connections must be established across the Internet or via a firewall You should contact our Technical Support staff if you believe you have special operating requirements that will cause difficulty in connecting to your Report Server Parallel Crystal D eveloper s Manual 252 Version 2 4 Revised 5 27 00 To summarize here are some typical calls to the pcrEappclient constructor m Create an application client for use with a PCR Server on an unspecified host A subsequent cal Connect will s
160. connect ToReport Server returns successfully your client is connected to a Report Engine Server running on the nominated host The Report Engine is allocated exclusively to your client and performs customization and report generation in response to calls on the methods and properties of the tcrapplication and IcRReport interfaces The Report Engine Server always runs in a stand alone server process Disconnecting from the Report Server You must call the ICRApplication method pi sconnectFromReportServer in order to terminate your Report Engine Server and release corresponding memory resources in the Automation Server This method is declared as follows Visual C HRESULT DisconnectFromReportServer void Visual Basic Sub DisconnectFromReportServer Visual J void DisconnectFromReportServer g Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 This method never returns a COM fail code Typically you call DisconnectFromReport Server as follows Visual C app gt DisconnectFromReportServer Visual Basic app DisconnectFromReportServer Visual J app DisconnectFromReportServer DisconnectFromReport Server also recovers memory resources in the Automation Server However to be effective Visual C clients must ensure that all interfaces to Automation Objects have been released manually or via smart pointers the disconnect call is made Visual Basic and Visual J clients
161. connect to this address NumberOfReportEngines is the number of Report Engine Server processes currently running on the Report Server e NumberOfReportServerProcessors is the number of CPU processors on the Report Server host e Loadfactor is a measure of the reporting load on the Report Server It is currently given by NumberOfReportEngines NumberOfReportServerProcessors If you have 4 Report Engine Server processes on a 2 processor machine then the load factor is 2 If you have 4 Report Engine Server processes on a 1 processor machine then the load factor is 4 In the following sections we demonstrate how to call the LoadBalancer manually using Visual C Visual Basic and Visual J The example retrieves the list of available Report Servers from the report Servers property and then iterates through the list locating the server with the smallest load factor The client connects to this server by passing it to the Application O bject s connect ToSelectedReport Server method For brevity and simplicity details of error reporting are omitted When using the Load Balancer in manual mode you should bear in mind that the load factor in each of the Report Server O bjects is correct when the call to the Report Servers property returns However it will become invalid as other clients connect independently to the same group of servers and therefore it is not possible to guarantee that a choice made solely on the basis
162. constructor argument nost specifies the Report Server to which your client will connect It may take the form of either a symbolic host computer name or a dotted host computer IP address For example PCREApplicationClient example host com PCREApplicationClient 111 222 333 444 zl Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 The constructor argument port specifies the port at which the G ateway process provides its initial reference When the client connection process occurs the client obtains the initial reference to the G ateway from this port The G ateway then provides the initial reference to all the other PCRE Services This process used to involve obtaining the references to these objects from the O SAgent The move toward more O RB independence in the Java Client mandated discontinuing usage of the O SA gent All client constructors throw a PCREClientE rror exception if the CORBA communication failed to initialize The constructor arguments args and props provide fine control over the connection of the client to the network They are sometimes required when Report Servers are accessed across the Internet or via firewalls or when inter operability is required between Parallel Crystal and one of the Java oriented Web Application Servers You should seek technical support if you believe you may have special operating requirements that may cause difficulty in connecting your client to the Report
163. ct from the Report Server If you use C you can rely on the destructor to disconnect your client automatically If you use C you must remember to call a disconnect A PI function We ll explain these operational details in the following sections C Application Client Instantiation The pcrREAppClient Class allows C application clients to connect to the Parallel Crystal Report Server The client has connect and disconnect methods and acts as a container for service provider classes that provide client side access to Report Server services Y ou can install a console in the client to adapt the client s error reporting facilities to the user interface provided by your application A PCREAppClient is instantiated using one of the following two constructors PCREAppClient PCREConsole console const char host NULL int argc 0 char const argv NULL PCREAppClient const char host NULL int argc 0 char const argv NULL The constructor argument console specifies an instance of a class implementing the PCREConsole interface If you call the second constructor then your client will be created with an instance of the default console class pcrEappconsole The constructor argument host specifies the Report Server to which your client will connect It may take the form of either a symbolic host computer domain name or a dotted host computer IP address For example PCREAppClient example host
164. ctionFormat section options Parallel Crystal D eveloper s Manual 78 Version 2 4 Revised 5 27 00 Sub report Management The following group of methods allows you to access sub reports within a given report OpenSubReport CloseSubreport GetNSubreportsInSection GetNthSubreportInSection Sub reports are accessed by Get NthSubreport InSection that returns a PCRESectionInfo helper class containing the name of the sub report You can open ajob for the sub report by passing the name to the opensubreport method of the PCREEngine Class The following fragment iterates through all the sub reports in the n th section int section job GetSectionCode n int nSubReports job GetNSubreportsInSection section for int i 0 i lt nSubReports i PCRESubreportiInfo info GetNthSubreportInSection section i PCREJob subReport engine OpenSubreport job info name customize sub report subReport CloseSubreport Graph Manipulation The following group of methods allows you to manipulate graphs and charts in your report GetGraphType GetGraphData GetGraphText GetGraphOptions SetGraphType SetGraphData SetGraphText SetGraphOptions Graphs are located by a section code returned by the Get Sect ioncode method Each section can contain multiple graphs that are numbered from 0 upwards The GetGraphOptions GetGraphData and GetGraphText methods respectively retum
165. d can fail if the client and server installations of Parallel Crystal are not version compatible If you experience problems and are sure that the formatting capability is available get your System Administrator to check the Parallel Crystal installed versions on your client and the Report Server Parallel Crystal D eveloper s Manual 227 Version 2 4 Revised 5 27 00 Problems with PDF In Chapter 6 we described how to generate PD F reports using the methods Output ToPDF ExportToPDF StartParallelPrint and ParallelPrintReport The Output Toppr method generates PD F directly using the D ynalivery PDF Library The remaining methods produce PD F indirectly by generating a PostScript version of the report first and then converting this to PDF using a utility from Adobe called Acrobat Distiller The problems that arise when generating PD F therefore depend upon which of the methods you have called The following problems are known to occur when using the Dynalivery PDF Library with OutputToPDF 1 You cannot generate linearized PD F for per page retrieval to a browser Future versions of the library may support this feature 2 OLE objects are rendered as bitmaps Bitmaps may look grainy when using the zoom feature in Acrobat Reader 3 Reports with overlapped images may not render correctly 4 Reports with fonts other than True Type fonts may not render correctly In general we recommend you try to generate PD F using t
166. d environment for customizing and generating Crystal Reports Clients are connected to Parallel Crystal Report Engines running in the Report Server and customization A PI calls are transmitted from client to server using CORBA IIOP technology A selection of client packages allows the Server to be accessed using a variety of development tools and software technologies Parallel Crystal D eveloper s Manual 23 Version 2 4 Revised 5 27 00 Parallel Crystal Client and Server Components Parallel Crystal contains a set of server components and several distinct sets of client components The installation additionally requires a web server and may also require Adobe Acrobat tools for viewing PD F documents and the Sun JDK for Java development Note The Paralld Crystal System A dministrator s M anual is being developed to ex plain these requirements in detail The Parallel Crystal Server components include e An implementation of CORBA IIOP Parallel Crystal uses Inprise Corporation s VisiBroker product that provides client server connectivity through two components called the O SAgent and IIOP G ateK eeper e The PCRE Report Engine Server Each Parallel Crystal client is connected to a Parallel Crystal Report Engine that encapsulates the Print Engine DLL The Report Engine is a CORBA server that exposes the customization interface to clients through the CORBA Interface Definition Language ID L e The PCRE Gateway The Gateway alloc
167. d then converting this to PDF using a utility from Adobe called Acrobat Distiller The problems that arise when generating PDF therefore depend upon which of the methods you have called The following problems are known to occur when using the Dynalivery PDF Library with Output ToPDF e You cannot currently generate linearized PDF for per page retrieval to a browser Future versions of the library may support this feature e OLE objects are rendered as bitmaps Bitmaps don t display well when using the Acrobat zoom feature e Some graphics are implemented as bitmaps and cannot be magnified by the zoom in feature in Acrobat Reader e Reports with overlapped images may also not render correctly Future versions of the library may remove these limitations e Reports using fonts other than True Type fonts may have rendering problems Parallel Crystal D eveloper s Manual 14 Version 2 4 Revised 5 27 00 In general we recommend you try to generate PD F using the output Toppr method first of all If problems arise try the Export To method that generates PD F using Acrobat Distiller If problems persist and you have access to Crystal Reports Designer load your report back into the Designer and check it for errors The following problems are known to occur when using the Distiller with ExportTo When the Report Engine Server receives a call to Export To it saves the name of the PD F output file Once the report has bee
168. d vith Parallel Crystal Report Engine Parallel Crystal Report Server Database Server Figure 5 6 It is quite possible to have the IIS Web Server the Report Server and the Database Server all running on the same machine The advantage of using Parallel Crystal is that it allows you to choose a suitable configuration rather than imposing one on you In the next section we ll describe some of the preparatory work you have to do to create an ASP project on the Web Server Then we ll look at a simple script that extracts information from a form and uses it to generate a report in HTML We cannot describe all the features of ASP or the VBScript language in this manual We recommend you read a good introductory text such as the book by Francis et al and then make the occasional excursion to the Platform SDK documentation in the MSDN 1 Brian Francis and others Professional Active Server Pages 2 0 Wrox Press 1998 ISBN 1 861001 26 6 Parallel Crystal D eveloper s Manual 164 Version 2 4 Revised 5 27 00 ASP Preliminaries An ASP project is located within a sub directory of your Web Server s root directory If you have Microsoft IIS 4 0 installed then the root will typically be located at C InetPub wwwroot An ASP project is usually organized within a sub directory of the root such as c Inet Pub wwwroot ASPDemos You should place your ASP pages in files with asp suffixes in this directory together with a single file called gio
169. dress else MsgBox No Report Servers available Release interfaces EF Bs If pSelected NULL pSelected gt Release pSvrList gt Release Each numbered paragraph below corresponds to the same numbered code statement 1 The list of available Report Servers is returned by a call to the Report Servers property of the A pplication O bject 2 The number of servers in the list is returned by the count property Parallel Crystal D eveloper s Manual 20 Version 2 4 Revised 5 27 00 3 The variable pselected is used to store the identity of the Server that is selected from the list The variable mintoad is used to keep a running record of the minimum server loading 4 The loop traverses the list of servers and examines their loads one by one The list must be indexed from 1 through the value returned by the count property 5 The ttem property returns an 1Dispatch interface to the i th Report Server O bject in the list A static_cast is used to simplify the conversion to the rcrreport Server custom interface 6 pSelected is updated whenever a Server is found whose load is currently less than the value in minLoad We have to be careful here and elsewhere to call Release on interfaces when we are finished with them If these calls are omitted the Automation Server will be unable to reclaim memory resources 7 If a server has been selected we pass it in the call to ConnectToSelectedRe
170. e Each Report Engine includes a copy of the Parallel Crystal Report Engine PCRE DLL Client server connections are established by an agent on the Report Server called the PCRE G ateway e The C C Application Client performs report customization and generation by making calls to the PCRE DLL These calls are transmitted from the client to the server and then the results are transmitted back to the client e Because report customization is performed within the Report Server the Crystal report files must be present on that machine or be available through networked file store e Reports are produced on the Report Server machine However Parallel Crystal provides a mechanism for retrieving reports back to the client machine e When aC C Application Client is started it is allocated a Report Engine when it connects to the Report Server The Report Engine is terminated when the client disconnects from the Server e Multiple Report Engines execute in parallel on the Report Server However the extent to which truly concurrent behavior is sustained depends upon a combination of factors including the number of available processors the number of connected clients the overall loading on the machine and the resulting contention for shared resources We re now in a position to look at a simple C Application Client that generates a report as a PostScript document Parallel Crystal D eveloper s Manual 233 Version 2 4 Revised 5 27
171. e If a Crystal API call leads to an error dialog the Report Engine Server G UI will display the call and the dialog itself will be visible Parallel Crystal may be run in desktop mode using the Start Parallel C rystal in D bug Mode shortcut placed in the Start Programs Parallel Crystal menu during installation e Occasionally components of Parallel Crystal may crash or terminate abnormally To assist error diagnosis the Report Engine Server File Server and G ateway Servers generate log files that contain trace and error messages In addition components write error messages to the Windows NT event log The log file may be viewed using the e Occasionally your Java client may transfer to a catch clause and report the error CORBA Error CORBA UNKNOWN The most likely cause is a Report Engine Server crash rendering the remote method that you are trying to call unknown e Occasionally your Java client may transfer to a catch clause and report the error CORBA Error CORBA NOIMPLEMENT This message means the method you are trying to call cannot be found in the Report Engine Server and the most likely cause is that the Parallel Crystal installations on your client and server machines are incompatible Y ou should get your System Administrator to make appropriate checks and re install if necessary Parallel Crystal D eveloper s Manual 116 Version 2 4 Revised 5 27 00 e Your Java client may report
172. e desired port Finally it defaults to 14020 When the PCREApplicationClient is instatiated it can take an initial reference port as an argument If a version without the port argument is used then it uses the default of 14020 If the client is trying to connect to a port that the server isn t using then a connection failure will occur The following connection problem can arise with badly configured Domain Name Servers You may find that connections succeed when specifying a host with an IP address but fail when using a domain name If this is the case you should check with your System Administrator that the D NS servers on all machines are configured to handle both forward and reverse lookups Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 m Problems with Applets First consider this information about browsers If you are using Internet Explorer you need to explicitly enable it to run Java applets To do this select the O ptions Dialog with View Options Then select the Security tab and check the Enable Java programs box If you are using Netscape Communicator output written to the System out character stream is displayed in the Java Console You can use this to display simple tracing messages The Console is displayed by selecting Communicator Java Console If you select the console window and type an h character the console will display a set of single character commands that you can use
173. e Blaszczak Professional MFC with Visual C 5 Wrox Press 1997 ISBN 1 861000 14 6 A Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Example 5 2 shows how the VC COM wrapper classes are used to simplify access to the Automation Server import lt cpemasl tlb gt no_namespace include lt iostream h gt static void RunReport void int main int argc char argv HRESULT hr hr CoInitialize NULL if FAILED hr return 0 RunReport CoUninitialize return 0 static void RunReport void ICRApplicationPtr pApp try pApp __uuidof CRApplication pApp gt ConnectToReportServer flea acme com _bstr_t name C SampleReports Box rpt ICRReport report static_cast lt ICRReport gt pApp gt OpenReport name report gt PrintoOut report gt Release pApp gt DisconnectFromReportServer catch const _com_error cout lt lt pApp gt GetLastErrorString lt lt endl Example 5 2 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Ix 25 no BW rw oO AI Tiz B Each numbered paragraph below corresponds to the same numbered code statement 1 The import statement instructs the VC compiler to use the type library in file cpemas1 t1b to generate a wrapper class for each interface in the PCRE Object Model The wr
174. e Check that the machine can be accessed with Ping or Network Neighborhood e Check that the MAS PCRE product is running on the machine e If running as a service look in Settings Control Panel Services to check that the NT service Parallel Crystal is started e Check that OsAgent and PCREG ateway are active by using the Task Manager Process List e Open aDOS box and type PCREServer Check that a PCRE Server G UI appears before dismissing it Diagnosing Client Web Server side Setup Problems The simplest way to set up correctly on the Web Server is by using a standard MAS installation to put the whole product or the relevant client part on that machine If you need to install or check the MAS client manually there are only three files involved at the time of writing Cpemasi dll ou The Automation Server Cppclient dll 00 The supporting C C client DLL OW Todle The CORBA Orb DII handling network communications You must ensure that the cppclient dll and orb_r dll are in directories which are mentioned in the PATH environment variable and that there are no earlier versions of these files in directories mentioned in PATH Normally they are placed in a directory called c mobileapps pcre bin You must register the cpemas1 dll To register the dll open a Command Prompt and type regsvr32 cpemas1 dll A message box will confirm if the registration was successful Cpemas1 dll is a COM object and can be examined w
175. e Load Balancer returns a collection of Report Server hosts together with their load factors Y ou can iterate through the collection and choose a server based on your own selection criteria Then you connect by passing the server to the Application O bject You should bear in mind that when you use the Load Balancer in Automatic Mode you cannot tell in advance which Report Server your client will connect to Therefore you must ensure that your report files are accessible from all possible servers in the group This can be achieved either by having shared or mirrored disk storage Using the Load Balancer in Automatic Mode Using the Load Balancer in automatic mode is very simple First you set the Application O bject s Automat icLoadSharing property to True and then you call Connect ToReport Server Without specifying a Report Server host name Visual C ICRApplicationPtr pApp __uuidof CRApplication pApp gt AutomaticLoadSharing TRUE pApp gt ConnectToReportServer Visual Basic Dim pApp As ICRApplication Set pApp New CRApplication pApp AutomaticLoadSharing True pApp ConnectToReportServer VBScript Dim pApp Set pApp Server CreateObject MAS CRApplication 1 pApp AutomaticLoadSharing True pApp ConnectToReportServer Visual J ICRApplication pApp ICRApplication new CRApplication pApp putAutomaticLoadSharing true pApp ConnectToReportServer Parallel Crystal
176. e Parallel Crystal Report Retrieval Service Retrieval to C Clients Y ou activate the Report Retrieval Service for your C client by first calling the setRet rieveMode property method with the argument value TRUE Then you specify a path for the generated report on the client s machine rather than the Report Server machine It doesn t matter whether you call set Ret rieveMode before or after you call Connect as long as you call it before the method that specifies the report destination The following example shows how the service is used to return a PDF report to the client machine PCREAppClient client example host com Ei is try client setRetrieveMode TRUE EL 2s client Connect oft sc PCREEngine engine client OpenEngine PCREJob job engine gt OpenJob 4 C MobileApps pcre SampleReports Box rpt job gt OutputToPDF C MyReports Box pdf null Like D8 job gt Start 6 job gt Close engine gt Close catch PCREError amp e e Report Each numbered paragraph below corresponds to the same numbered code statement 1 A PCREAppClient is created for connection to a Report Server 2 The automatic Report Retrieval Service is activated by calling setRet rieveMode with the value TRUE 3 The client is connected to the Report Server 4 A print job is opened for c MobileApps pcre SampleReports Box rpt
177. e Report Server file store allow the file to be created e The call to the Report Object method Printout may fail and report the error Cancelled by user This message is returned by the Report Engine when it is unable to locate a suitable printer This is either because the printer has become inaccessible because of network problems or because the printer settings inserted into your report at design time are no longer valid You may need assistance from either your System Administrator or D ynalivery Technical Support Staff to fix this problem Parallel Crystal D eveloper s Manual 143 Version 2 4 Revised 5 27 00 Things to Remember Independent of whether you use bare COM or COM support classes ALWAYS call DisconnectFromReportServer after you have finished generating your report It will release resources on the Report Server and recover memory in the Automation Server If you use bare COM with C make sure you understand the CO M specification rules for calling addref and Release In particular ALWAYS call release when you are finished using any interface pointer returned by the Automation Server If you use COM smart pointer classes such as _com_t make sure you understand when they will call adaref and Release Remember that a call to QueryiInterface does an implicit addref Parallel Crystal D eveloper s Manual 144 Version 2 4 Revised 5 27 00 Using Parallel Crystal with Visual J This section de
178. e examples in this section again show you how to produce reports in Postscript PD F and HTML In the section entitled Using Parallel Crystal with Active Server Pages we describe how to use the PCRE Object Model from web server pages that include embedded scripts written in a simplified version of Visual Basic called VBScript VBScript clients allow Report Customization to be integrated with Microsoft s Active Server Pages web development technology You use the PCRE Object Model from VBScript in exactly the same way as you would use it from Visual Basic The next section contains a rather lengthy introduction to COM If you are anxious to get started then skip directly to one of the following sections on using Visual C Visual J Visual Basic or Active Server Pages Parallel Crystal D eveloper s Manual 119 Version 2 4 Revised 5 27 00 Parallel Crystal and ActiveX COM clients This section describes how to access Parallel Crystal using Microsoft s CO M ActiveX technology ActiveX is an umbrella term that was introduced in 1996 to embrace Microsoft s third generation O LE and COM technologies Both OLE and COM are important because they allow all the major Microsoft development tools to access Parallel Crystal through a collection of COM objects provided by the Parallel Crystal Automation Server It is impossible to describe the Automation Server without some preliminary discussion of COM and COM Automation COM itself de
179. e interface The C Client Library automatically transmits the calls across the network to the Report Server and returns the results to your program You need only add two extra function calls to manage your Report Server connection PEInitialize PEUninitialize In the following sections we ll demonstrate simple C Application clients that generate reports as PostScript PDF and HTML documents Generating a Simple PostScript Report The sample C program shown in Example 8 4 generates a report from the Box rpt report file and sends it to a PostScript printer We ll describe it line by line but note that if you try the program e actly as presented here it will neither compile nor execute We ll explain why in the commentary below where each numbered paragraph corresponds to a statement in the code include lt pcre h gt Ae n include lt stdio h gt static void ReportError short job HANDLE handle short length char buffer 256 PEGetErrorText job amp handle amp length f f LTs PEGetHandleString handle buffer length printf s n buffer void main int argc char argv short job BOOL bOK PEInitialize NULL example host com 2 argc argv PE_DO_CONNECT if boK ReportError 0 goto close_app 3 if PEOpenEngine A ReportError 0 goto close_app Example 8 4 cont on next page Parallel Crystal D eveloper s
180. e section entitled Parallel Crystal Configuration Server describes how clients can retrieve configuration information such as the installation path names of various directories The information currently returned is primarily useful for sampling the tutorial examples provided with Parallel Crystal The section entitled Parallel Crystal Report Retrieval describes how reports generated on a remote Report Server can be retrieved to the client s machine Web based clients such as ASP pages can use this service to pull a report back to the Web Server before returning a suitable hyperlink in the response page The section entitled Parallel Crystal Load Balancer describes the load balancer service that allows client connections to be distributed across a collection of Report Servers When clients connect in automatic mode the Load Balancer uses dynamic load monitoring to select an appropriate Report Server However clients can also request load monitoring information to be returned by the Load Balancer enabling the final section of the Report Server to be made manually Parallel Crystal D eveloper s Manual 179 Version 2 4 Revised 5 27 00 Automation Server Clients In this section we ll describe how ActiveX clients use the Automation Server to connect and disconnect to and from the Parallel Crystal Report Server We ll use the term automation client to refer to any client written in Visual Basic VBScript Visual J or Visual
181. e to the Application O bject and that the method connect selects an appropriate Report Server public void Connect ICRReportServer selected null Tf 1s double minLoad 1000 ICRReportServers svrList 2 ICRReportServers app getReportServers int nsvrs svrList getCount 3 Tterate through Report Server List for int i 1 i lt nsvrs itt A ICRReportServer server ICRReportServer svrList getItem i IIIR double load server getLoadfactor 6 if load lt minLoad minLoad load selected server Connect to selected server if selected null pepe Ts app ConnectToSelectedReportServer selected MsgBox Connected to Report Server on host 8 selected getHostAddress else MsgBox No Report Servers available Each numbered paragraph below corresponds to the same numbered code statement 1 The variable se1ectea holds a reference to the most lightly loaded Report Server and the variable min oaa holds the load factor for selected They are initialized to represent a state in which no server is selected 2 The list of available Report Server is returned by the getReportServers property method Note that the property returns an object reference that must be cast to the custom interface type IcRReport Servers 3 The number of Report Servers in the list is returned by the getcount property method 4 The loo
182. e to the directory containing your ASP files If these are located in the directory aspdemo in the Web Server s root then this name will be visible in the scope pane 3 Right click on the directory name and select the Properties field from the popup menu The Properties D ialog shown in Figure 5 7 on page 166 appears 4 Select the check box labeled Run in separate memory space isolated process 5 Press OK to implement the selection Parallel Crystal D eveloper s Manual 165 Version 2 4 Revised 5 27 00 ASPDemo Properties 2 EA shae located om another computer Mgl Figure 5 7 The effect of this selection is to run your scripts in a separate Proxy server process rather than as part of the Web Server s process If you are unfortunate enough to generate a fatal error during development the Proxy Server may be terminated but the Web Server will remain unharmed This precaution is well worth taking Generating HTML Reports with ASP In this section we describe a simple A SP project that produces a report in HTML The project comprises the following files located in the directory asppemo in the web server root directory 3 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 InetPub wwwroot ASPDemo globals asa SimpleDemo asp SimpleAPICalls asp The simpleDemo asp file contains an HTML form that is used to identify the Report Server host the name of the report file and
183. e value overrides False and determines whether the property applies locally or globally A Section O ptions O bject is obtained from the Options property of the Section O bject Methods Custom Properties Navigation Properties BackColor Parent BackColorFormula Report FreeFromPlacement Application KeepTogetherFormula NewPageAfter NewPageAfterFormula NewPageBefore NewPageBeforeFormula PrintAtBottomOfPage PrintAtBottomOfPageFormula ResetPageNumberAfter ResetPageNumberAfterFormula SuppressIfBlank UnderlaySection UnderlaySectionFormula Visible VisibleFormula Table 6 11 Interface acquisition Dim options As ICRSectionOptions Set options section Options Property calls options BackColor crBlue options NewPageBefore Tru options UnderlaySection Tru Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 A ICRReportObject s ICRReportOb jects is the collection interface exposed by the Reports Collection Object The methods and properties are listed in Table 6 12 A Reports Collection O bject is obtained from the Reportobjects property of the Section O bject Each item in the collection is a Subreport O bject representing a sub report within the parent section and the number of Subreport O bjects is returned by the count property Individual sub reports are obtained by the tt em method that takes an index or string argument identifying the report required Visual Basic
184. eK eeper as a proxy server You can save some connect time by including the following lt param gt tag between lt applet gt and lt applet gt tags lt param name ORBalwaysProxy value true gt This tag tells the client to contact the G ateK eeper rather than try a direct connection to the Report Server that will fail If your client lies behind a firewall the G ateK eeper should be configured to run with an accessible external IP address and port combination and should also be enabled for HTTP tunneling if the firewall restricts internal traffic to the HTTP protocol Your System Administrator should advise you on how best to deal with firewalls A number of other problems can occur which are characteristic of applet programming Remember that browsers and web server have caches Sometimes you can fix a problem in an applet but continue to get the old version of the class file because it was resident in a cache When debugging its best to re start your browser each time and if possible to re start your web server A browser won t download a class file if it finds it using the local CLASSPATH This can be the cause of much confusion so check your local file store for possible conflicts Applets are an integral part of the Java Abstract Windowing Toolkit so their methods are invoked on callback threads Y ou should be aware that each call to the Report Engine Server such as the pcrEJob start method will block the thread for the dur
185. eOutputs directory If the report has embedded images the corresponding JPEG files will be stored in the same directory e To generate a report in PostScript and save it in a file replace the call to printout with the following call to output Tops Step 8 report gt OutputToPs C SampleOutputs Box ps The report will be generated in the file Box ps in the sampleoutputs directory Note that you cannot depend upon the file being completely generated when you return from the method call This is because the file must be generated by the Windows Printer Spooler that does not run synchronously with the Report Engine Server Remember that all these methods cause the print job to be started Therefore you must complete all necessary customization in previous method calls Parallel Crystal D eveloper s Manual 140 Version 2 4 Revised 5 27 00 The Trouble with Smart Pointers In the preceding example we used a smart pointer type IcRApplicationPtr to access the IcRApplication interface and a raw IcRReport pointer to access the rcrReport interface However cpemas1 t1h header file contains the definition of a smart pointer called tcrReportPtr so why didn t we use it The answer is that smart pointers are often not smart enough In the case of tcRReportPtr the following difficulties arise e Since 1crApplication OpenReport returns aN IDispatch pointer it is necessary to convert this to a smart rcrReportPtr pointer
186. ecified by supplying the full path name of the report file on the Report Server Perform customization and report generation calls for each print job using the methods of the pcrEJob Class Close all your print jobs when they have completed using the close method for each job Close your print engine The pcreappClient destructor terminates your connection to the Report Server If you declared the client instance dynamically with new remember to destroy it with a corresponding call to delete You should not attempt to call delete on instances of the pcrEEngine and PCREJob classes returned by the openEngine and OpenJob methods Memory for these classes is managed internally by the C Client Library Parallel Crystal D eveloper s Manual 236 Version 2 4 Revised 5 27 00 Trouble Shooting the Simple C Client Let s examine what happens when things go wrong in the simple C client First suppose you supplied an incorrect host name in the declaration of the PCREAppClient variable For example suppose you typed PCREAppClient client bad host name This statement will be executed correctly but the subsequent call to connect on line 3 will throw an exception and control will transfer to the handler at line 12 This statement will then print the following line PCRE Gateway error Connect cannot connect client to Gateway Service on host bad host name The error message
187. ed from pcreserviceError in order to group errors that originate in the Report Server PCREInternalError EServer EGatewayError Figure 9 2 Parallel Crystal D eveloper s Manual 289 Version 2 4 Revised 5 27 00 The six derived error classes are e PCREClientError is used to identify errors that are detected by the Parallel Crystal C client classes These errors are caused by an invalid argument to a client side method or an inappropriate use of such a method PCREGatewayError is used to identify errors that are detected in the G ateway Server and are reported back to the client These errors can arise when the client tries to connect to the G ateway or when the G ateway tries to start your Report Engine Server pcCREServerError is used to identify errors that are detected in the Report Engine Server but are not specifically related to the PCRE customization API For example they may be generated by a network failure PCREAPIError is used to identify errors that are detected by the Crystal Reports Print Engine in the Report Engine Server The Server transforms the error into an exception containing the Crystal error number and message and then returns it to the client e PCREFatalError and PCREInterna1 error are used internally by the C clien
188. ed with a copy of the ASCII string c sampleReports Box rpt 6 The rcrapplication OpenReport method is called via the papp smart pointer and the result is stored in a result pointer with type tcrReport This statement is executed in two steps First openReport is called via the following code inline IDispatch ICRApplication OpenReport _bstr_t ReportFileName const _variant_t amp OpenMethod IDispatch _result HRESULT _hr raw_OpenReport ReportFileName OpenMethod amp _result if FAILED _hr com_issue_errorex _hr this _uuidof this return _result The method calls the real openreport that creates the co class implementing the ICRReport interface However openReport is designed to work with automation controllers that are restricted to using disp interfaces and so its result is a pointer to the 1pispatch interface on the same object Although we could use 1pispatch directly in C it is far more efficient to convert back to the dual rcrReport interface because we can then use the v table to make efficient method calls This conversion is performed implicitly by the static_cast Strictly speaking this is not correct COM programming practice We ll discuss the alternatives in the section entitled The Trouble with Smart Pointers A Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 7 The call to printout uses the wrapper class to provide the default values for missing
189. eeeaeeaeesecsecseesecseeeseeaeesecaeeeeeeaeeaeeneeeeeesees Using Manual Load Balancing with Visual C g Using Manual Load Balancing with Visual Basic cecesesssscesssecceseeseeseesecsecseceaeesecsecsececeaeeseeseesecsecseceeeeaeeaecaeseeeeaseaeeaeeeerenee 221 Using Manual Load Balancing with Visual J cceccescessssseseeseceececceseeseesecsecsecceeseesecsecseceaeeseeseesecsecseeeeeeaeeaecseeeeeeeeaeeaeeaeeaeenee 223 Parallel Crystal D eveloper s Manual 5 Version 2 4 Revised 5 27 00 Chapter 7 Trouble Shooting ActiveX Clients scscccsssssscssssssssesscsssssssesssesssssesssssssessssssssssseassssesscsesscssseesscssssaseesessessssesssseseeses 225 Problems with C lent Connecti Ons ss 2id0iic60s8s ves cessevedecesuyet csezevee E EEEE RA ATE EREINEN EAN eased ARTEA RTIA 225 Problems with Export Formats isise ereen toeni eE anaa OEA ETENE EAD EREE EE E TE E REEERE e aeae 227 Problems with PDF 0 0 228 Problems with the Report Server 1 229 Chapter 8 Getting Started with C C Clients cscssssssssssssssssssssssssssssscsssesssssesssssssessesssssssssesessessesessesssecssesessassesessesessessssesseses 231 Using Parallel Crystal in a C Application ccccccsecsesessesccssessseseescescesceescescesceaceseesceesensecsseseessesaeesseeaenaeeseeseseneeaeeeeeseeaeseesenseaseas 234 Generating a Simple PostScript Report 234 Trouble Shooting the Simple C Client 237 Generating a Simple P
190. eeseeaeeaeeneeaees 140 The Trouble with Smart Pointers 141 Handling Errors from COM eeeeees 142 Trouble Shooting Simple C COM Clients 143 Things to Remember posisi errei Eae EE TEER ETE I EE nua an maa LEESE means TISERE ead nineteen 144 Parallel Crystal D eveloper s Manual 4 Version 2 4 Revised 5 27 00 Using Parallel Crystal with Visual It tescdfSasccasscacaceusetick AEN EENEN NEER RE AER ARE Vis al J Preliminaries oososreirr esearo AEA E EEEE AA EAA AESI EEEE AAEE A ORTE OA a Aa ata E iR Generating PostScript Reports with Visual J a Generating PDF and HTML Reports with Visual J ccccsscescesscsceseeseeseeeceeceseeseesecsecseceeeesecsecsececeseeseeseeseeseseeeeeseaeeaeeaeeeeenes 149 Handling Errors from Visual J ssccssessceacececaveascsasstsscesaevavenasecancnsavavesanuasccanaabase ateyavenachazascasejacessuaganserebsceveavasecnareiaeevansasersoensa 150 Trouble Shooting Simple Visual J Clients 20 0 0 ccceccescsssesseseeseceeeeceesesseesecsecsccceesesseesecsecaeeseeseesecseesececeeseeaecseeeeeeeeeaeeaeeaeeeeeees 151 Using Parallel Crystal with Visual Basics cccccsscsscedessessssie sua easvagasees ovea ide bes bas ots luca dd cbua ah ola SVaed ced Sas ota A Visual Basic Preliminaries ieys erosi eea sas dass raea e EEr T aE TOVE eSEE AVENENT EEV EVRENE SASA TAVA TVE TAVO SEE OV peas nes saasntonas etnies Generating PostScript Reports with Visual Basic us Generating PDF and HTML Report
191. el Crystal D eveloper s Manual 303 Version 2 4 Revised 5 27 00 Using the Load Balancer from C C clients use the Load Balancer in automatic mode by supplying pz_LB_connect as the last argument to PEInitialize If the Load Balancer is unable to locate a Report Server PEInitialize Will retum ratsz and you should call pecetErrortText to get the associated error message For example if PEInitialize NULL NULL 0 NULL PE_LB CONNECT HANDLE handle short length code if PEGetErrorText 0 amp handle amp length har msg 256 PEGetHandleString handle msg length printf Client initialization failure s n msg Q return The connection process is identical to that used in the C client To use the Load Balancer in manual mode you call the pERequestReport ServerInfo function that returns a vector of candidate hosts You apply your own selection procedure to the vector and then call the peconnectWithReport ServerInfo function passing the selected vector element as argument The function completes the connection to the Report Server The following example shows a typical code fragment PCREReportServeriInfo host servers 100 int number if PEInitialize NULL NULL 0 NULL PE_NO_CONNECT handle error Get a list of available Report Servers number PERequestReportServeriInfo servers 100
192. emal environments that run your automation controller use these entries in the following ways 6 MAS Application and mas Application 1 are called PROGIDs and allow VBScript and JScript controllers to locate the automation server D LL with the CreateObject e 81B34614 B2B4 11D1 8c38 000000000000 is the CLSID that uniquely identifies the application object s co class The co class implements the interface ICRApplication that forms the root of the object hierarchy Collectively the registry entries provide a way to map from PROGIDs to CLSIDs and back again Visual C automation controllers can use the CLSID directly but Visual Basic controllers must locate the PROGID first and then use that to locate the CLSID InprocServer32 identifies the full path of the automation server D LL and indicates it is loaded into the same process address space as your client This means that calls on the automation objects methods and properties are efficient since they do not cross thread process or machine boundaries e ThreadingMode1 identifies the threading characteristics of the automation server The value Apartment allows a single process to run multiple copies of the automation server concurrently provided each executes on a separate thread In environments such as a Web Server that maintain thread pools the value apartment additionally ensures that once a thread is assigned to run the Automation Server it is only ever run on that thre
193. ent if client null client Quit client null UIDisplayText Client disconnected from report server private void stop QuitClient private void destroy QuitClient With this framework the client server connection will be severed whenever you navigate away from the page containing the applet If you return a new client will be created by the call to start and it will be connected to anew Report Engine Notice that by this time you have lost the references to the pcREEngine and PcREJob Class instances that were opened within the first client since they were local variables of the Rungob method If you had stored them as instance variables in the pcreapplet class they would now reference class instances from a severed connection and an attempt to invoke their methods would cause exceptions to be thrown from the PCRE package It is possible to generate and retrieve PD F reports by changing the code of runJob to call OutputToPpF instead of passing a PCREHTMLExportInfo reference to ExportTo job Output ToPDF C MobileApps PCRE SampleOutputs Box pdf job Start job Close This code is identical to that in Example 2 3 on page 39 The showReport method will also work but you need to be sure that your web server can serve PD F files and that your browser is equipped with an Acrobat Reader plugin to display the file Version 2 4 Revised 5 2
194. ents the headers provide a set of API function prototypes that include the original Seagate Crystal Report Engine functions Both interfaces are accessed by including the single file pcre n into your program Throughout the Chapter we use a sample Crystal report file called Box rpt that is distributed with Parallel Crystal in the sampieReports directory of the product installation The file already incorporates its own data so the report may be produced directly without the need to connect to a database Before looking at some example code we need to clarify details of a Parallel Crystal Report Server installation Parallel Crystal D eveloper s Manual 231 Version 2 4 Revised 5 27 00 PCRE Server PCRE Server PCRE Server Parallel Crystal Report Server Machine PRE CA PORE Citl PORE CA Application Application Application Client Client Client Client Machine Client Machine Client Machine Figure 8 1 Figure 8 1 on page 232 illustrates the following important points e The Parallel Crystal Report Server is normally hosted within a single powerful multi processor server machine running Windows NT e A Parallel Crystal C C Application Client normally runs in a less powerful client machine such as a desktop PC running Windows 95 Parallel Crystal D eveloper s Manual 232 Version 2 4 Revised 5 27 00 e Each C C Application Client is connected to a corresponding PCRE Report Engine in the Report Server machin
195. epending upon their location relative to the client In general clients are connected to the nearest server that provides the interface requested e COM dllows interfaces to be attributed to an apartment which specifies how COM client and server threads may interact The DCO M specification allows servers to specify security requirements that clients must satisfy before access to an interface is granted 1 A vtable is a vector of function pointers that it very similar to a C virtual function table Parallel Crystal D eveloper s Manual 121 Version 2 4 Revised 5 27 00 When considering COM it is important to realize that component programming is not the same as object oriented programming Components must be resilient extensible universally identifiable and provide true black box re usability Simple classes implemented without addressing these requirements are unlikely to succeed as true software components COM embody an unfortunate reality that truly re usable encapsulated components are more complex to build and to use than dedicated C classes As a result Microsoft have added support tools to their Visual Programming Environments whose aim is to remove much of the pain of COM development For Visual C these take the form of wrapper and template classes which are available as part of the Visual C COM SDK For interpreted languages such as Visual Basic or Visual J COM support is provided through a related techno
196. eport Display the generated report if ok ShowReport C MobileApps PCRE SampleOutputs Box html Having generated an HTML report it seems natural to retrieve it and display it in your browser The method showReport does this by generating a retrieval URL using the getD ocumentBase method to generate the host and protocol components private void ShowReport String report try URL docURL getDocumentBase URL rptURL new URL docURL getProtocol docURL getHost docURL getPort report UIDisplayText Retrieving rptURL getAppletContext showDocument rptURL _blank catch Exception e Notice the extra character which has to be inserted in the final URL to separate the port component from the file name component If you forget this your browser will display an error dialog when you call showDocument 5 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Parallel Crystal D eveloper s Manual 47 Once the report has been generated and retrieved it may be time to navigate to another URL or quit the browser altogether In either case we want to terminate the Report Engine to release resources on the Server and to destroy the applet client This is achieved with the following simple guitciient method that is called from the applet s stop and destroy override methods private void QuitCli
197. eport A PrintingStatus O bject is obtained from the print ingstatus property of the parent report O bject Methods Custom Properties Navigation LatestPageNumber Parent NumberOfPages Report Progress Application RecordsPrinted RecordsSelected Table 6 23 Parallel Crystal D eveloper s Manual 203 Version 2 4 Revised 5 27 00 Interface acquisition Dim pstats As ICRPrintingStatus Set pstats report PrintingStatus Method and Property Calls Dim pages As Integer records As Integer selected As Integer pages pstats NumberOfPages records pstats ReordsPrinted selected pstats RecordsSelected ICRPrinterinfo ICRPrinterInfo is the custom interface exposed by the PrinterInfo O bject The methods and properties are listed in Table 6 24 They provide access to the selected printer s port driver and name A PrinterInfo Object is obtained from the printerinfo property of the parent Report O bject Methods Custom Properties Navigation Properties DriverName Parent PortName Report PrinterName Application Table 6 24 Interface acquisition Dim printer As ICRPrinterInfo Set printer report PrinterInfo Method and property calls Dim info As String info Printer amp printer PrinterName amp amp _ Driver amp printer DriverName amp amp _ Port amp printer Port Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 ICRReportSumma
198. eport can be generated in HTML Once again the code differs only slightly from the preceding examples Generating a report in HTML looks a little more complicated since two extra statements are required rather than one In the example line 6 creates an instance of the PCREHTMLJobExport Info Class using the name of the HTML file as an argument to the constructor This object is passed to the ExportTo method that informs the Print Engine DLL that the output for the print job is to be exported to HTML The HTML file is generated when the job is started at line 7 Notice that when a graphical report is generated in HTML any embedded images will be stored in additional JPEG files in the same directory If the name of the HTML file is Box ntmi then the JPEG files are named Box001 jpeg Box002 jpeg and so on The Parallel Crystal Report Engine supports a large number of additional export formats which allow reports to be formatted for a variety of front office tools We ll describe these formats in greater detail in Chapter 3 Parallel Crystal D eveloper s Manual 38 Version 2 4 Revised 5 27 00 import com mobileapps pcre class HTMLExample public static void main String args PCREApplicationClient client null try client new PCREApplicationClient example host com client Connect PCREEngin ngine client OpenEngine
199. er s Manual 55 Version 2 4 Revised 5 27 00 Client Configuration Each pcrEApplicationClient or which PCREAppletClient instance acts asa container for a number of service provider classes that grant clients access to the various Parallel Crystal servers running on the Report Server machine The service providers are created when you call the client s constructor and are available through get property methods in the client When the client calls the connect method connections are established between each service provider and its corresponding server Prior to connection it is possible to configure some service providers by invoking their set property methods Most commonly this is used to control operation of the client s Report Engine Server The four service providers contained by the client classes are shown in Table 3 1 The function of each is summarized below Service Provider Get Property Purpose PCREGat eway GetGateway Access to PCRE Gateway Server PCREServer Get Server Access PCRE Report Engine Server PCREConfigServer getConfigServer Access to PCRE Configuration Server PCRECustomServer getCustomServer Access to PCRE Custom Server Table 3 1 PCREGateway The pcrEGateway Class provides client access to the Parallel Crystal G ateway Server The Gateway is responsible for allocating PCRE Report Engine Servers to clients PCREServer The pcreserver Class provides client acces
200. eration using Acrobat Distiller is slower than direct generation using the output Toppr method it is retained for backwards compatibility In Example 2 3 on page 39 in Chapter 2 we showed how to generate HT ML reports using the PcREHTMLJobExport Info helper class This class is an extension of the PCREJobExport Info that automatically sets the formatting DLL to u2fntm1 a11 and the destination DLL to u2ddisk d1l There are also convenience classes for Rich Text PcRERTFJobExport Info Microsoft Word pcREWordJobExport Info and Microsoft Excel pcREExcelJobExport Info Parallel Crystal D eveloper s Manual 74 Version 2 4 Revised 5 27 00 Formula Manipulation The following group of methods allows you to retrieve and adjust the formula fields and record or group selection formulae in your report GetNFormulas GetNthFormula GetFormula SetFormula CheckFormula GetSelectionFormula SetSelectionFormula GetGroupSelectionFormula SetGroupSelectionFormula CheckGroupSelectionFormula Formula fields are accessed by an index that ranges from o to GetNFormulas 1 The retrieval methods retum a string so you must allocate a stringBuf fer to hold it The following fragment returns all the formula fields in a report int nFormulas job getNFormulas StringBuffer nameBuffer new StringBuffer 32 StringBuffer formulaBuffer new StringBuffer 128 for int i 0 i l
201. ervice provider classes For example PEHANDLE gateway server Connect to unspecified Report Server PEInitRemote NULL Retrieve gateway details char host 256 name 256 gateway PEGetGateway P P EGatewayGetName gateway name sizeof name EGatewayGetHost gateway host sizeof host Retrieve server details server PEGetServer PEServerGetName server name sizeof name PEServerGetHost server host sizeof host The peserverGet xxx and PEGatewayGet xxx functions will retum a Farse result if you attempt to call them before the client is connected to the Report Server Disconnecting C Clients You should disconnect your C client from the Report Server by calling peuninitialize before your program terminates If your client crashes or terminates without calling PEUnitialize the Report Engine Server will receive a client aborted signal and shut itself down It is possible to re open a connection to a Report Server by re calling peEtnitialize after PEUninitialize This allows you to release resources on the Report Server if for example you process a report then spend a significant amount of time on some other activity and then process another report Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 271 Report Generation for C Clients In Parallel Crystal the Repor
202. es on the Web Server with asp suffixes contain standard HTML tags interleaved with embedded scripts that are written in a simplified version of Visual Basic called VBScript The reply page delivered to the Web Browser consists of the original HT ML combined with the results of executing the scripts For example a very simple ASP page that returns the date and time on the Web Server might take the following form lt HTML gt lt HEAD gt lt TITLE gt Remote Time lt TITLE gt lt HEAD gt lt BODY gt You visited me on lt Date gt at lt Time gt lt BODY gt lt HTML gt In this fragment the VBScript interpreter replaces the text between the lt s and s gt delimiters by date and time strings before returning the HT ML page to the Web Brower Multi line scripts can be formed by locating the lt and gt brackets on separate lines or by using lt scripT gt and lt script gt HTML tags lt SCRIPT LANGUAGE VBScript RUNAT Server gt lt SCRIPT gt The attributes are necessary to identify VBScript as the scripting language and to distinguish server side scripts that run in the Web Server from client side scripts that run in the Web Browser The lt s and gt provide a more concise way of specifying server scripts and we use them throughout the examples in this section In addition to the ability to generate HT ML dynamically server side scripts can connect to any ActiveX Automa
203. ese advanced features of Parallel Crystal then skip directly to the sections entitled Application Client Connection and Applet Client Connection PCREGateway Properties The pcrEGateway provides client access to the Parallel Crystal G ateway Server running on the Report Server machine The property methods allow you to specify the Report Server host and the name of the G ateway running on that host They also allow you to specify the value of a timeout that controls the period of time that the G ateway will wait while starting a Report Engine Server These properties are summarized in Table 3 2 Property Name Purpose setHost Set the Report Server host for the G ateway Server getHost Return the Report Server host running the G ateway Server setName Set the name of the G ateway Server getName Return the name of the G ateway Server setWait Set G ateway Server timeout when starting a PCRE Server getWait Return the G ateway Server timeout Table 3 2 Parallel Crystal D eveloper s Manual 57 Version 2 4 Revised 5 27 00 Here is a simple example in which the setHost property is used to specify the Report Server machine running the G ateway Server try String hostName HostNameDialog client getGateway setHost hostName client Connect catch PCREError error error Report If you supply a Report Server host in a client constructor call the constr
204. ese wrappers in the next section g Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Using Simple Wrapper Classes l Handling COM zstr types In the example we used a simple crst r class to package BsTR and handle the conversions between wide and narrow characters Here is a simplified version of this class class CRStr public Constructors and destructor CRStr m_bstr NULL m_len 0 m_cstr NULL CRStr const BSTR str m_len SysStringLen str m_bstr SysAllocStringLen str m_len CRStr const char str m_len strlen str m_bstr SysAllocStringLen 0 m_len mbstowcs m_bstr str m_len 1 CRStr const CRStr amp str m_len SysStringLen str m_bstr SysAllocStringLen str m_len CRStr if m bstr NULL SysFreeString m_bstr if m_cstr NULL delete m_cstr Return the length of the string UINT len const return m_len Conversion operator to BSTR operator BSTR const return m_bstr Conversion operator to char operator char const if m_cstr NULL m_cstr new char m_len 1 wcstombs m_cstr m_bstr m_len 1 return m_cstr private LPCSTR m_cstr BSTR m_bstr UINT m_len The class uses the COM APIs sysallocString and SysFreestring for BSTR allocation and de allocation and the mbstoscs and wcstombs Win32 APIs for string conversion The destructor
205. ess to a single Configuration Server e The Load Balancer Server ensures that client connections to multiple Report Servers are allocated in a way that spreads the report processing load evenly across the available server machines Clients share access to the Load Balancer Server e The Custom Server is an extension to the Report Engine Server that is used to provide custom extensions to the Parallel Crystal Report Server Parallel Crystal C clients gain access to these servers through the pcrEappClient class When you call the client class s connect method it will establish a connection first to the G ateway server and then to the allocated Report Engine Server When you call the Disconnect method these connections are broken and the Report Engine Server is terminated The pcrEAppClient Class also provides access to client side service provider classes that can be used to fine tune the connection to the G ateway and control the operation of the Report Engine Access to the Load balancer is granted via special purpose client methods Parallel Crystal C clients gain access to the pcREAppClient through an equivalent set of API function calls Parallel Crystal D eveloper s Manual 251 Version 2 4 Revised 5 27 00 Parallel Crystal client programming always follows the same pattern you instantiate your client refine its configuration and connect to the Report Server O nce you have finished customizing your report you disconne
206. etimes of the pcrEEngine and PCREJob Class instances are managed internally by the pcREAppClient Consequently their constructors and destructors are private and you should n delete ot attempt to create independent instances of these classes or destroy them with Customizing Print Jobs The pcr EJob Class provides methods to perform a wide range of report customization tasks Each time you call the pcreEngine S OpenJob method you create a PCREJob instance multiple representing a print job opened on the nominated report file You can have print jobs opened simultaneously and you may customize and run each job independently of the others Each call to the pcregob s start method will run the job and generate a copy of the report When you are finished with the print job you should call the pcre In the fo sample c Job S Close method to release resources in the Report Engine Server llowing sections we present groups of related pcrEgob methods together with ode fragments illustrating typical calls For brevity we omit the surrounding try catch block but you must include it in real applications For more realistic examples you should consult the sample code distributed with Parallel Crystal Parallel Crystal D eveloper s Manual 274 Version 2 4 Revised 5 27 00 Print Job Execution The following group of methods control the execution of a print job and retum its status
207. evised 5 27 00 SQL Queries The following group of methods allows you to access the SQL Query string associated with your report Get SOQLQuery SetSQLQuery The following fragment shows how to retrieve and reset the SQL query You must allocate a StringBuffer to hold the query string StringBuffer queryBuffer new StringBuffer 128 job GetSQLQuery queryBuffer System out printin SQL Query queryBuffer job SetSQLQuery SELECT FROM CUSTOMER Sort Field Manipulation The following group of methods allows you to retrieve and set the sorting fields for the records and groups within your report GetNSortFields GetNthSortField SetNthSortField DeleteNthSortField GetNGroupSortFields GetNthGroupSortField SetNthGroupSortField DeleteNthGroupSortField Sort fields are accessed by an index that ranges from o to GetNSortFields 1 GetNthSortField returns the value of the n th sort field in a pre allocated st ringBuffer The following fragment prints all the sort fields in a report int nFields job GetNSortFields for int i 0 i lt nFields itt StringBuffer sortBuffer new StringBuffer 128 job GetNthSortField i sortBuffer System out printin Sort field i sortBuffer Parallel Crystal D eveloper s Manual 77 Version 2 4 Revised 5 27 00 Sections and Groups The following group of methods allows you to access the sectio
208. f Not IsObject Report Then ReportError Cannot open report file amp ReportPath End If End If If bOK Then L5 Report ExportToHTML OutputPath If Err Number lt gt 0 Then ReportError Cannot export report to amp OutputPath End If End If If bOK Then Y 16 Response write lt br gt lt br gt lt b gt Report generated in amp _ OutputPath amp lt b gt End If If IsObject PCREApp Then sees Eee PCREApp DisconnectFromReportServer End If Set PCREApp Nothing T8 gt lt BODY gt lt HTML gt Example 5 5 Each numbered paragraph below corresponds to the same numbered code statement 1 This line appears at the start of most ASP pages It identifies VBScript as the server side scripting language for the whole page 2 The text between the lt cENTER gt and lt ceNTER gt tags forms the title for the response 3 Lines of VBScript are distinguished from HTML by being enclosed in lt s and gt brackets Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 m 10 11 12 The procedure ReportError is responsible for composing an error message and embedding it in the response This is done by the call to the write method of the built in object Response Each call to write appends a line to the response returned to the browser This line sets a Boolean variable box to False and Clears the built in error indicator called Err box is used to contr
209. f instanceof ICRApplication ICRApplication appObject ICRApplication iref msg appObject getLastErrorString else if iref instanceof ICRReport ICRReport rptObject ICRReport iref msg rptObject getLastErrorString System out printin PCRE Error msg Notice that we have to use Java s runtime type operator instanceof to check whether the given iret is a reference to IcRApplication OF ICRReport Unfortunately the types ICRApplication and IcRReport are not related by inheritance so we cannot use a shared definition of the getLastErrorString method Neither can we use the COM QueryInterface method since it is hidden from us by the Visual J interface to COM B Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 In order to use ReportError the PostScript example must be modified as follows public static void main String args Variant none new Variant none noParam ICRApplication app null try app ICRApplication new CRApplication app ConnectToReportServer example host com ICRReport report ICRReport app OpenReport C MobileApps pcre SampleReports Box rpt none try report PrintOut none none none none none none catch ComFailExceptione ReportError report e app DisconnectFromReportServer catch ComFailException e ReportError app e A simila
210. f the parameter types result codes and functionality B Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 ICRApplication ICRApplication is the custom interface exposed by the root Application O bject CRApplication The methods and properties are listed in T able 6 1 They control access to the Report Server and its report files and allow Report Server and Global O ptions object to be created Errors returned from the Report Server are accessed through the LastErrorCode and LastErrorString properties The Application O bject is created from the crapplication Class constructor Methods Custom Properties Navigation ConnectToReportServer AutomaticLoadBalancing ReportServers DisconnectFromReportServer RetrieveMod ServerSettings OSAgentAddress Options OpenReport Server LogOnServer LogOffServer astErrorCode CanClose aastErrorString ParallelPrintReport ConvertPSTOPDF ClearError Table 6 1 Interface acquisition Dim app As ICRApplication report As ICRReport Set app New CRApplication Method and property calls app ConnectToReportServer butterfly acme com Set report app OpenReport C SampleReports Box rpt if Err Number lt gt 0 Then sgBox Err Description amp amp app LastErrorString End If Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 B ICRGlobalOptions ICRGlobalOptio
211. face and use Parallel Crystal then you can use DOR 8 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 6 I don t use any data objects all my data exists in a database However I like the other aspects of DOR access control database connection pooling can I still use DOR Yes In fact if your database will return data in a manner compliant with either java sql ResultSet or DO RD ataSet interfaces then using D OR will be very easy for you 7 Can I use DOR to report on real time data DOR can be used to create a report on a snapshot of a real time data source This means that the data in the report will only change if you generate the report again 8 Does DOR have any underlying depencies on environment or data source As long as you can use Parallel Crystal in your environment and you can use the interface to describe and provide access to your data source then you can use DOR Parallel Crystal D eveloper s Manual 89 Version 2 4 Revised 5 27 00 Datatype Mapping Reference Crystal DORDataSet java sql ResultSet Currency CURRENCY java sql Types DOUBLE Boolean BOOLEAN java sql Types BIT Date DATE java sql Types DATE java sql Types TIME java sql Types TIMESTAMP Decimal DOUBLE java sql Types FLOA java sql Types REAL java sql Types DO
212. fice Report options MailMessage Here is your Box Office Report amp _ Chr 13 amp Chr 10 report Export report PrintOut ICRReportOptions ICRReport Options is the custom interface exposed by the ReportO ptions O bject The methods and properties are listed in Table 6 27 They provide access to a variety of option settings that may be set for the current report A ReportO ptions O bject is obtained from the options property of the parent Report O bject Methods Custom Properties Navigation Properties CaseInsensitiveSQLData ConvertDateTimeTyp ConvertNullFieldToDefault MorePrintEngineErrorMessages SaveDataWithReport SaveSummariesWithReport TranslateDosMemos TranslateDosStrings UselIndexForSpeed VerifyOnEveryPrint Parent Report Application Table 6 27 Interface acquisition Dim options As ICRReportOptions Set options report Options Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Method and property calls options VerifyOnEveryPrint False options UseIndexForSpeed Tru ICRFormulaFieldDefinition s ICRFormulaFieldDefinitions is the collection interface exposed by the FormulaFieldD efinitions Collection O bject The methods and properties are listed in Table 6 28 on page 208 A FormulaFieldD efinitions Collection O bject is obtained from the FormulaFields property of the Report O bject Each item in the collection is a
213. follows class IUnknown public STDMETHOD QueryInterface REFIId riid void ppvObject 0 STDMETHOD_ ULONG AddRef 0 STDMETHOD_ ULONG Release 0 Parallel Crystal D eveloper s Manual 122 Version 2 4 Revised 5 27 00 This abstract class definition is packaged in a header file that is used by both the COM class providing the implementation of the three interface methods and the clients that call these methods This means that both the client and the implementation class work with the same C definition of the interface that in turn means that the access code compiled for the client will be consistent with the v table compiled for the implementation An interface that is implemented in this way is called a custom interface Custom interfaces are very efficient because both the client and server sides can be compiled to code However the vtable layout is fixed at compile time and this constrains the interface to maintain a fixed set of methods with fixed parameter types Clients that rely on statically typed interfaces are called early bound clients It is clear that interpreted languages such as VBScript cannot access CO M objects using a custom interface Firstly the interpreter cannot understand the C or C header files that are normally produced from the ID L interface definition Secondly the Microsoft IDL compiler that produces these header files cannot produce an equivalent VBSc
214. for C and languages supporting C style function linkage It offers the original C interface to the customization API and an object oriented interface that is similar to the Java package It also includes additional classes for connection management error reporting and recovery e The Parallel Crystal ActiveX Client provides a COM compliant interface to Microsoft development tools such as Visual Basic Visual Basic Scripting Edition Visual J and Visual C This is achieved through the PCRE Automation Server that presents the customization API as a hierarchy of COM automation objects These client packages are arranged in a layered architecture that allows for upwards extension The arrangement of these layers is shown in Figure 1 7 Activex Clients CA Clients Java Clients VB VBScript u C Web AS Java Apps and M App App Client Applets Component Proprietry C i a i i Java Layer gt i Framework H Beans PCRE Active i work jji Automation Paaa e eea ene a eee Server PORE C Client PCRE Java Client Framework Framework Language Layer PCRE ANSI API PCRE Java API C Client Stubs Java Client Stubs CORBA Layer CORBA IDL tor PORE Customization IDL Figure 1 7 Parallel Crystal D eveloper s Manual 25 Version 2 4 Revised 5 27 00 Corba Layer The CORBA Layer consists of acommon CORBA IDL interface for the PCRE Customization API that is shared by all clients Internally the interface is incorporated i
215. format Example 8 2 illustrates a simple C client that outputs a version of the Boxoffice report to PDF It is in fact identical to Example 8 1 with the exception of the single line highlighted include lt icstrenm h gt include lt pcre h gt Ld Te void main int argc char argv PCREAppClient client example host com Ife try client Connect Ll 3x PCREEngine engine client OpenEngine A PCREJob job 5 Engine gt OpenJob C MobileApps PCRE SampleReports Box rpt job gt OutputToPDF C MobileApps PCRE SampleOutputs Box pdf NULL 6 job gt Start EVs job gt Close 8 cout lt lt PDF report generated lt lt endl 9 engine gt Close 10 catch PCREError amp error yy a error Report 12 Example 8 2 Parallel Crystal D eveloper s Manual 238 Version 2 4 Revised 5 27 00 Once again notice that line 6 is formatted to preserve readability Splitting a string across physical line boundaries is illegal in C A PDF report is generated by calling the output Toppr method of the pcrevob class and supplying the name of the output file as an argument The PD F document is generated by starting the print job at Step 7 and is stored in the file C MobileApps PCRE SampleOutput Box pdf In order to display the file you must have access to a PDF viewer such as Adobe s Acrobat Reader
216. g fe V3 despatch events return true Example 2 4 Each numbered paragraph below corresponds to the same numbered code statement 1 Java applets differ fundamentally from the Java applications because they are effectively part of the user interface provided by your browser This means that your applet must use one of the Java User Interface toolkits in order to present its output Simple interfaces can be constructed using the Java Abstract Windowing Toolkit AWT but for commercial quality interfaces your are more likely to require the new Java Foundation Classes 2 You must build your applet by extending the appiet class from java applet Consequently you must import this package Parallel Crystal D eveloper s Manual 42 Version 2 4 Revised 5 27 00 You must import the com mobileapps pcre package to access the Parallel Crystal Java client classes The PCREApp1et Class must be declared as a sub class of java applet Applet This provides access to the start stop init and destroy methods and allows you to override them The pcreappiet Class must implement the pcreconsole interface We ll explain this in more detail below but basically it allows the error reporting facilities within the PCRE package to be adapted to your user interface PCRE applet clients must declare and create an instance of the pcrEappletClient class This class adapts the PCRE client to the rather restricted Java Sandbox i
217. g PCREGateway Properties from C Accessing PCREServer Properties from C 258 GC Client Configuration issie irere aoao a ETNE RNEER TEE SETENE E ESTEEN TAL aI ana Naa eae aaa ETEE AETS 259 Accessing PCREGateway Properties from C ossiciosiisiresisir it iin tE ETE NEE a i 261 Accessing PCREServer Properties from C F CONnMECHNE CECEN Seese i s E EiT E EERIE EEE EEEE OEE REEERE EERE Disconnecting CR CIENS oonan aE rE EAEE EEAS VEE oto uvedasasagucacto ubdugusveuwsecsssaducasspuneecesseducd sti elessenseaed Connecting C Clients Disconnecting C Clients Report Generation for CHF Chents oiie siii ea E ES EEE AAE EENE aaa TAG E A aa 272 Accessing Report Engines and Print Jobs 272 Customizing Print Jobs 0 0 eee 274 Print Job Execution is Print JobDetail Sins tho oN ate A Sa AAA O ISTRA ER I E EAE erie E AS AEREE REA Print JOD OTAD 11N EEEE EAA TE E OA EE A E E Formula Manipulation X Parameter Field and Stored Procedure Manipulation cccescssscssesseeseesecseceseeseesecsecececeeaeeseesecseeeeeeaeeeceaeeaeesecaeeeeeeaeeaeeaeeneeeeeeee 281 DataBase Table Maniptalat otis ssis scicrroci orisii nerta nis aT REES EEEE NI EEPE ATE ES AN RE ER E EA A 282 SQL Queries i Sort Field Mamipw lation sissies sssssosesaxesasavevavesssasasasavavevevssasiscescevaxesavavtvisssdaacsvavsaaccessvancenssssavsvasuvavcaspdeandyasavavsaavieaxdsssdsacoraasansszeatates 283 Sections ANG GLOUPS soa cssenceccascvosvenccusevaascvosveassnsaveusceeteve
218. ge import statement The Visual J compiler includes the Java Trust Lib directory on its search path so it should locate these classes automatically If you have moved the trust Lib directory then you may need to adjust your Visual Studio O ption Settings accordingly 2 The com ms com package contains additional CO M support classes A number of Automation Server methods require arguments to be supplied as values of a universal type called vartanr and this is done using methods of the variant support class 3 A number of methods in the Automation Server have optional arguments that are designed to work with Visual Basic Unfortunately you cannot mark a method parameter as optional in Java and so you must supply the missing values by passing a Variant that has been initialized with the noparam method In the example we create a single missing value called none and use it whenever the method expects an optional argument 4 The root application interface is acquired by creating an instance of the CRApplication Class and then casting to the tcrapplication interface The wrapper Classes force you to use this casting idiom and will throw an exception if you try to call the methods of the crapplication Class directly 5 The client is connected to the Report Server on host example host com This method will throw an exception if this host name is wrong or the Report Server is not running and control will transfer to Step 9 6 The refere
219. gine Parallel Crystal D eveloper s Manual 16 Version 2 4 Revised 5 27 00 PCRE extensions and enhancements include e Provide access to the customization API for the Java programming language e Enable reports to be produced directly in Adobe s Portable Document Format PD F e Enable access to the customization API for networked clients e Provide an adaptation of the API for web related technologies such as Microsoft Active Server Pages ASP e Secure performance enhancements on multi processor architectures The customization API provided by the Report Engine contains over a hundred functions that provide management facilities for print jobs database access report formats and report destinations report layout data record selection formula manipulation and error reporting The API is expressed in the following language related ways e Asaset of ANSI C function declarations that can be called from a C program or any other programming language that supports C style function linkage e Asaset of packaged Java classes which can be invoked from Java applications or applets e AsaC class library which can be called from C applications e AsaMicrosoft COM Automation Server which can be accessed from CO M enabled clients such as Visual Basic Visual Basic Script JScript Visual C and Visual J If you are aC programmer or are familiar with the original Seagate Crystal Report Engine you will find everything you need
220. gram It may just be apparent that it is stored internally as an attribute or property of the Java pcrEJob Class Since Parallel Crystal uses CO RBA IIOP to transmit the arguments and results of API calls to and from the server it follows that Parallel Crystal client program must be able to talk CORBA While this is true of the C C and Java programming languages it is not the case for important Windows development tools such as Visual Basic and Delphi In these cases Parallel Crystal clients are provided with an ActiveX Automation Server that provides a bridge between ActiveX and CORBA technologies The Automation Server exposes the API functions through an object hierarchy that is oriented particularly to the requirements of object based scripting languages such as Visual Basic However more conventional programming languages may use the same interface as long as they conform to the Microsoft Active X specification Naturally this includes Microsoft Visual C and Visual J Parallel Crystal and Web Application Servers Recent developments on the World Wide Web have led to the emergence of a new kind of server called a Web Application Server WebAS Web Application Servers aim to provide very large numbers of browser based clients with facilities to access corporate data Most of them incorporate rapid application development tools that allow the data to be extracted and presented in the form of dynamically composed web pages W
221. gt At this stage we could spend a long time customising the report run on the basis of interactions with the end user but the simplest thing to do is just to run the report unchanged Parallel Crystal D eveloper s Manual 318 Version 2 4 Revised 5 27 00 There are a variety of output formats To produce HTML code Report ExportToHTML c temp out html lt Check for Errors gt Normally outputs should be directed into the Web Server area so that the end user can be given access via an URL to see the results in the browser ExportToHtml isa MAS invention which makes a number of API calls to the Report Engine on your behalf to set up an Export structure appropriate for HTML and to run the report So if there is any reason that the report cannot run successfully on the Report Server this method call is going to fail Check that the report is safe by first running it in the Seagate D esigner on the report server The only other common problem is to supply an illegal file name for the HTML which produces the misleading error message D isk full from a system dll Finally we need to close the Report Engine disconnect from the Report Engine machine and free the Automation Server objects This is all done for you in a single call App DisconnectFromReportServer This call e Closes any open jobs e Closes the Report Engine e Shuts down your PCREServer process on the Report Server e Closes the CORBA network connectio
222. have a Report Server connection you use the ICRApplication OpenReport method to return an ICRReport interface and then use its methods to generate your report As you acquire interfaces the Automation Server generates a tree of object instances You must remember to release the interfaces whenever you are finished with them so that the tree can be systematically dismantled 1 Don Box Essential CO M Addison Wesley 1998 ISBN 0 201 63446 5 Parallel Crystal D eveloper s Manual 127 Version 2 4 Revised 5 27 00 Example 5 1 illustrates the essential steps to produce a PostScript report Certain details have been omitted for a first reading include lt pcreauto h gt int main HRI LG hr if ESULT hr RApplication pApp int argc char ar NU ColInitialize NULL FAILED hr return 0 try hr if FAIL throw Connec ED CRI CoCreateInstance CLSID_CRApplication hr Error Cann to report s gv LL NULL CLSCTX_INPROC_SERVER ITID_ICRApplication 1 2 Th 3 4 IIS reinterpret_cast lt void gt amp pApp ot create PCRE CLver CRStr host flea acme com hr pApp gt ConnectToReportServer host if FAILED hr thro Open a report IDispatch pDispatch ICRReport pReport w CRError pApp NULL NULL 6 Automation Server CRStr
223. he value of the n th sort field is returned by cetNthsortField in a string that you must subsequently release with c1oba1Free The following fragment prints all the sort fields in a report int nFields job gt GetNSortFields j for int i 0 i lt nFields i char name short direction job gt GetNthSortField i name amp direction cout lt lt Sort field lt lt i lt lt lt lt name lt lt lt lt direction lt lt endl GlobalFree name Sections and Groups The following group of methods allows you to access the sections and groups within your report GetNSections GetNGroups GetGroupCondition SetGroupCondition GetSectionCode Sections are accessed by an index that ranges from o to GetNSections 1 The type of a section is retrieved by Get SectionCode and the condition associated with a group is retrieved as a string accompanied by two scalars identifying the condition and its direction The following fragment returns the group conditions for all sections in a report int nSections job gt GetNSections for int i 0 i lt nSections i char field short condition direction int section job gt GetSectionCode i job gt GetGroupCondition section field condition direction Process condition GlobalFree field Parallel Crystal D eveloper s Manual 283 Version 2 4 Revised 5 27 00 Area and Section Formatting The following gro
224. he wizard generates a text file called C WINNT4 0 Java TrustLib cpemas1 summary txt which holds a text description of the methods and their parameters 1 The contents of this section apply to Visual J Version 1 1 or later with Visual Studio 5 or later Parallel Crystal D eveloper s Manual 145 Version 2 4 Revised 5 27 00 Java Type Library Wizard Select items to be converted 4 Application Performance Explorer Pool Manager Application Performance Explorer Queue Manager Application Performance Explorer Server Manager Application Performance Explorer Service Application Performance Explorer Worker Application Performance Explorer Worker Provider Application Performance Explorer Standard Interfaces cicomwrp 1 0 Type Library cpemas1 1 0 Type Library Crystal Data Object Crystal Report 7 ActiveX Designer Design Time Library In Crystal Report 7 Active Designer Run Time Library Crystal Report Control Crystal Report Control obsolete 1 0 Crystal Report Control obsolete 4 5 LiCrystal Report Control obsolete E x Location Figure 5 2 Cancel se Here is an extract from the file that shows how the root tcrapplication interface is expressed in Java public interface ICRApplication extends com ms com IUnknown Get properties public abstract sh
225. he Automation Server In each case the caller must be able to handle exceptions raised when the Automation Server methods return a CO M error Visual C caller must handle _com_error s void RunSample _bstr_t host _bstr_t report ICRApplicationPtr pApp __uuidof CRApplication pApp gt ConnectToReportServer host ICRServer pConfig static_cast lt ICRServer gt pApp gt ServerSettings _bstr_t inputPath pConfig gt SampleReportDir report rpt _bstr_t outputPath pConfig gt WebServerDir report html pApp gt RetrieveMode TRUE ICRReport pReport static_cast lt ICRReport gt pApp gt OpenReport inputPath pReport gt ExportToHTML outputPath pConfig gt Release Must release ICRServer pReport gt Release Must release ICRReport pApp gt DisconnectFromReportServer pApp gt Release Must release ICRApplication Visual Basic caller must have an On Error handler Sub RunSample ByVal host As String ByVal report As String Dim pApp As ICRApplication pReport As ICRReport Dim pConfig As ICRServer Dim inputPath As String outputPath As String Set pApp New CRApplication pApp ConnectToReportServer host Set pConfig pApp ServerSettings inputPath pConfig SampleReportDir amp report amp rpt outputPath pConfig WebServerDir amp report amp html pApp RetrieveMode Tru Set pReport pApp OpenReport inputPath
226. he IIS Web Server then you can return a hyperlink to the report so that the Web Browser can finally display it Report retrieval is enabled for automation clients by setting the ret rieveMode property of the rcRapplication interface to True You must do this after you have called Connect ToReport Server Then when you set the output format with a call such as Export ToHTML OF Output ToPDF you must specify a path name for the file on the diat s machine rather than the Report Server machine Visual C ICRApplicationPtr pApp __uuidof CRApplication 7I iy pApp gt ConnectToReportServer example host com 2 pApp gt RetrieveMode TRUE Lh Sis C SampleReports Box rpt on the Report Server machine ICRReport pReport A static_cast lt ICRReport gt pApp gt OpenReport C SampleReports Box rpt C MyReports Box pdf on the client machine pReport gt OutputToPDF C MyReports Box pdf ff 5a pReport gt Release Must release ICRReport pApp gt DisconnectFromReportServer 6 pApp gt Release Must release ICRApplication Visual Basic Dim pApp As ICRApplication pReport As ICRReport Set pApp New CRApplication ame pApp ConnectToReportServer example host com Pe pApp RetrieveMode True Sue C SampleReports Box rpt on the Report Server machine Set pReport pApp OpenReport C SampleReports Box rpt 4 C MyReports Box pdf on the client machine
227. he Parallel Crystal Report Engine Server running on the Report Server machine Table 9 3 summarizes the property methods which allow you to supply or retrieve a string of command line arguments to be used when the G ateway Server starts the Report Engine Server Property Name Purpose setArguments Supply the command line argument string getArguments Return the command line argument string addArgument Append a command line argument to the string Table 9 3 The command line arguments for the Report Engine Server are summarized in Table 9 4 Argument Purpose verbose Switch on Report Engine Server tracing This is useful if you are running Parallel Crystal on the desktop and you wish to see full tracing in the Report Engine s G UI folder directory Specify the Report Engine Server working directory This lets you specify report files with path names relative to this directory client name Specify the name of the client If you are running Parallel Crystal on the desktop the Report Engine will display this string to help you identify your server amongst many Table 9 4 Parallel Crystal D evelopers Manual 258 Version 2 4 Revised 5 27 00 Here are two example fragments that specify the same arguments in equivalent ways Supply arguments in a single call try PCREServer server client getServer server gt setArguments client toby folder C Monthl
228. he Web Server root directory The Parallel Crystal installation normally includes a G ateK eeper IO R file at C MobileApps pcre ior gatekeeper ior So you can copy this file into your applet code base directory or include an ORBgatekeeperIor parameter of the form lt param name ORBgatekeeperIOR value http www acme com MobileApps pcre ior gatekeeper ior gt Client ORB Management Each application or applet client uses an O bject Request Broker to manage the CO RBA connections to the various PCRE servers running on the Report Server When you create an application with multiple clients possibly running in multiple threads a single instance of the ORB is shared by all clients This strategy conserves resources and can be important if the clients are deployed in a long running Java Virtual Machine Suppose you create an application with multiple client instances such as PCREAppConsole console new PCREApplicationConsole j PCREApplicationClient clientl new PCREApplicationClient console hostl argsl propsl clientl Connect PCREApplicationClient client2 new PCREApplicationClient console host2 args2 props2 client2 Connect 1 Multi threaded clients are discussed in the section at the end of this chapter Parallel Crystal D eveloper s Manual 65 Version 2 4 Revised 5 27 00 If client1 is instantiated first its O RB is created using any relevant values supplied in argsi and pro
229. he member formatType S Set to UxFNet scape2Type format Options is used as an auxiliary data structure that holds the name of HTML output file and a pointer to this variable is saved in the options member variable formatOptions The void Cast is required because options can be used to store details of many other report formats that supply different auxiliary formatting structures The second group of statements diskOptions fileName strcpy options destinationDLLName u2ddisk dl1 options destinationType UXDDiskType options destinationOptions void amp diskOptions enters information in options to save the report file to disk The field dest inationDLLName is set to the name of a destination DLL called u2ddisk dii and the field destinat ionType is set to uxpDDi skType diskOptions is used as an auxiliary data structure that can be used to specify the name of the disk file However in this case the name is already stored in the formatoptions structure so the fileName member of diskoptions is set to the empty string The options data structure initialized in Step 3 is passed to the Print Engine in the call PEExportTo If the parameters are incorrect the function will return a Farse result and control will transfer to the close_job label after the error message has been printed The report is generated when the pestartPrintJob is called If the report contains graphical images the HTML fo
230. he next chapter entitled Using the Java Client Package describes the Java client interface in detail In both sections we use a sample Crystal report file called Box rpt that is distributed with Parallel Crystal in the sampleReports directory of the product installation The file already incorporates its own data so the report may be produced directly without the need to connect to a database 1 We describe how to use Visual J ActiveX COM extensions with Parallel Crystal in Chapter 5 Parallel Crystal D eveloper s Manual 29 Version 2 4 Revised 5 27 00 Using Parallel Crystal in a Java Application In this section we describe how to construct a Java application program that generates a report as a PostScript PDF or HTML document For simplicity we assume that the Java program has a simple character based user interface O nce you ve mastered the material in this chapter you can refer to the section entitled Print Job Outputs in Chapter 3 to learn how to generate reports in other formats Before looking at some example code we need to clarify details of a typical Parallel Crystal rr ee PCRE Report Server installation PCRE Server PCRE Server PCRE Server Parallel Crystal Report Server Machine PCRE Java PCRE Java PCRE Java Application Application Application Client Client Client Client Machine Client Machine Client Machine Figure 2 1 2 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5
231. he output roppr method first If problems arise try Export ToppF that generates PD F using Acrobat Distiller If problems persist and you have access to Crystal Reports D esigner load your report into the D esigner and check for errors in the report itself When the Report Engine Server receives a call to Export To it saves the name of the PD F output file Once the report has been generated in PostScript the Report Engine starts the conversion to PDF by running a Parallel Crystal command line utility called pdfdistiller This program performs the following functions e It checks the input PostScript file exists e It checks that the output PD F file can be created e It runs Adobe Acrobat Distiller in an invisible desktop e It prevents multiple versions of Acrobat Distiller from running concurrently e It deletes the PostScript input file after conversion If you experience problems in generating PD F using export Toppr check with your System Administrator that Acrobat Distiller has been installed correctly on your Report Server The pdfdistiller utility searches the registry for the Acrobat Distiller s executable and expects to find an entry in HKLM Software Microsoft Windows CurrentVersion AppPaths AcroDist exe Parallel Crystal D eveloper s Manual 28 Version 2 4 Revised 5 27 00 If the entry no longer points to a valid file pafdistilier will not be able to execute the AcroDist program If there is no registry entr
232. hen Parallel Crystal is integrated with a WebAS we get an n tier application similar to that shown in Figure 1 5 1 CORBA stands for Common Object Request Broker Architecture 2 TIOP stands for Internet Inter O RB Protocol Parallel Crystal D eveloper s Manual 21 Version 2 4 Revised 5 27 00 Wieb Application Server d EEA client browser client browser client browser client browser Figure 1 5 The core of the WebAS is a high performance highly scalable web server that is capable of scheduling requests for web pages In many cases however the pages served are the result of dynamic composition performed by additional back office tools invoked by the web server These may include CGI Perl Scripts server side plugins Java servlets or Microsoft Active Server Pages The usual sequence of actions begins when the client submits a query using an HTTP request The web server receives the request and dispatches it to the correct server side utility The utility analyzes the request accesses a database and composes an HT ML page to display the data and returns the page to the web server In the final step the web server returns the page to the client When Parallel Crystal is integrated with a WebAS it provides report customization production and retrieval facilities that are accessible via your web browser Because of the limited capabilities of the HTTP protocol Parallel Crystal clients do not attempt to make customization API
233. hm which is normally configured by the System Administrator The two algorithms most commonly used are called load factor and round robin The load factor algorithm compares all the Report Servers in the group and returns the one with the smallest load The round robin algorithm simply cycles through all Report Servers in turn and selects the next one in the sequence When you use manual mode the Load Balancer returns a vector of Report Server hosts together with their load factors You use the vector to make your own selection and then reset the host within the client When you call the client s connect method you are connected to your chosen Report Server The Load Balancer is dynamically updated whenever a G ateway starts or stops a Report Engine Server when a new G ateway is started or when an existing G ateway is stopped This means that it adjusts to servers started by clients using the Load Balancing Service and to servers started by clients who connected directly to a Report Server without using load balancing Using the Load Balancer from C C clients use the Load Balancer in automatic mode by calling the connect method with the argument true For example PCREAppClient client 1 try client Connect TRUE ff Ds make method calls catch PCREError amp e e Report 3 Each numbered paragraph below corresponds to the same numbered code statement 1 A PCREAppCl
234. ication Object reference is returned by creating an instance of the crapplication co class and storing the result in an object reference variable declared with type icRapplication Dim app As ICRApplication Set app New CRApplication If you use VBScript with ASP the Application O bject reference is returned by calling CreateO bject and specifying the Automation Server s PROGID Dim app Set app Server CreateObject MAS CRApplication 1 Each of these calls relies on the Automation Server D LL being installed on the client machine and appropriate information set up in the registry as follows The Automation Server D LL is called cpemas1 a11 and is normally located in the installation directory c MobileApps pcre bin The full path name of the DLL is entered into your client machine registry at installation time by the command regsvr32 cpemasl dll When the command is executed it creates the following entries in the registry hive HK EY_CLASSES_ROOT MAS CRApplication CurVer MAS CRApplication 1 CLSID 81B34614 B2B4 11D1 8C38 000000000000 MAS CRApplication 1 CLSID 81B34614 B2B4 11D1 8C38 000000000000 81B34614 B2B4 11D1 8C38 000000000000 InprocServer32 C MobileApps pcre bin cpemas1 dll ThreadingModel Apartment ProgID MAS CRApplication 1 VersionIndependentProgID MAS CRApplication Parallel Crystal D eveloper s Manual 181 Version 2 4 Revised 5 27 00 The ext
235. ice provider and its corresponding server Prior to connection it is possible to configure some service providers by invoking their set property methods Frequently this is used to control operation of the client s Report Engine Server Parallel Crystal D eveloper s Manual 255 Version 2 4 Revised 5 27 00 The four service providers contained by the client classes are shown in Table 9 1 Service Provider Get Property Purpose PC Parallel Crystal PCREGat eway getGateway Access to PC Gateway Server PCREServer get Server Access PC Report Engine Server PCREConfigServer getConfigServer Access to PC Configuration Server PCRECustomServer getCustomServer Access to PC Custom Server Table 9 1 The function of each is summarized as follows e ThepcreGateway Class provides client access to the Parallel Crystal G ateway Server The G ateway is responsible for allocating PCRE Report Engine Servers to clients e Thepcreserver Class provides client access to the Parallel Crystal Report Engine Server The Report Engine Server provides the report customization and generation functionality that you use to generate reports e ThepcreconfigServer Class provides client access to the Parallel Crystal Configuration Server The Configuration Server provides information about the current configuration of your Parallel Crystal installation e ThepcrecustomServer Class provides special purpose functionality to clie
236. ient null try client PCREAppletClient client Connect PCREEngin ngine client OpenEngine engine Close catch PCREError e e Report client Quit This short lived connection might be preferable if it is appropriate to perform all report processing before constructing the applet s user interface Another possibility is to establish the connection in init or start and then hold it open until the browser is terminated Parallel Crystal D eveloper s Manual 49 Version 2 4 Revised 5 27 00 This can be accomplished with the framework in Example 2 5 on page 50 public class PCREApplet extends java lang Applet implements PCREConsole private PCREAppletClient client public void init try client new PCREAppletClient public void start empty public void stop empty public destroy client Quit Example 2 5 In this example the client and its connection to the Report Server persist over the calls to start and stop This means that the browser can navigate to other pages and continue to access the report on return to the applet page This framework may be appropriate if the interaction with the Report Server takes place in a context that requires the display of several HT ML pages or even several different applets A Java applet is run within your browser under the control of a Security M
237. ient is declared without specifying a host name Ultimately the Load Balancer determines the host 2 Connect is called with the value rruz which uses the Load Balancer in automatic mode The Load Balancer returns the Report Server host determined by its current selection algorithm and the client is connected to that host Parallel Crystal D eveloper s Manual 302 Version 2 4 Revised 5 27 00 3 If there are no Report Servers available to the Load Balancer then the connect call will throw a pcREServerError exception and at Step 3 the message Server error Load Balancer failure no available Report Servers will be printed To use the Load Balancer in manual mode you call the RequestReportServerList method that returns a vector of candidate hosts Y ou apply your own selection procedure to the vector and then call the client s ResetReportServerHost method passing the selected vector element Finally you call connect to connect the client to the Report Server The following example shows a typical code fragment PCREAppClient client try PCREReportServerInfo servers 100 int number 100 int nElements nElements client RequestReportServerList servers number PCREReportServeriInfo host MySelection servers number client ResetReportServerHost host client Connect method calls catch PCREError amp e Report Each element of the arr
238. igServer Visual Basic Property Get ServerSettings As Object Visual J public java lang Object getServerSettings Typically you get a reference to the tcrserver interface as follows Visual C ICRServer config config static_cast lt ICRServer gt app gt ServerSettings Visual Basic Dim config As ICRServer Set config app ServerSettings VBScript Dim config Set config app ServerSettings Visual Java ICRServer config config ICRServer app getServerSettings The rcrserver interface contains a series of read only properties that return strings containing configuration dependent information about the Report Server These properties are declared as follows Parallel Crystal D eveloper s Manual 212 Version 2 4 Revised 5 27 00 Visual C HRESULT get_Version BSTR pDirPath HRESULT get_HostName BSTR pDirPath HRESULT get_HostAddress BSTR pDirPath HRESULT get_InstallDir BSTR pDirPath HRESULT get_SampleReportDir BSTR pDirPath HRESULT get_SampleOutputDir BSTR pDirPath HRESULT get_WebServerDir BSTR pDirPath Visual Basic Property Ge Property Ge Property Ge Property Ge Property Ge Property Ge Version As String HostName As String HostAddress As String InstallDir As String SampleReportDir As String SampleOutputDir As String Property G Visual java lang java lang j
239. ike http www acme com SampleReports sample asp 2 The IIS web server loads the sample asp page and begins to compose the reply During processing it encounters the lt s and s gt brackets and loads the VBScript interpreter to process the script 3 As the script executes it loads the PCRE Automation Server and then connects to the Report Server The Report Server host can be specified in an HTML form sent with the document request in Step 1 4 Customization calls to the Automation Server s methods are transmitted to the Report Server If the report uses a database the Report Engine Server will make an independent connection to the D atabase Server 5 If the report has been generated in HTML or PDF and the Report Server does not run on the same machine as the Web Server then the report should be retrieved to the Web Server 6 Once the report has been generated the script is disconnected from the Report Server and a reply is delivered to the browser Typically it contains a message confirming that the report was generated together with a possible hyperlink to the report document Version 2 4 Revised 5 27 00 1 Client navigates to 6 Report retrieved to client ASP page browser Client browser HTTP 2 Web server receives HTTP request and runs ASP page 3 Customization calle made fram VBScript weithin 5 Report retrieved to web Server ASP page Web Server IGF 4 Customization calls execute
240. ile contains all the classes in the PCRE package and all the classes in the Inprise VisiBroker CO RBA framework When you install the Java Client the installation procedure automatically modifies your CLASSPATH environment variable to include an entry for the pcrEjavaclient jar file Subsequently the following problems can arise e Older versions of the Java compiler such as that included with Microsoft Visual J Version 1 1 cannot read jar files In this case you must unpack the jar file into a set of directories containing the individual class files For example if you use the command jar xvf C MobileApps pcre classes PCREjavaclient jar this will unpack all the class files into a directory hierarchy rooted in the classes sub directory of c MobileApps pcre Parallel Crystal D eveloper s Manual 109 Version 2 4 Revised 5 27 00 You must then reset your CLASSPATH to 7C MobileApps pcre classes so that the compiler can locate the class files in their new location Some Java Project D evelopment Environments maintain their own classpath independently of the user s environment If this is the case then you need to ensure that you keep your development project classpath consistent with your environment CLASSPATH You may be using the Parallel Crystal Java Client in conjunction with a Web Application Server Many of the WebAS environments also use Java CORBA products and some use the Inprise VisiBroker product in com
241. ilure The following simple example shows how to retrieve the host name of the Report Server and the version number of the Parallel Crystal installation PEHANDLE config Connect to unspecified report server EInitRemote NULL As Obtain configuration info har host 256 version 256 onfig PEGetConfigServer j EGetPCREVersion config version sizeof version EGetPCREHostName config host sizeof host FO EF Oe QPS Other API calls Disconnect client PEUninitialize 8 Version 2 4 Revised 5 27 00 The configuration strings are truncated if the buffer you provide is not large enough Method Purpose PC Parallel Crystal PEGetPC REVersion Returns the PCRE version string PEGetPC REHostName Returns the PCRE Report Server host name PEGetPC REHostAddress Returns the PCRE Report Server host address PEGetPC REInstallDir Returns the PCRE installation root directory PEGetPC RESampleReportDir Returns the PCRE sample reports directory PEGetPC RESampleOutputDir Returns the PCRE sample output directory PEGetPC REPCREWebServerDir Returns the Web Server s root directory PEGetPC REGatewayName Returns the name of the PCRE G ateway Server PEGetPC REConfigInfo Returns an agg
242. ime is no longer valid If you experience the timeout problem use the setwait method of the pcrEGateway service provider to increase the time in seconds Parallel Crystal D eveloper s Manual 110 Version 2 4 Revised 5 27 00 For example PCREApplicationClient client null try client new PCREApplicationClient host Wait for up to 120 secs for connection client getGateway setWait 120 client Connect API Calls avi Ey catch PCREError e e Report client Quit Y ou tried to connect using the Load Balancer but the Load Balancer could not locate any Report Servers In this case it is possible that the Report Servers were not configured to use the Load Balancer Service or there is an inconsistency in the way the Load Balancer Service has been configured You should get your System Administrator to check the current Load Balancer configuration The PCREG ateway makes its initial reference available at a specific port This port is determined in the following ways It first looks for an environment variable called IO RPort that has been set to the desired port N ote If the environment variable is present but its value can t be converted to a number then it is ignored and the process continues to the next step Next it looks for a registry entry called IO RPort see your System Administrator to setup or change this value that isa DWORD registry value containing th
243. indicates that an attempt to connect the client to the G ateway on the nominated host failed This usually means one of two things e The Report Server host name you supplied in the pcreappclient constructor call was invalid e The host name was valid but Parallel Crystal was not running on the Report Server when the connection was attempted A second commonly occurring error is to specify an invalid name for the report file For example suppose that instead of line 5 you typed PCREJob job engine gt OpenJob C MobileApps PCRE SampleReports junk rpt When this statement is executed the report pathname will be supplied to the Print Engine DLL that will fail because the report file does not exist In this case the D LL returns an exception to the client that causes control to transfer to the handler at line 12 This statement prints the following line to the standard output stream PCRE API error invalid file name The PCRE API error prefix indicates that the error was raised by the Print Engine D LL Generally this is an indication that something went wrong in a Print Engine API call and the most likely cause is an invalid argument value Unfortunately the error messages returned by the Print Engine D LL are quite terse O ne way to compensate for this is to enclose smaller groups of calls within separate try catch blocks so that you can be sure which call failed A third error that is easy to make is to fo
244. ing Client Web Server side Setup Problems ccsccssescessesseeseceeceseeseeseesecsecseceseeaeesecsecseceeeeaeeeeaeeaesaeeeeeeeeaeeaeeaeeneeats 324 Parallel Crystal D eveloper s Manual 7 Version 2 4 Revised 5 27 00 Chapter 1 Introducing Parallel Crystal This manual describes how to use D ynalivery s Parallel Crystal Report Server to customize and generate reports prepared with the Seagate Crystal Reports D esigner The introductory chapter is divided into three sections e The section entitled Using this Manual describes the layout and composition of this manual including a Roadmap to help locate the information you need e The section entitled G etting Help describes how to get technical assistance how you should report bugs and how you can get the latest versions of Parallel Crystal from our web site e The section entitled Why Use Parallel Crystal includes a detailed description of the design and operation of the Parallel Crystal product as well as an explanation of some basic report processing concepts N ote It is highly recommended that you read most of this introductory chapter It ex plains many of the basic concepts of the design and operation of the Parallel Crystal produc Parallel Crystal D eveloper s Manual 9 Version 2 4 Revised 5 27 00 Using this Manual This User Manual is intended to get you started with Parallel Crystal in particular to get that all important first report produced Th
245. ion i amp info PCREJob subReport engine gt OpenSubreport job info name customize sub report subReport gt CloseSubreport Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 PESubreport Info struct containing the name of the sub report You can open a job for R Graph Manipulation The following group of methods allows you to manipulate graphs and charts in your report GetGraphType GetGraphData GetGraphText GetGraphOptions SetGraphType SetGraphData SetGraphText SetGraphOptions Graphs are located by a section code returned by the Get Sect ionCode method Each section can contain multiple graphs that are numbered from 0 upwards The GetGraphOptions GetGraphData and GetGraphText methods respectively return the required information in the structs pEcraphOptions PEGraphDataInfo and PEGraphText Info GetGraphType retums an integer valued type code identifying the type of the graph The corresponding set methods use the same structs when resetting a property of the graph The following fragment shows how the formatting options and title string for a graph in the n th section are retrieved and reset int section job gt GetSectionCode n PCREGraphOptions options job gt GetGraphOptions section 0 amp options options verticalBars TRUE job gt SetGraphOptions section 0 amp options PEGraphTextInfo info job gt GetGraphText section 0 amp
246. ion Server describes how clients can access information that describes the way in which their Parallel Crystal installation has been configured The section entitled Parallel Crystal Load Balancer describes how Report Server hosts can be allocated to clients to ensure the load is balanced evenly or systematically across a group of servers The section entitled Multi Threaded Clients describes how to construct multi threaded clients that can perform report generation tasks concurrently The Parallel Crystal C classes do not form a general purpose class library like the Microsoft Foundation Classes Their primary purpose is to expose the Report Engine API in amanner that is convenient for C programmers and to provide a small number of additional facilities that assist in integration of report processing into your application In the sections that follow the various facilities provided by the Library are described for both C and C For full details of each class its methods and its equivalent C interface you should consult the online Reference D ocumentation Parallel Crystal D eveloper s Manual 250 Version 2 4 Revised 5 27 00 Parallel Crystal Clients In this section we describe how to create Parallel Crystal clients using C or C Each client API uses a set of service provider classes to access a corresponding set of Report Server programs that provide report generation load balancing and connection management servi
247. ion and control will transfer to the handler at line 12 This statement will then print the following line PCRE Gateway error Connect cannot connect client to Gateway Service on host bad host name The error message indicates that an attempt to connect the client to the G ateway on the nominated host failed This error message usually indicates one of a number of things including e The Report Server host name you supplied in the pcrEApplication Client constructor call was invalid e The host name was valid but Parallel Crystal was not running on the Report Server when the connection was attempted e The Gateway wasn t broadcasting its initial reference on the default or provided port e There was some other communication problem Parallel Crystal D eveloper s Manual 35 Version 2 4 Revised 5 27 00 Invalid Report File Name The second most common error in programming a simple client is to specify an invalid name for the report file For example suppose that instead of line 5 you typed PCREJob job engine OpenJob C MobileApps PCRE SampleReports junk rpt When this statement is executed the report pathname will be supplied to the Print Engine DLL that will subsequently fail because the report file does not exist In this case the DLL returns an exception to the client that causes control to transfer to the handler at line 12 This statement prints the following line to the standard outpu
248. irst argument of the PCREAppClient constructor If you omit the argument an instance of the character based PCREAppConsole Will be installed by default For example the fragment PCREAppClient client example3 host com try client Connect try API method calls catch PCREAPIError el el Report catch PCREError amp e2 e2 Report will report all errors using the default PcREAppConsole If your application has a graphical user interface the PcREAppConso1e class is inappropriate and you will require a graphical implementation of the pcreconsole interface A typical implementation might take the following form Parallel Crystal D eveloper s Manual 293 Version 2 4 Revised 5 27 00 class GUIConsole public PCREConsole enum TEXT_MSG SERVER_MSG GATEWAY_MSG CLIENT_MSG FATAL_MSG INTERNAL _MSG public PCREConsole interface methods void PCREOutputMsg const char msg MessageBox TEXT_MSG msg void PCREAPIErrorMsg const PCREError amp e LogMsg e getText void PCREServerErrorMsg const PCREError e essageBox SERVER_MSG e getText void PCREGatewayErrorMsg const PCREError amp e essageBox GATEWAY_MSG e getText void PCREClientErrorMsg const PCREError amp e essageBox CLIENT
249. is called if you terminate your browser while displaying the page containing the applet It should therefore terminate the Report Engine and destroy the existing applet client 13 Between calls to start and stop the applet client must be accessed via the user interface For example if we have a button labeled Run then we could invoke the RunJob method through an action handler as follows public boolean action Event evt Object arg if Run equals arg RunJob return true else if Quit equals arg QuitClient return true The underlying Java A bstract Windowing Toolkit will invoke this method whenever buttons labeled Run and Quit that are part of the user interface contained within the applet Panel are pressed By trapping and dispatching events as shown we can invoke the methods within the applet that perform the report customization and generation This framework provides a transient connection to a Report Server We ll provide a little more implementation detail and then describe how it might be adapted to support a persistent server connection Let s look first at a typical implementation of start that creates an applet client and connects it to the server private method ConnectClient try client new PCREAppletClient this this client Connect UIDisplayText Connect to report server catch PCREError error error Report client null
250. is manual is essentially divided into three parts or paths that separately describe how you may use Parallel Crystal Use the following RoadMap to navigate to the correct path in the manual RoadMap Y our route through the roadmap depends upon your client development environment or on a prior selection of web technology Try to match your requirements against the following queries Are you using a pure Java client development environment such as the Sun JDK or are you using a Java oriented Web Application Server Or are you using Visual J but without the ActiveX COM extensions If so Go to Chapter 2 entitled G etting Started with Java Clients to get started Go to Chapter 3 entitled Using the Java Client Package to learn more about using the Parallel Crystal Java Client package to write client applications and applets Go to Chapter 4 entitled Trouble Shooting Java Clients to learn how to solve the problems that occur most often in Java clients Are you using any of the following Microsoft products for development Active Server Pages with VBScript or Jscript or Visual Basic Or do you wish to use the ActiveX COM extensions provided in Visual C or Visual J If so Go to Chapter 5 entitled G etting Started with ActiveX Clients to get started Go to Chapter 6 entitled Using the PCRE Automation Server to learn more about the customization interface provided by the PCRE Automation Server Go to Chapter 7 entitled
251. isual J and by smart pointers in Visual C VBScript and JScript clients are constrained by these languages to use the dispatch interface Structurally a report is modeled as a set of collections of various kinds In the diagram above each interface post fixed with a s represents a collection All collection interfaces provide a standard set of properties and methods that allow you to iterate through their members Special consideration is given to Visual Basic that has a ror Each Statement that is explicitly designed to work with automation collections 5 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 All automation clients acquire a reference to the root rcRapplication interface first of all and then call openreport to create one or more Report Objects on named report files Thereafter the methods and properties of the rcrReport interface are used to customize and generate each of the reports Roughly speaking acquiring an rcRApplication reference corresponds to opening a Print Engine on the Report Server and calling OpenReport corresponds to opening a print job In the remaining sections we provide top level descriptions of each Automation O bject and its interface The properties are divided into those that allow you to customize the report and those that allow you to navigate through the object hierarchy Each interface definition is accompanied by code samples that show how to acquire the interface h
252. itaan es eA EE ENEE EAEEREN EAEE EEEE EKE E EERS EREE EECA ESEVE VOEE AR Using the Load Balancer from C a Using the Load Balancer from Gii eidooier n ai E EENE EERE TRS AE E AE ENE ER E A A Multithreaded CU ents so srin caste cates an E AEAEE IR AENEA IR ARENOR AARNA AARNA OSN 305 Chapter 10 Trouble Shooting C C ClientS esesesesesesesescococororororosoeosorororososorosoeeeeseeeseoeororororororororororoseeeeeereeeeseseseeeeeseeeoeorororororose 309 Problems with Client Connections cess se ar cscs R E eG an R EO een TEER 309 Problems with Export Formats Problems WNP DE Seea EA AREAN E A EAAS ARE E ES A AEE EE REAREN Problems with the Report SErvera rire eienen oE E EEE ETEN EEE AERE EAEE A EE AERE ONEEK EES EENE 313 Appendix A Simple ASP VBScript Tutorial cccsssssssssssssssssssssesssssesscssssessssesscssseaseseassssessssessessssesesssssesssssesessesesscssssasssseseasees 315 OVET EW E casein EAE AE NEA EEDEN EEEN EVEEK EARE AAAA DEAE AENA A A E AEEA PETE AAA EEAO PATENS REER Ein 315 Understariding a Simiple Pro Stari is serenite iiir Kadi an iei i te Sii VEETEE EERTE Er KE vasadeonebedebeusavevevnvoaceseoasseed 317 Embedding the Program in a Working ASP Page cscsscssssceeseeseeseeseesecsecseceseseesecsecsecsecsaceseeaeesecsecsececeaeeaecseeeeeaeeaeeaeeaeeaeeaes 320 Setting Up Your First ASP Application 322 In the Event of a Failure 323 Diagnosing Server side Setup Problems 324 Diagnos
253. ith various Microsoft tools Parallel Crystal D eveloper s Manual 324 Version 2 4 Revised 5 27 00
254. ividual D atabase Parameter Objects are obtained by the 1tem method that takes an index or argument identifying the parameter required Visual Basic clients may iterate through all items with the For Each statement that calls the Newznum property to create an enumeration of D atabase Parameter O bjects Methods Custom Properties Navigation Item Count Parent _NewEnum Report Application Table 6 21 ICRDat aBaseParameter S the custom interface exposed by each D atabase Parameter Object in the collection The methods and properties are listed in Table 6 22 They provide access to the name type and value attributes of the parameter Parallel Crystal D eveloper s Manual 202 Version 2 4 Revised 5 27 00 Methods Custom Properties Navigation Name Parent Type Report Value Application Table 6 22 Interface acquisition Dim dbpmc As ICRDataBaseParameters Dim param As ICRDataBaseParameter Set dbpmc dbase Parameters Set param dbpmc Item 1 Set param dbpmc 2 Iteration collection For Each param in dbase Parameters If param Type crDateField Then Dim val As String val param Value End If Next ICRPrintingStatus ICRPrintingStatus s the custom interface exposed by the PrintingStatus O bject The methods and properties are listed in Table 6 23 They provide access to the number of records and pages printed and the overall print status for the parent r
255. l D eveloper s Manual 174 Version 2 4 Revised 5 27 00 The most important thing to remember when using the Report Retrieval feature is that the path name for the generated report must be specified on the Web Server and not on the Report Server If you want the file to be directly available for browsing then you must retrieve it to a file store location within the Web Server s root directory Generating PDF and PostScript Reports with ASP The rcrReport interface provides several methods that make it easy for you to generate reports in other formats In each case the call to Export TouTML in Step 15 is replaced with one that generates the report in the appropriate format In particular e To generate a report in PDF and save the results replace the call to Export TOHTML with the following call to output ToPDF report OutputToPDF OutputPath When the method returns the PD F report will be stored in the file specified by the OutputPath You should use a paf subscript to identify PD F files e To generate a report and send the results to a printer replace the call to Export ToHTML with the following call to printout report PrintOut When the method returns the report has been generated but printing will not necessarily be complete e To generate a report in PostScript and save it in a file replace the call to Export ToHTML with the following call to output Tops report OutputToPS OutputPath The report will
256. l in the section entitled Parallel Crystal Configuration Server Interface acquisition Dim config As ICRServer Set config app ServerSettings Property calls Dim webDir As String reportDir As String outputDir As String webDir config WebServerDir reportDir config SampleReportDir outputDir config SampleOutputDir ICRReport ICRReport is the custom interface exposed by the Report O bject The methods and properties are listed in Table 6 4 The methods allow you to control the selection of the output format and trigger report generation The custom properties allow report attributes to be modified The navigation properties allow child objects to be created and the parent and application objects to be located A Report O bject is obtained by calling the OpenReport method of the Application Object or by calling the opensubreport method of the Report O bject Methods Custom Properties Navigation Properties OutputToPs Title ParameterFields OutputToPDF HasSavedData SummaryFields NumberOfGroup FormulaFields ExportToPDF PrintDate Options ExportToHTML GroupSelectionFormula ExportOptions ExportToExcel RecordSelectionFormula PrinterInfo ExportTowWord SQLQueryString ReportSummaryInfo Export PrintingStatus ProgressDialogEnabled DataBase OpenSubreport ParameterPromptingEnabled RecordSortFields DiscardSavedData Sections Save sastErrorCode Areas uastErrorString
257. le c MyReports Box pdf when the print job is started by the call to pestartPrintJob Parallel Crystal D eveloper s Manual 297 Version 2 4 Revised 5 27 00 Parallel Crystal Configuration Server When Parallel Crystal is installed a number of directories are created with sample Crystal Reports and demonstration materials In order to help you locate path names for these directories Parallel Crystal incorporates a Configuration Server that returns configuration and installation dependent information to the client Configuration Server for C Clients C clients access the Configuration Server through the methods of the PCREConfigServer Service provider class that are summarized in Table 9 13 Y our client is automatically connected to the Configuration Server when you call the connect method Thereafter you can get a reference to the pcrEconfigServer Class by calling the client s getConfigServer method Method Purpose getPCREVersion Returns the Parallel Crystal version string getPCREHostName Returns the Parallel Crystal Report Server host name getPCREHostAddress Returns the Parallel Crystal Report Server host address getPCREInstallDir Returns the Parallel Crystal installation root directory getSampleReportDir Returns the Parallel Crystal sample reports directory getSampleOutputDir Returns the Parallel Crystal sample output directory getPCREWebServerDi
258. le the various errors reported by Parallel Crystal The section entitled Console Interface describes the abstract console interface that error handling classes use to display error messages The section entitled Parallel Crystal Configuration Server describes how clients can access information that describes the way in which their Parallel Crystal installation has been configured The section entitled Parallel Crystal Load Balancer describes how Report Server hosts can be allocated to clients to ensure the load is balanced evenly or systematically across a group of servers The section entitled Multi threaded Clients describes how to construct multi threaded clients that can perform report generation tasks concurrently The section entitled Web Application Servers discusses a number of issues that arise when using the Parallel Crystal Java client from a Web A pplication Server The Parallel Crystal Java Client package is not a general purpose class library in the sense of for example the Java Foundation Classes Its primary purpose is to expose the Report Engine API in amanner that is convenient for Java Programmers and to provide a small number of additional facilities that assist in integrating report processing into your application The sections that follow provide general information on how to use the PCRE Java Client For full details of each class and its methods you should consult the online Reference Documentation Pa
259. lease resources held in the Report Server Parallel Crystal D eveloper s Manual 33 Version 2 4 Revised 5 27 00 10 11 12 13 This statement is executed if all previous statements executed without error If an error occurs in an API call the corresponding method of the PCREEngine or PCREJob Class will throw an exception and control will transfer to the exception handler at statement 11 When we are done with all print jobs the print engine is closed with a call to its close method The exception handler is executed if an expception occurs in any of the preceding method calls We will discuss exception handling in detail in Chapter 3 but for the present its sufficient to note that by specifying the base class pcREError in the handler we can trap all exception classes raised by the Java Client In this simple example we choose to handle the exception by displaying the exception on the screen The last statement calls the ouit method and disconnects the client from the Report Server You should call this method whenever you are finished with generating reports since it will automatically terminate the Report Engine and free up resources in the Server Here it is included in a finally clause so that it is sure to be called before the program completes This example may be summarized as a set of rules that you can use to develop your own applications Access the Parallel Crystal Java Client
260. led on the client and Report Server are identical You should get your System Administrator to check for possible version incompatibility problems Problems with PDF This section describes the problems with PD F production using the D ynalivery library and Acrobat Distiller In Chapter 9 we described how to generate PD F reports using the C output ToPDF and ExportTo methods and the corresponding API functions in C The output ToPDF method generates PD F directly using the D ynalivery PDF Library The export To method produces PD F indirectly by generating a PostScript version of the report first and then converting this to PD F using a utility from Adobe called Acrobat Distiller The problems that may arise when generating PD F therefore depend upon which of the methods you have called Parallel Crystal D eveloper s Manual 31 Version 2 4 Revised 5 27 00 The following problems are known to occur when using the Dynalivery PDF Library with OutputToPDF 1 You cannot currently generate linearized PD F for per page retrieval to a browser Future versions of the library may support this feature 2 OLE objects are rendered as bitmaps When using the zoom in feature in A crobat Reader bitmaps may look grainy 3 Reports with overlapped images may not render correctly 4 Reports designed with fonts other than True Type fonts may not render correctly In general we recommend you try to generate PD F using the
261. lied client Connect catch PCREError error error Report In each case the argument string is supplied when the Report Engine Server is launched by the G ateway This implies that you must know the values of the arguments before you issue the connect Call In the section Parallel Crystal Configuration Server we ll show how you can change the Report Engine Server s working folder after you have established the Report Server connection Parallel Crystal D eveloper s Manual 59 Version 2 4 Revised 5 27 00 Parallel Crystal D eveloper s Manual Application Client Connection When you construct a Parallel Crystal Java application you must first create a PCREApplicationClient Class then connect it to the Report Server and then access the client s Report Engine Typically this requires a code sequence such as PCREApplicationClient client null try client new PCREApplicationClient example host com client Connect PCREEngin ngine client OpenEngine j engine Close catch PCREError e e Report client Quit When the Connect method is called the following events occur in sequence e The client tries to establish a connection to a G ateway running on the Report Server The Report Server is identified by the host name or host address supplied in the PCREApplicationClient constructor call or in a call to the pcrEGateway
262. lient threads can generate reports concurrently The following example illustrates a multi threaded client application in which five clients are concurrently connected to different Report Servers Each client is created within a worker thread that executes independently of the others Notice that the lifetime of the thread embraces the lifetime of the client that in turn embraces the lifetime of the Report Engine Server static const int NTHREADS 5 static char hosts NTHREADS beetle flea mantis butterfly grub DWORD WINAPI ClientWorker LPVOID l1pArg LPTSTR host reinterpret_cast lt LPTSTR gt 1pArg PCREAppClient client host try client Connect PCREEngine engine client OpenEngine j BPI calls engine gt Close catch PCREError amp e e Report return PCRE_FAIL Worker completed return PCRE_OK void main int argc char argv HANDLE handles NTHREADS Parallel Crystal D eveloper s Manual 305 Version 2 4 Revised 5 27 00 Create client worker threads for int i 0 i lt NTHREADS i DWORD dwThreadId handles i CreateThread NULL 0 ClientWorker LPVOID hosts i 0 amp dwThreadId if handles i NULL cout lt lt CreateThread lt lt GetLastError lt lt endl Wait for worker threads to finish WaitForMultipleObjects NTHRE
263. limited filtering to advanced data objects which filter perform access control contain not only stored data but also calculated data and pass the data through a layer of complex business logic D ata O bject Reporting allows users to specifiy these data objects as their data sources for their reports Using design time utilities a report file that contains only the data access information is created Then using the Crystal Reports D esigner the empty report file is used as a base to add fields charts graphs text etc to the report design At run time the data object is specified as the data source for the report template and the report is generated Preparation Creating a report for use with D ata O bject Reporting is much like designing a report for any other Parallel Crystal application The result is still a Crystal Report template rpt file that is used by Parallel Crystal The main difference is that the DOR report accesses data differently Therefore the creation of the report template for DOR requires some special consideration extra analysis and utility work as well as some system preparation Preparation for Creating DOR Reports includes e Installing DOR to RPT Utility e Analyzing the D ata Source Steps for Creating a DOR Report e Run DOR Design Utility to generate inital D OR file e Run DOR to RPT Utility to create a Crystal Reports template RPT from the DOR file e Final formatting using Crystal Reports
264. lls gI Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 DOR Design Utility The DOR Design Utility is included in the PCREJavaClientjar This utility creates a DOR file by evaluating a Data Object Running this utility results in the creation of aD OR file in the format that the DOR to RPT Utility expects The correct syntax for creating a DOR File from a Data O bject is listed below Running the DOR Design Utility From a command line java com mobileapps dor DorDesignUtil ResultSetClassName MetaDataClassName OutputFileName Running as java com mobileapps dor D orD esignUtil Will cause a usage message to be printed to the screen From within a program example code DORDataSetImpl dorDS DORDataSetImpl DorDesignUtil dUtil new DorDesignUtil DUtil outputDorFile DorDataSet dorDS filename DOR to RPT Utility The DOR to RPT Utility creates a Crystal Reports rpt template by evaluating the DOR dor file created by the DOR Design Utility Running the DOR to RPT Utility results in a pre loaded skeleton of a report template with links to the D ata O bject but whose formatting should be completed using the Crystal Reports Designer The instructions for the use of this utility are listed below Note This utility is installed by running the program MobileApps Pcre DataObjectReporting DORReportUtility exe Parallel Crystal D eveloper s Manual 85 Version 2 4 Revised 5 27 00 Run
265. located to your client by the G ateway and is terminated when you disconnect from the Report Server Report Engine Servers are not shared amongst clients e The Configuration Server allows clients to retrieve configuration information about their Parallel Crystal installation For example you can obtain the name of the directory containing sample reports or the name of the directory to contain sample output All clients share access to a single Configuration Server e The Load Balancer Server ensures that client connections to multiple Report Servers are allocated in a way that spreads the report processing load evenly across the available server machines Clients share access to the Load Balancer Server e The Custom Server is an extension to the Report Engine Server that is used to provide custom extensions to the Parallel Crystal Report Server Parallel Crystal D eveloper s Manual 53 Version 2 4 Revised 5 27 00 Parallel Crystal Java clients gain access to these servers through the PCREApplicationClient and PCREAppletClient Classes When you call the client class s connect method it will establish a connection first to the G ateway server and then to the allocated Report Engine Server When you call the Disconnect method these connections are broken and the Report Engine Server is terminated The client classes also provide access to the service providers that can be used to fine tune the connection to the Gateway and control the opera
266. logy called Automation and through extensions to the language interpreters that hide the low level COM API We ll describe Automation in the next section If you re curious to see how COM programming works from Visual Basic or Visual J take a look at the examples in the next section Microsoft COM Automation Automation is an extension to COM that allows component objects to be accessed by weakly typed scripting languages The term derives from OLE Automation which was originally designed to allow COM objects to be controlled by macros written in Visual Basic The macros act as a kind of glue allowing object based applications to be controlled by scripts performing complex tasks O bjects exposed in this way are called automation objects and their clients are called automation controllers To understand the need for automation we need to compare the way in which compiled and interpreted clients access an object through its interface The methods and properties of a COM object are specified by an interface written in Microsoft Interface D efinition Language ID L For example an abbreviated form of the tunknown interface is interface IUnknown HRESULT QueryInterface in REFIID riid fout iid_is riid void ppvObject ULONG AddRef ULONG Release In order to use this with compiled clients the interface is translated into an equivalent C orC header file For example the C version is as
267. lue Alternatively you can use the command line argument orBagent Adar as follows MyApp exe ORBAgentAddr 123 456 654 321 You must collect this argument in the argv vector passed to main and pass this in a call to the pcREAppClient Constructor or PEInitialize function as shown in the preceding example for orBagentPort Finally the following connection problem can arise with badly configured Domain Name Servers You may find that connections succeed when specifying a host with an IP address but fail when using a domain name If this is the case you should check with your System Administrator that your D NS servers are configured correctly and can handle both forward and reverse lookups Problems with Export Formats In Chapter 9 in the section entitled Print Job Outputs we described how to control the output format of the report with a variety of export formats Two problems can arise with report formats 1 Not all of the formatting D LLs may be available on your Report Server If you experience problems with formats other than HTML or PDF then check with your System Administrator that the corresponding D LL is on your system and accessible to the Report Engine Server through the PATH environment variable 2 Output formats are set with the Export To method of the pcreJob Class The parameters that this method passes across the network are complicated and require that the versions of the Inprise VisiBroker product instal
268. mallest load e Round robin simply cycles through all Report Servers in turn and selects the next one in the sequence Manual Mode When you use manual mode the Load Balancer returns a vector of Report Server hosts together with their load factors You use the vector to make your own selection and then reset the host within the client When you call the client s connect method you are connected to your chosen Report Server The Load Balancer is dynamically updated whenever a G ateway starts or stops a Report Engine Server or when a new Gateway is started or when an existing G ateway is stopped This means that it adjusts to servers started by clients using the Load Balancing Service and to servers started by clients who connected directly to a Report Server without using load balancing Parallel Crystal D eveloper s Manual 103 Version 2 4 Revised 5 27 00 The following example shows you how to use the Load balancer in automatic mode PCREApplicationClient client null try client new PCREApplicationClient LB host com Ef Ex client Connect true LI 2s make method calls catch PCREError e e Report Lies The connection process is completed in the following steps 1 A PCREApplicationClient is specifying a host name for the Load Balancing 2 Connect is Called with the value t rue which activates the Load Balancer in automatic mode The Load Balancer returns the Rep
269. mon with Parallel Crystal If both product installations modify your CLASSPATH you may need to check and reconcile the entries to ensure that your compiler will search the correct directories in the correct order If you need to move your Parallel Crystal installation because of disk space management problems it is best to uninstall and re install the product since this should restore and then re modify your environment CLASSPATH accordingly Of course you may have to modify Project D evelopment CLASSPAT Hs independently Common Problems with Client Connections A call to your client s connect method can fail for a number of reasons Check these common situations first If the problem persists the causes may be more obscure The most common causes of connection failure are You specified a Report Server host in the client constructor call that is invalid either the host name or the IP address is incorrect You specified a correct host name or host address in the client constructor but the Report Server is down or is not running Parallel Crystal Y our client was able to connect to the Report Server but the G ateway could not start a Report Engine Server Perhaps you specified incorrect command line arguments or the machine was so busy that the G ateway timed out before the Server could get started Or perhaps the Parallel Crystal Installation has been moved and the Report Server s executable path name which is configured at install t
270. most important thing to note is the line pinfo currentValueset true If this isn t done the Report Server will seem to hang because the Crystal Engine will display a dialog box on the server asking for the value of the parameter Database Table Manipulation The following group of methods allows you to access database tables within your report GetNTables GetNthTableType GetNthTableLocation SetNthTableLocation GetNthTableSessionInfo GetNthTableLogonInfo SetNthTableLogoninfo TestNthTableConnectivity Tables are accessed by an index value ranging from 0 to GetNTables 1 The following fragment shows how to log the first table onto the database this value tells the server whether or not to try to use this logon information for the other tables in the report boolean propagate true PCRELogOnInfo info job GetNthTableLogOnInfo 0 info Password password job SetNthTableLogOnInfo 0 info propagate If you look at the pcreLogonInfo structure in the API reference you will notice that it has several other fields Here we only set the Password field because the call to GetNthTableLogOnInfo fills in the other fields they are stored with the report The methods cetNthTableSessionInfo and GetNthTableLocat ion use similar helper Classes pcRESessionInfo aNd PCRETableLocat ion to return their results Parallel Crystal D eveloper s Manual 76 Version 2 4 R
271. mportant because postscript is the input to Distiller Users cannot create a postscript file that has more than about 7500 pages in it so long reports using Distiller are not possible Parallel Crystal D eveloper s Manual 27 Version 2 4 Revised 5 27 00 Chapter 2 Getting Started with Java Clients In this chapter we describe how to customize and generate reports using Java You may use any pure Java environment with Parallel Crystal so long as it incorporates a JD K 1 2 x Java Virtual Machine Y ou may also use Microsoft s Visual J environment so long as you don t intend using the ActiveX COM compiler extensions The chapter is divided into two major sections e In the first section entitled Using Parallel Crystal in a Java Application we describe how to build a Parallel Crystal client that runs as a stand alone Java application program The section contains example code fragments that show you how to connect to the Parallel Crystal Report Server and how to make simple customization calls to generate reports formatted as PostScript PD F and HTML documents e In the second section entitled Using Parallel Crystal in a Java Applet we describe how to build a Parallel Crystal client that runs as an applet in a Java enabled web browser You can use any web browser so long as it incorporates a Java 1 1 x Java Virtual Machine Both application and applet clients are constructed using a Java package called com mobileapps pcre T
272. n e Releases the objects from the report object down that have been created directly or indirectly by your script Note that in the nature of COM objects they may not actually be freed and returned to the heap until the object variables declared in your script go out of scope and the script interpreter also releases them However NO use should be made of the objects from report down after the Disconnect call The connection and the report engine are gone In order to perform further report processing you must run the script again or execute another pcreA pp ConnectT oReportServer call which provides you with a new Report Engine and set of objects Remember Parallel Crystal customises and runs a report but the report must be designed and first tested in the Seagate CRW Designer If the report does not run in the Seagate Designer then it is not going to run in Parallel Crystal The Seagate D esigner should be installed on the Report Server and whether you develop the report there or bring in a functioning report from another machine the next step is to check that the report runs on the Report Server machine using the designer Parallel Crystal D eveloper s Manual 319 Version 2 4 Revised 5 27 00 The most common source of problems is the data source not being set up as the report expects on the Report Server Hit the refresh lightning button in the designer to force the report to attempt to use its database settings If there i
273. n which applets are forced to run You must provide an implementation of the pcreconsole interface This interface declares the following seven abstract methods public abstract void PCREOutputMsg String msg public abstract void PCREFatalErrorMsg PCREError error public abstract void PCREInternalErrorMsg PCREError error public abstract void PCREServerErrorMsg PCREError error public abstract void PCREAPIErrorMsg PCREError error public abstract void PCREGatewayErrorMsg PCREError error public abstract void PCREClientErrorMsg PCREError error These methods give you an opportunity to adapt the error reporting requirements of the PCRE package to your user interface For example you may wish to log client Server API and G ateway error messages in a display panel and then continue processing However fatal and internal error messages should probably be treated differently The ecreerror Class is derived from java lang Exception and has property methods called getcode getText and getKind that retum details of the exception If you are not too concerned with the quality of error handling in your applet you can treat all errors in the same way and map the implementation of these methods to a common handler The applet implementation methods contain the core of your applet processing In the example this i
274. n generated in PostScript the Report Engine starts the conversion to PDF by running a Parallel Crystal command line utility called pdfdistiller This program performs the following functions e It checks the input PostScript file exists e It checks that the output PD F file can be created e It runs Adobe Acrobat Distiller in an invisible desktop e It prevents multiple versions of Acrobat Distiller from running concurrently e It deletes the PostScript input file after conversion If you experience problems in generating PD F using Export To check with your System Administrator that A crobat Distiller has been installed correctly on your Report Server The pdfdistiller utility searches the registry for the Acrobat D istiller s executable and expects to find an entry in HKLM Software Microsoft Windows CurrentVersion AppPaths AcroDist exe If the entry no longer points to a valid file pafdistilier will not be able to execute the AcroDist program If there is no registry entry then pdfdistiller will attempt to run a program called acropist and will rely on the System PATH environment variable to locate this program You Can run pdfdistiller manually on the Report Server to check its operation The command line is pdfdistiller command input psfile output pdffile By default the program runs silently and writes its error messages to the Windows NT Event Log You should check this log file before you do anything else
275. n required Visual Basic clients may iterate through all items with the For Each statement that calls the Newznum property to create an enumeration of Section O bjects A Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Methods Custom Properties Navigation Item Count Parent _NewEnum Report Application Table 6 9 ICRSect ion is the custom interface exposed by each Section O bject in the collection The methods and properties are listed in Table 6 10 They provide access to the section s properties and its constituent sub report objects Methods Custom Properties Navigation Height Options Number ReportObjects Width Parent Report Application Table 6 10 Interface acquisition Dim scns As ICRSections section As ICRSection Set scns area Sections Set section scns Item 2 Set section scns 1 Set section scns Item PH Collection iteration For Each section In area Sections section Height 200 twips section Width 200 twips Next Parallel Crystal D eveloper s Manual 195 Version 2 4 Revised 5 27 00 ICRSectionOptions ICRSect ionOptions Is the custom interface exposed by the Section O ptions O bject The methods and properties are listed in Table 6 11 Section O ptions control the layout and formatting of an individual section within an area whereas Area O ptions apply globally to all sections in an area When conflicts occur the Tru
276. n the machine running the PCRE Java client not the PCRE server machine DOR Frequently Asked Questions 1 DOR supports the java sql ResultSet interface through the use of an adapter Does this mean that Data Object Reporting users have to be using a database No Although DOR supports that interface there is no underlying reliance on databases JDBC orODBC We provide support for that interface to make DOR easier to use for JDBC users 2 I use software that can collect data from a variety of sources databases data objects etc into a central data object Can I use DOR Yes As long as you can use the DO RD ataSet interface to describe this central location you can use D OR to report on that information 3 DOR interests me but I need to use one of Parallel Crystal s non Java client libraries C C Active X what can I do With PCRE 2 4 our Automation Server supports Microsoft ADO Recordset objects as a DOR datasource See the Automation Server documentation for additional details 4 I m a SilverStream Weblogic NetDynamics Websphere etc Web Application Server WAS user who uses Parallel Crystal can I use DOR As long as your WAS environment will allow you to create an object that implements the DORDataSet interface and describes your data source you can use D OR with Parallel Crystal 5 Z don t use a Web Application Server can I use DOR DOR has no built in dependencies on WAS s If you can implement the inter
277. n the host mantis acm com Having created an applet client and connected it to a Report Engine we can now use the Engine to produce a report Typically we have to do this in response to input from the user interface so an implementation of the Rungob method that is called when the Run button is pressed is shown below If you compare the code in RunJgob to that in Example 2 3 on page 39 then you ll see that the sequence of calls to produce the HTML formatted report is identical In other words the difference between PCRE applet client programming and PCRE application client programming is the difference between Java applets and applications The PCRE API calls that you make to customize and generate reports remain the same Parallel Crystal D eveloper s Manual 45 Version 2 4 Revised 5 27 00 private void RunJob Check the client is connected if client null UIDisplayText Client not connected return Set success fail indicator boolean ok false try PCREEngin ngine client OpenEngine PCREJob job engine OpenJob C MobileApps PCRE SampleReports Box rpt PCREHTMLUJobExportInfo info new PCREHTMLJobExportInfo C MobileApps PCRE SampleOutputs Box html job ExportTo info job Start job Close UIDisplayText Report generated engine Close ok true catch PCREError error error R
278. n your Report Server If not the connect method will throw a PCREGat eway exception and the connection will fail In the section entitled Parallel Crystal Configuration Server we ll show how you can retrieve the G ateway name from the Report Server rather than hard code it as a literal string Parallel Crystal D eveloper s Manual 266 Version 2 4 Revised 5 27 00 Once aconnection has been established you can retrieve the hosts and names of the Servers as follows PCREAppClient client try client Connect PCREGateway gateway client getGateway PCREServer server client getServer char gatewayHost gateway gt getHost char gatewayName gateway gt getName char serverHost server gt getHost char serverName server gt getName Use report server catch PCREError amp e e Report Remember that it makes no sense to try to set the name and host of a G ateway after you have called connect If you call a set property in these circumstances it will throw a PCREClientError exception Disconnecting C Clients When you are finished with a Parallel Crystal C client you should disconnect it from the Report Server The easiest way to do this is to invoke the pcreappclient destructor on an instance of the class For example void RunReport char host char report PCREAppClient client host
279. name of a Gateway running on your Report Server If not the connect method will throw a PCREGat eway exception and the connection will fail In the section entitled the Parallel Crystal Configuration Server we ll show how you can retrieve the G ateway name from the Report Server rather than hard code it as a literal string Applet Client Connection When you construct a Parallel Crystal Java applet you must first create an instance of the PCREAppletClient class then connect it to a Report Server and then access the client s Report Engine For example PCREAppletClient client null try client new PCREAppletClient example host com client Connect PCREEngin ngine client OpenEngine engine Close catch PCREError e e Report client Quit Parallel Crystal D eveloper s Manual 61 Version 2 4 Revised 5 27 00 The sequence of events that occurs when the connect method is called is e The client tries to establish a connection to a G ateway running on the Report Server If no host name is supplied in a call to the constructor or the PCRE G ateway s setHost method the client will attempt to connect to a G ateway running on the same host as the Web Server e If aconnection to the G ateway is established the client issues a request to the Gateway to start a Report Engine Server on the same host The G ateway executes the request by starting a uniq
280. nce to the rcrreport interface is acquired by calling the ICRApplication OpenReport method and specifying the name of the report file The second parameter is optional and so we pass the missing value none You must cast the result to the rcRReport interface type since you have no direct access to the Report O bject s implementation class 7 The report is generated and sent to the printer by calling the rcrreport Printout method This method takes six optional arguments and so six default missing values are supplied The method returns when the report has been generated 8 Thecall to pisconnectFromReport Server disconnects the client from the Report Server and releases resources at the client You MUST call this method after your report has been generated If you forget resources will be tied up within your client and server machines until your application terminates 9 The methods in the Java classes generated by the Type Library Wizard will raise exceptions if their corresponding COM methods fail The exceptions can be trapped with a catch clause that specifies a comrailException type 10 The error message supplied by the Automation Server can be retrieved with a call to the getMessage method and the COM fail code can be retrieved with the getHResult method Parallel Crystal D eveloper s Manual 148 Version 2 4 Revised 5 27 00 Unfortunately the summary txt file produced by the Type Library Wizard does not include the name
281. nd does not change the pointer value While strictly illegal according to the CO M Specification it nevertheless achieves the conversion without hidden side effects that affect the report object s reference count Parallel Crystal D eveloper s Manual m Version 2 4 Revised 5 27 00 The strictly CO M conformant way of converting from 1pispatch t0 ICRReport is as follows HRESULT hr ICRReport pReport IDispatch pDispatch pApp gt OpenReport name hr pDispatch gt QueryInterface IID_ICRReport void amp pReport pDispatch gt Release The final call to Release releases the 1pispatch interface The tcrreportPtr smart pointer constructor does not perform this call and that is why it was necessary to insert it manually Handling Errors from COM When an error occurs in the Automation Server it stores an error message internally and returns a generic COM error called z_rarzi When you access the Automation Server using bare COM you must test the result of each method call with the macro ratuen If the return code indicates an error you can recover the Automation Server s error message by calling the get_ Last ErrorString property of the rcrapplication and IcRReport interfaces Earlier we showed a helper class called CRError whose constructors re packaged the error message in an exception Unfortunately when you use the Visual C COM support classes the pre packaged _com_error does no
282. nd no knowledge of the implementation details of the object s class e Inorder to use a COM object clients must acquire a reference or pointer to its interface O nce acquired the client is guaranteed that the object provides an implementation of all the methods and properties listed in the interface 5 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 e COM clients neither create nor destroy CO M objects directly Clients cannot create COM objects because data encapsulation means that in general they do not know how much memory to allocate Clients are also not permitted to destroy objects while they are in use e COM objects are implemented by co classes that provide one or more COM interfaces A co class is created by an associated factory class called a class object that is registered with the CO M administration framework CO M co classes have names beginning with a capital C such as crapplication e COM objects monitor their clients using a simple system of reference counts Whenever a client acquires a reference to the interface the count is incremented and whenever the client relinquishes the interface it is obliged to call areiease method which decrements the count The object will delete itself whenever its reference count reaches zero e Reference counts are maintained by a special interface called tunknown that contains three methods called AddRef Release and QueryInterface Clients call addref and
283. ndicates that an attempt to connect the client to the G ateway on the host called bad host name failed This usually means one of two things e The Report Server host name supplied as the second argument to the petnitialize call was invalid e The host name was valid but Parallel Crystal was not running on the Report Server when the connection was attempted A second commonly occurring error is to specify an invalid name for the report file For example suppose that instead of the code in Step 5 in Example 8 4 you typed job PEOpenPrintJob C MobileApps PCRE SampleReports junk rpt When this statement is executed the report file pathname will be supplied in a call to the Print Engine DLL and this will subsequently fail because the report file does not exist In this case the D LL returns an exception to the client that causes PEopenPrintJob to return a negative result When reportError is called it prints the following error message invalid file name Unfortunately many of the messages returned by the Print Engine D LL are very terse In some cases it will help if you pass the name of the API function that failed as an extra argument to ReportError For example if job ReportError PEOpenPrintJob 0 goto close_engine A third error is not specifying the destination for the report In other words once it s generated where do you send it In the simple client Example 8 4 Step
284. ne and if that fails it issues an HTTP request to download the applet from the server machine An applet is downloaded by composing a URL for its class file from a code base and a code name The code base specifies the Web server host and a sub directory of its root directory The code name is the name of the applet class 1 You can specify URLs using the forward slash character Web servers will automatically translate this to a back slash character on Windows based machines Parallel Crystal D eveloper s Manual 62 Version 2 4 Revised 5 27 00 If the HTML page containing the applet was retrieved from http www acme com travel html then the applet s class file will be retrieved from http www acme com TravelApp class If the code attribute of the lt applet gt tag specified the full name com acme apps T ravelA pp then the applet s class file would be retrieved from http www acme com com acme apps TravelApp class Sometimes it is convenient to organize a web server s root directory so that applets and HTML pages are held in different sub directories If this is the case then the code base cannot be deduced from the original document URL and has to be specified using a codebase attribute in the lt applet gt tag So if the TravelA pp class was actually held in the classes sub directory of the Web Server root then an lt applet gt tag with the following form would be required lt applet code Tra
285. nfo that is defined as follows define PE_INFO_NAME LEN 64 define PE_PATH_NAME_LEN 256 As typedef struct PCREConfigInfo char PCREVersion PE_INFO_NAME_LEN har PCREHostName PE_INFO_NAME_LEN har PCREHostAddress PE_INFO_NAME_LEN har PCREInstallDir PE_PATH_NAME_LEN har PCRESampleReportDir PE_PATH har PCRESampleOutputDir PE_PATH har PCREWebServerDir PE_PATH_NAME_LEN har PCREOutputDir PE_PATH_NAME har PCREGatewayName PE_INFO_NAME_LEN char PCREFileServer PE_INFO_NAME PCREConfigInfo D D F zZ QO 2A OQ GQ Notice that you don t need to worry about calling st rFree after get PCREConfigInfo as the strings have been copied into statically allocated character arrays For example PCREAppClient client try client Connect PCREConfigInfo info client getConfigServer gt getPCREConfigInfo amp info use info catch PCREError amp e e Report The Configuration Server returns information that you can use with other service providers The next example shows you how to connect to a Report Server and then set the Report Engine Server s working folder to the sample reports directory Parallel Crystal D eveloper s Manual 299 Version 2 4 Revised 5 27 00 Parallel Crystal
286. ng int Administrative Group close This method will be called by PCRE after retrieving the data from the data object Use this method to close any open connections and fr any resources as necessary next This method advances the row pointer to the next row of data It is assumed that the pointer points to BEFORE the first row when the object is initialized ie PCRE will call next before attempting to retrieve any data When the pointer is past the last row this method should return false Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 General Suggestions for implementing the data interface e Have the data object itself implement the interface This means fewer classes to keep track of but it will mean that the data object will have more methods and could be more complex e Write a data object descriptor for the data object The data object descriptor implements the interface to describe a single data object This means more classes but each class is more specific a data object and its descriptor e Write a generic data object descriptor that can be used to describe any number of data objects Perhaps using Java s reflection capabilities to call get type methods with the data objects This means having fewer data object descriptors to maintain but also means that each data object will have to follow a common pattern Using ResultSet interface The D ORD
287. ngine Server you can create applications in which multiple client threads connect to multiple Report Servers and generate reports concurrently If your client is running on a multi processor machine then concurrency may be real rather than apparent The following example illustrates a multi threaded client application in which 5 clients are concurrently connected to different Report Servers Each client is created within a worker thread that executes independently of the others Notice that the lifetime of the thread embraces the lifetime of the client that in turn embraces the lifetime of the Report Engine Server Parallel Crystal D eveloper s Manual 106 Version 2 4 Revised 5 27 00 class ClientThread extends Thread private String clHost public ClientThread String host clHost host public void run PCREApplicationClient client null try client new PCREApplicationClient client host Connect client thread to host client Connect PCREEngin ngine client OpenEngine j do work engine Close catch PCREError e e Report Disconnect client thread from host client Quit public class ThreadExample private static final int NTHREADS 5 private static String hosts beetle flea mantis butterfly grub public static void main String args ClientThread clients new
288. ning the DOR to RPT Utility 1 From the Start Menu choose gt gt Programs gt gt Pardllel Crystal gt gt DOR Report Utility The DOR to RPT Utility dialog box appears MAS DOR te RPT Utility Bie Hap EDO Recordsi DOR Fe HIF inpak Pile Meares The DOR Input file is the file created using the DOR Design Utility The Output File Name is the name of the report file to be created If the data source is an ADO Recordset choose the ADO Recordset tab MAS DOR te RPT Utility Bie Hap ERa 00 F If you are using D OR with the Automation Server then your data source is likely an ADO Recordset Enter the Source string and the Connection text string like you would in the code to create such a recordset in the appropriate boxes The Output File Name is the name of the report file to be created Hitting the G enerate RPT File button will cause a blank report skelton to be created and a dialog box similar to the one below will be shown Final Report Design Final formatting of the report template should be completed using the Crystal Reports Designer Parallel Crystal D eveloper s Manual 86 Version 2 4 Revised 5 27 00 Running a DOR Report Running the DOR Report Template This code snippet instantiates a data object that implements the DO RD ataSet interface connects to a report server sets the data object as the data source for the report generates the report as PDF and disconnects from the report engine
289. ning the Parallel Crystal IO P G ateK eeper on the Web Server machine can solve both problems The G ateK eeper acts as a staging post taking incoming IO P requests and forwarding them to Report Server on the specified host The G ateK eeper also handles protocol restrictions by a technique called HTTP tunneling in which the client CORBA framework packages each IIO P request in an HTTP wrapper When the G ateK eeper receives the HTTP request it removes the wrapper and forwards the original IIO P request to the server Normally the CORBA framework tries to connect direct to the G ateway using IIOP If the request fails the framework will then re try using the IIO P GateK eeper and if necessary switching to HTTP protocol In order to do this you must first have the GateK eeper running on your Web Server and you must tell the CORBA framework how to find it When the G ateK eeper is started it creates a file called gatekeeper ior whose contents allow the client CORBA framework to establish a G ateK eeper connection The CORBA framework retrieves the IOR file to the client by using a URL that you specify as an additional applet parameter lt param name ORBgatekeeperIOR value http www acme com classes gatekeeper ior gt The URL looks very similar to the applet code base discussed above and if you omit the ORBgat ekeeperIor parameter the CORBA framework will attempt to retrieve the IOR file from the applet s code base directory by default
290. ns 3 ReportError job goto close_job if PEStartPrintJob job TRUE A ReportError job goto close_job printf Report generated n close_job if PECloseJob job ReportError job close_engine PECloseEngine j close_app PEUninitialize Example 8 8 The additions required to generate HTML are quite complex and have been highlighted in bold font in the example 1 The three declarations PEExportOptions options UXFHTML30ptions formatOptions UXDDiskOptions diskOptions introduce data structures that are used with the PEExportTo Call in Step 4 In order to generate an HTML report we must inform the Print Engine that the output of the print job is to be formatted in HTML and stored on disk file The formatoptions and diskOptions structures are combined with other information in the variable options and this is passed to the Print Engine in Step 4 Parallel Crystal D eveloper s Manual 247 Version 2 4 Revised 5 27 00 The first group of statements formatOptions fileName C MobileApps PCRE SampleOutputs Box htm1 strcpy options formatDLLName u2fhtml dll options formatType UXFNetscape2Type options formatOptions void amp formatOptions enters information into the opt ions variable to generate the report in HTML The member formatDLLName is set to the name of a formatting D LL called u2fhtml d1i and t
291. ns PCREPDFOutputOptions Figure 9 1 The C classes are arranged in the functional groups shown in Figure 9 1 Within each group base classes are marked with an asterisk Parallel Crystal D eveloper s Manual 249 Version 2 4 Revised 5 27 00 The chapter is divided into the following sections The section entitled Parallel Crystal Clients describes how to use the pcREAppClient class and in particular how to specify the connection to your Report Server The section entitled Report G eneration for C Clients describes how to use the PCREEngine and PCREJob Classes to perform report customization and generation The methods of the pcrevob class are arranged in groups and illustrated with sample code fragments The section entitled Report G eneration for C Clients describes the equivalent facilities for C clients When a report is stored in a file it may be necessary to retrieve the file from the Report Server back to the machine hosting the client The section entitled Report Retrieval describes facilities for automatic return of reports to the client The section entitled Error Recovery describes how to use the error handling classes to detect and handle the various errors reported by Parallel Crystal The section entitled Console Interface describes the abstract console interface that error handling classes use to display error messages The section entitled Parallel Crystal Configurat
292. ns and groups within your report GetNSections GetNGroups GetGroupCondition SetGroupCondition Get Sect ionCode Sections are accessed by an index that ranges from o to GetNSections 1 The type of a section is retrieved by Get Sect ionCode and the condition associated with a group is retrieved as the value of a pcREGroupCondit ion helper class The following fragment returns the group conditions for all sections in a report int nSections job GetNSections for int i 0 i lt nSections i int section job GetSectionCode i PCREGroupCondition cond job GetGroupCondition section Process condition Area and Section Formatting The following group of methods allows you to adjust the areas and sections in your report GetSectionFormat SetSectionFormat GetAreaFormat SetAreaFormat GetMinimumSectionHeight SetMinimumSectionHeight GetSectionFormatFormula SetSectionFormatFormula GetAreaFormatFormula SetAreaFormatFormula Sections and areas are accessed by a section code returned by the Get Sect ionCode method The formatting details of each section or area are specified in the attributes of a PCRESectionOptions helper class The following fragment shows how the formatting of the n th section is retrieved and reset int section job GetSectionCode n PCRESectionOptions options job GetSectionFormat section adjust formatting options job SetSe
293. ns is the custom interface exposed by the Global O ptions O bject CRGlobalOptions The methods and properties are listed in Table 6 2 They control the settings of various global options on the Application O bject A Global O ptions O bject is obtained from the opt ions property of the Application O bject Methods Custom Properties Navigation Properties MatchLogOnInfo Parent MorePrintEngineErrorMessages Application Table 6 2 Interface acquisition Dim options As ICRGlobalOptions Set options app Options Property calls options MorePrintEngineErrorMessages Fals options MatchLogOnInfo False iCRServer ICRServer is the custom interface exposed by the Configuration Server O bject The methods and properties are listed in Table 6 3 A Configuration Server O bject is obtained from the serverSett ings property of the Application Object Methods Custom Properties Navigation Properties Version HostName HostAddress InstallDir SampleReportDir SampleOutputDir WebServerDir OutputDir GatewayName DORTempDir Table 6 3 B Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 The Configuration Server O bject allows the client to request configuration information from the Report Server such as the Parallel Crystal Version and the installation path names for several important directories The Configuration Server is described in more detai
294. nterface The Parallel Crystal Java client package does not make any internal assumptions about the nature of your application In particular it does not know whether output messages will be sent to a character stream or displayed in a G UI Consequently the reporting facilities incorporated into the error handling classes output error messages using an abstract application console interface Y ou can adapt this interface to your application by providing an appropriate implementation class The Parallel Crystal Application Console interface is called pcrEconsole It contains seven methods that allow a message to be displayed according to the kind of information it conveys For example fatal error messages might be accompanied with a sound effect whereas A PI errors might simply be written to a text window Y ou provide the appropriate implementation of these methods in your implementation class If your application uses a simple character based user interface then the pre packaged PCREApplicat ionConsole Class may be adequate for your requirements You must install your application console by supplying it as the first argument of the PCREApplicationClient constructor If you omit the argument an instance of the character based PCREApplocationConsole will be installed by default For example PCREApplicationClient client null try client new PCREApplicationClient example host com client Connect try
295. nto each client as a set of stub functions which marshal the arguments for the various API calls and send them across the network to the Report Server The stubs also retrieve results and handle errors when they occur Neither the stubs nor the IDL are normally exposed to users That means that you do not have to bea CORBA programmer to use Parallel Crystal Language Layer The Language Layer exposes the PCRE customization API in a language dependent manner For C and Java applications the language layer provides a moderately object oriented version of the API through classes that implement print engine and print job objects Additional classes allow client applications to connect to servers and provide exception oriented error handling which is natural for these languages By contrast ANSI C applications interface to a traditional C header file which contains the declarations of all the API functions Error handling is provided using a system of returned error messages and codes Component Layer The Component Layer exposes the PCRE customization API using industry standard component object models Currently the language layer includes the PCRE ActiveX Automation Server that supports the Microsoft CO M standard The Automation Server re expresses the customization API as a hierarchy of objects offering dual interfaces that can be used by Microsoft scripting languages such as VBScript and JScript and Microsoft compiled clients such a
296. nts This chapter describes how to solve the problems that most frequently occur when developing Parallel Crystal clients in C or C Problems with Client Connections An attempt to connect your C client with the connect method or to connect your C client with the PEInitialize OF PEConnect functions can fail for a number of reasons The most common causes are 1 2 An invalid Report Server host was specified in the client constructor call either the host name or the IP address is incorrect Your client was able to connect to the Report Server but the G ateway could not start a Report Engine Server Perhaps you specified incorrect command line arguments or the machine was so busy that the G ateway timed out before the Server could get started Or perhaps the Parallel Crystal Installation has been moved and the Report Server s executable path name which is configured at install time is no longer valid If you experience the timeout problem use the setwait method of the pcrEGateway service provider to increase the time in seconds For example in C PCREAppClient client host try Wait for up to 120 secs for connection client getGateway gt setWait 120 client Connect API calls catch PCREError amp e e Report client Quit OrinC PEInitialize NULL host 0 NULL PE _NO_CONNECT PEGatewaySetWait PEGetGateway 120 if PEConnec
297. nts Its function may vary depending upon your installation The following fragment shows how the get property methods can be used to access the Gateway and Configuration servers PCREAppClient client PCREGateway gateway client getGateway PCREConfigServer config client getConfigServer The pcrREAppClient Class is responsible for managing the life times of its service provider classes Y ou should not attempt to create a service provider independently or invoke the delete operator on an instance or access its methods after you have called the client s Disconnect OF Quit methods The PCREGateway and pcREServer providers are described briefly in the next two sections The pcreconfigServer is described in the section entitled Parallel Crystal Configuration Server If you don t plan to use these advanced features of Parallel Crystal then skip directly to the section entitled A pplication Client Connection Parallel Crystal D eveloper s Manual 256 Version 2 4 Revised 5 27 00 Accessing PCREGateway Properties from C The pcrEGateway provides client access to the Parallel Crystal G ateway Server running on the Report Server machine The property methods allow you to specify the Report Server host and the name of the G ateway running on that host They also allow you to specify the value of a timeout which controls the period of time that the G ateway will wait hile trying to start a Report Engine
298. o Release The COM interfaces provided in Visual Basic VBScript and Visual J release the interface internally It is very important for clients to call Disconnect FromReport Server to terminate their Report Engine Servers and to release client side resources Connecting to the Automation Server The manner in which Automation Server connections are made depends upon the choice of client language In particular If you use C with the bare COM API the Application Object reference is returned by calling CoCreateInstance HRESULT hr ICRApplication pApp hr CoCreateInstance CLSID_CRApplication NULL CLSCTX_INPROC_SERVER IID_ICRApplication reinterpret_cast lt void gt amp pApp g Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 If you use Visual C COM support classes the A pplication O bject reference is returned by calling the rcrapplicationPtr constructor ICRApplicationPtr pApp pApp __uuidof CRApplication If you use Visual J and have imported the Automation Server Type Library with the Java Type Library wizard the Application O bject reference is returned by creating an instance of the Java crapplication wrapper Class and casting the result to the ICRApplication interface ICRApplication app ICRApplication new CRApplication If you use Visual Basic and have imported the Automation Server Type Library with the Project References dialog the A ppl
299. o report particularly serious errors with a message box Clearly if the message is displayed on the Web Server the client can neither view nor dismiss it However you can produce a message box in the client s browser by modifying the ReportError procedure in the example as follows Sub ReportError msg Response write lt SCRIPT LANGUAGE amp Chr 34 amp VBScript amp Chr 34 amp gt Response write Alert amp Chr 34 amp msg amp Chr 34 Response write lt SCRIPT gt bOK False Err Clear End Sub This piece of trickery generates the following script that is executed in the browser when it receives the response lt SCRIPT LANGUAGE VBScript gt Alert lt contents of msg gt lt SCRIPT gt The actual argument to alert is the msg string enclosed within double quotes Notice the use of the _ continuation marker to allow a VBScript statement to be continued on the next line and the separator that allows multiple statements to occupy the same line Note TheE rror O bject in A SP 3 0 may be used for better eror handling Trouble Shooting Simple ASP Clients In this section we ll take a look at the most common errors that occur when programming simple clients using ASP We ll assume that errors are reported by accessing the appropriate Get LastErrorString property in the Automation Server e The call to the Application O bject method connect ToReport Server may fail and report the
300. o specify a codebase attribute in the lt applet gt tag which specifies that directory relative to the Web Server root Parallel Crystal D eveloper s Manual 112 Version 2 4 Revised 5 27 00 To avoid version incompatibility problems ensure that your applet downloads the CORBA framework included with the Parallel Crystal Java Client Distribution by including the following lt param gt tag between the lt applet gt and lt applet gt tags lt param name org omg CORBA ORBClass value com visigenic vbroker orb ORB gt When connecting to the Report Server your applet client needs to contact the IO P GateK eeper To do this it needs to download a file called gatekeeper ior from the Web Server Normally the client expects to find this file in the same directory as the applet s class file The Parallel Crystal installation normally includes this file in the directory c MobileApps pcre ior S0 you can copy it to the required locations The G ateK eeper also generates the file each time it runs so you may find duplicate copies lying in other directories If you don t want to copy the gatekeeper ior file each time you can include its location in a lt param gt tag included between the lt applet gt and lt applet gt tags lt param name ORBgatekeeperIOR value http www acme com classes gatekeeper ior gt If you know for sure that your Report Server and Web Server are on different machines then you will always need to use the G at
301. ocedure parameters in your report GetNParameterFields GetNthParameterField SetNthParameterField GetParameterField SetParameterField Parameter fields are accessed by an index value ranging from o to GetNParameterFields 1 The GetnthParameterField method accesses the n th field and returns its attributes in a struct called pcrEParameterFieldinfo The following code fragment retrieves and resets all the parameter fields in a report Parallel Crystal D eveloper s Manual 281 Version 2 4 Revised 5 27 00 int nParamFields job gt GetNParameterFields for int i 0 i lt nParamFields i PCREParameterFieldinfo info job gt GetNthParameterField i amp info check parameter field job gt SetNthParameterField i amp info The GetParameterField and setParameterField methods allow slightly more convenient access using the name of the field rather than its index value DataBase Table Manipulation The following group of methods allows you to access database tables within your report GetNTables GetNthTableType GetNthi Location SetNthTableLocation GetNthTableSessionInfo GetNth Logoninfo SetNthTableLogonInfo TestNthTableConnectivity Tables are accessed by an index value ranging from 0 to GetNTables 1 The following fragment indexes through all the tables in a report and prints the Log on information for each The method cGetNthTableLogOnInfo return
302. of D atabaseField D efinition O bjects Enum Methods Custom Properties Navigation Item Count Parent _NewEnum Report Application Table 6 19 ICRDat aBaseFieldDefinition is the custom interface exposed by each D atabaseField Object in the collection The methods and properties are listed in Table 6 20 They provide access to the name kind and content attributes of the field Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Methods Custom Properties Navigation Kind Parent Name Report Text Application Table 6 20 Interface acquisition Dim dbfldc As ICRDataBaseFieldDefinitions Dim field As ICRDatabaseFieldDefinition Set dbfldc table Fields Set field dbflde Item 1 Set field dbfldc 2 Collection iteration For Each field In table Fields If field Kind crFormulaField Then Dim fname As String fname field Nam End If Next ICRDataBaseParameter s ICRDataBaseFieldparameters is the collection interface exposed by the DatabaseParameters Collection O bject The methods and properties are listed in Table 6 21 A DatabaseParameters Collection O bject is obtained from the parameters property of the D atabase O bject Each item in the collection is a D atabase Parameter O bject representing a stored procedure or parameterized query within the database and the number of D atabase Parameter O bjects is returned by the count property Ind
303. of software within each client and the processing power required of each is reduced e All the reports are located within the report server making the reporting process is easier to administer e Both servers are dedicated to a single well defined role and can be tuned for performance in that role Parallel Crystal D eveloper s Manual 20 Version 2 4 Revised 5 27 00 Distributed Report Server Processing Execution of the customization program is now distributed between the Parallel Crystal desktop clients and the Parallel Crystal Report Engine running in the Report Server The process of remoting the customization call from the client to the server is accomplished with a technology called CO RBA that in turn uses a network protocol called IIO P that is designed specifically for invoking remote API calls Imagine for a moment Example 1 1 on page 18 running in the client When execution reaches the statement PCREJob job engine OpenJob Box rpt the name of the report file is transmitted to the server and the corresponding Report Engine API call is made with the function propenPrint Job If you look up this function in the Seagate Crystal Reports Developer s Help information you will find that it is declared as the C function short PEOpenPrintJob char reportFilePath When the function completes it returns an integer that represents a handle to the print job and this handle is returned to the PCRE client pro
304. ol the flow of execution through the report generation part of the script This line implicitly declares the variable called box and clears the current error indicator All variables in VBScript have the Visual Basic type variant So you need not use explicit Dim statements This sequence of statements shows how VBScript uses the built in object Request to retrieve the strings entered into the HT ML form Each entry is recovered using an equivalently named property of the request object The entries are treated as Variants containing strings and therefore we can combine them using the Visual Basic string concatenation operator amp This sequence of static HT ML formats a table containing the Report Server host name the path name of the report file and the path name of the HTML report to be generated The script between lt s and s gt brackets generates the report using the highlighted methods of the PCRE Automation Server This line is the most important on the whole page When you make calls to the PCRE Automation Server the VBScript interpreter handles the low level CO M interface internally However if a method returns a failure result code the interpreter stops and delivers the code back to the client in the form of a hexadecimal string The on Error Resume Next Statement allows us to override the default error handler and provide our own error message However it also means that after every method call the result code must be
305. om the pcreError Class so the easiest way to catch both is to specify pcrEError in the catch clause 2 Version 2 4 Revised 5 27 00 Connections to both the G ateway and Report Engine Servers are established on the basis of the host and name strings that are supplied through the service provider property methods The host specifies a particular Report Server on your network and the name identifies a particular instance of the Server on that host The Report Engine Servers are assigned unique names by the G ateway so that they can be identified to their clients The G ateway Server is normally assigned the default name pcre A client is always connected to G ateway and Report Engine Servers on the same host Occasionally it may be more appropriate to make connections based on logical Server names rather than Report Server hosts In order to do this you must omit the host from the client constructor call and use the pcrEGateway S setName property method For example try PCREApplicationClient client new PCREApplicationClient example host com client getGateway setName purple client Connect catch PCREError e e Report This code will then try to connect your client to a Report Server running the G ateway named purple running on example host com You must ensure that the argument supplied to the setName method matches the
306. on PEGet SubreportInfo PEOpenSubreport PEGetNthSubreportInSection Stored Procedure PEGetNParams PEGetNthParam Functions PESetNthParam Table Management PEGetNTables PEGetNthTableType Functions PEGetNthtableLogOnInfo PESetNthTableLogOnInfo PEGetNthTableLocation PESetNthTableLocation PETestNthTableConnectivity PEGetNthTableSessionInfo PESetNthTableSessionInfo Table 9 11 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 287 Error Recovery in C Clients The Parallel Crystal C client has no special facilities for error recovery Most of the API functions return a boolean result indicating success or failure If the function fails you can call pEErrorCode and pEGetErrorText to get the error code and message returned from the Report Engine Server Unfortunately the error text is returned as a handle to a string so an extra call to pEGet HandleSt ring is required to retrieve the message as a null terminated C string The following code fragment shows a typical function that retrieves the error code and message following an A PI failure AG Report is the LE mo retrie the error occurring in the last API call Job print job handle or 0 The function returns error occurred or the message could not be ved void ReportError short job HANDLE handle short length code char buffer 256
307. onnect st int argc C does not provide default arguments so you must supply a value for each parameter The argument console is a pointer to a PEConso1e structure that provides access to a PCREConsole implementation If you supply nut for this argument the initialized with a default console that is functionally equivalent to the pcr implementation Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 client will be FAppConsole 253 The argument host specifies the Report Server to which your client will connect It may take the form of either a symbolic host computer domain name or a dotted host computer IP address For example PEInitialize NULL example host com 0 NULL PE_DO_CONNECT PEInitialize NULL 111 222 333 444 0 NULL PE_DO_ CONNECT If you supply nuz or the empty string for host then your client will be connected to a Report Server somewhere on your network We recommend that you supply a host name whenever possible for the reasons stated in the previous section The argc and argv arguments are derived from the command line arguments to your application and are used to provide fine control over the connection process Again the remarks in the previous section apply The connect argument allows you to control whether your client should be initialized and connected in one step or whether you wish connection to be defer
308. onnected from the Report Server Automatic Report Retrieval requires your Parallel Crystal to be installed with a file transfer service If this service is not running then the call to output ToppF will fail If you call the LastErrorString property of tcRReport it will return the message PCRE ServerError Connect cannot connect to PCRE File Transfer Service One you have connected to a Report Server you can switch the Report Retrieval on or off by setting the ReportRetrieval property to True Or False Parallel Crystal D eveloper s Manual 216 Version 2 4 Revised 5 27 00 Parallel Crystal Load Balancer When your client has access to a group of Report Servers you can use the Parallel Crystal Load Balancer service to ensure that the report processing load is distributed appropriately across the available server machines The load balancer provides two interfaces for automatic and manual use When you use automatic mode the client is connected to a Report Server chosen by the Load Balancer The choice is made by a selection algorithm that is normally configured by the System Administrator The two algorithms most commonly used are called load factor and round robin The load factor algorithm compares all the Report Servers in the group and returns the one with the smallest load The round robin algorithm simply cycles through all Report Servers in turn and selects the next one in the sequence When you use manual mode th
309. ons return the value TRUE if they succeed and Farse if there was an error The error message can be retrieved with a call to PEGetErrorText You must call p P P P EServerSetArgument and PEServerAddArgument after a call to EInitialize with ape_no_connect argument Then you must call peconnect and EInitapr to connect the client to the Report Server Y ou can call EServerGetArguments before or after a call to PEConnect EGet Server as its first Property Name Purpose P EServerSetArguments Supply the command line argument string P EServerGetArguments Return the command line argument string P EServerAddArgument Append a command line argument to the string Table 9 7 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 263 In the following example we specify client and folder arguments before connecting to the Report Server PEHANDLE svHandle Must call PEInitialize with PE_NO_CONNECT PEInitialize NULL NULL 0 NULL PE_NO_CONNECT Get Server handle and set command line arguments svHandle PEGetServer if PEServerSetArguments svHandle client toby folder C MonthlyReports ReportError goto close Connect to Report Server on host if PEConnect ReportError goto close Complete initialization if PEInit
310. ort Server host determined by its current selection algorithm and the client is connected to that host 3 If there are no Report Servers available to the Load Balancer the connect call will throw a pcREServerError exception and at Step 3 the message Server error Load Balancer failure no available Report Servers will be printed In order to use the Load Balancer in manual mode you call the Request Report ServerList method that returns a vector of candidate hosts You apply your own selection procedure to the vector and then call the client s ResetReportServerHost method passing the selected vector element Finally you call Connect to connect to the client to the Report Server The following example shows a typical code fragment PCREApplicationClient client null try client new PCREApplicationClient LB host com PCREReportServeriInfo servers client RequestReportServerList PCREReportServerInfo host MySelection servers client ResetReportServerHost host client Connect method calls catch PCREError e Report Each element of the vector returned by requestReportServerList contains information about the Report Server encapsulated as an instance of the helper class PCREReportServeriInfo public class PCREReportServerlInfo public double loadFactor Gateway load factor public int numberOfServers Number of running server
311. ort getLastErrorCode public abstract java lang String getLastErrorString public abstract java lang String getserver public abstract java lang Object getServerSettings public abstract java lang Object getOptions Put properties public abstract void putFTPUserName java lang String public abstract void putFTPPassword java lang String public abstract void putOSAgentAddress java lang String public abstract void putRetrieveMode int Methods public abstract void ClearError public abstract void ConnectToReportServer java lang String public abstract void DisconnectFromReportServer public abstract java lang Object OpenReport java lang String com ms com Variant public abstract void LogOffServer java lang String java lang String com ms com Variant com ms com Variant com ms com Variant public abstract void LogOnServer java lang String java lang String com ms com Variant com ms com Variant com ms com Variant public abstract boolean CanClose public abstract void ParallelPrintReport java lang String int int java lang String java lang String Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 146 The extract shows that each method and property in the CO M interface is mapped to a corresponding abstract method in the Java interface In particular e BSTRs are mapped to Java Strings e VARIANTS are mapped to a Java class called variant in the package com ms com
312. ort method at all If you have trapped the error with an appropriate try catch block then how you handle it thereafter is entirely within your control Parallel Crystal D eveloper s Manual 292 Version 2 4 Revised 5 27 00 Console Interface The Parallel Crystal C C client library does not make any internal assumptions about the nature of your application In particular it does not know whether output messages will be sent to a character stream or displayed in a G UI Consequently the reporting facilities incorporated into the error handling classes output error messages using an abstract application console interface You can adapt this interface to your application by providing an appropriate implementation class The Parallel Crystal Application Console interface is represented by the abstract base class PCREConsole It contains seven pure virtual methods that allow a message to be displayed according to the kind of information it conveys For example fatal error messages might be accompanied with a sound effect whereas API errors might simply be written to a text window You provide the appropriate implementation of these methods in an implementation class derived from pcrEconsole If your application uses a simple character based user interface then the pre packaged pcREAppConsole Class may be adequate for your requirements You must install your application console by supplying it as the f
313. osevesazavessesvasancoasavayesevasancongonasasevavevessasd soseiavexevavasd oiessazanssavenscsssesazeere 49 Chapter 3 Using the Java Client Package ssssssssssssssssssssssessssssssscssssessscsssessseasessesssssssessassssessessossessssessesssecssssessssssessassssessees 51 Parallel Crystal Clients ccc ri ssa cusies AEE E E S UE ES EOE aes ena ean ete Rates eens 53 DELVICES LOE CENS ears SE N A EA AAE ATTESE A AAEN ARNARS AT AIEEE DEE Application Client Instantiation Applet Chent stantati oeio ienris iaaii Eaa a aS NE ANE AAEE REOS EEEE EEE EEEE ENEA A E Client Confira On esserne oE EEREN EEEE E AEE VEE Ea PCREGateway Properties PCREServer Properties Application Client Connection Applet Chent Connection siorino riniisiiivi tiai ts intis Aat a ENEE RREN TRENS ANEO EEEE AENEA A 6l Client ORB ManatemMmen tsooni EEEO E EA E T E EATEN E ERA TRE 65 Client Disconnection iss aroye sesesexsaitvs rara araraya raO o EEO EAE IESKO NES EETA TO PEPEN ENESOVE SOS KANA A Vo EE KOPETE EOR ESO TAISE IE TEET S 66 Parallel Crystal D eveloper s Manual 3 Version 2 4 Revised 5 27 00 Report Gener tor E EA EREA AA uta Gaede AERO AROK ER EA OEE AEA ORS HOB RC URNS i 67 Accessing Report Engines and Print JobSreir oeren tern ro EAE ETEA ETEO EAA RA ER REOT Ni 67 Customizing Print Jobs Print Job Executionsuinsaesare MONEE EEE E E T O O OEE E Print Job Details riana nan Aa A RR AENA ER EN N EN EEES rterprecer erent Print Job Outputs Form
314. oss referenced according to the JavaD oc standard e developr hip is the Windows help file for the Seagate Crystal Reports Print Engine API You may need to consult both files to understand how the customization function is mapped to an equivalent method of the pcreEngine OF PCREJob Classes Accessing Report Engines and Print Jobs Once you have connected your Java client to the Report Server you get a reference to the Report Engine by calling the client s openEngine method PCREApplicationClient client null try client new PCREApplicationClient example host com client Connect PCREEngin ngine client OpenEngine j run print jobs engine Close catch PCREError e e Report client Quit Y our client only has access to a single Report Engine Server so successive calls to OpenEngine Will return the same value When you are finished you should call the close method to release resources in the Report Engine Server If you call openEngine when your client is not connect to a Report Server it will throw a pcrEClientError exception The most important methods of the pcreEngine Class are summarized in Table 3 5 on page 68 Parallel Crystal D eveloper s Manual 67 Version 2 4 Revised 5 27 00 Method Purpose OpenJob Open a print job OpenSubReport Open a sub report PrintReport Start a report run Par
315. ou return to the page containing your applet the start method is called again Finally if you terminate your browser then the destroy method is called You can control the behavior of your applet by overriding the init start stop and dest roy methods with your own implementations Although there are several possible approaches we recommend that you write a Parallel Crystal client applet using the framework shown in Example 2 4 on page 42 Parallel Crystal D eveloper s Manual 41 Version 2 4 Revised 5 27 00 import java awt Fo Ve import java applet Lhe 2s import com mobileapps pcre J 3 public class PCREApplet extends Applet Bl As implements PCREConsole JE Bs private PCREAppletClient client null 6 PCREConsole implementation methods 7 Applet implementation methods private void RunJob 8 customize and run report Override called when applet loaded public void init Ef 9 create applet user interface Override called when page is visited public void start 10 connect client to the PCRE report server Override called when page is departed public void stop A AL disconnect client from the PCRE report server Override called when browser is terminated public void destroy ff V2 disconnect client from the PCRE report server Despatch handler public boolean action Event evt Object ar
316. output in the specified format The Automation Server presents an object oriented interface and to achieve results you are going to have to create at least two objects These are the A pplication object and the Report object VBScript does not require declarations for simple variables so you will simply see App and Report appear below The Application object allows you to set up a connection to a report engine on a Report Server Start with On Error Resume Next Should anything go wrong it can be a little abrupt for the default error handler in ASP to merely give us a Catastrophic Error message The effect of the On Error Resume Next statement is to make execution of the script continue after an error Now if anything goes wrong we can see what the specific problem is and report it from an error handling block that we can write You create an Application object as follows Set App Server CreateObject MAS CRApplication 1 The MAS PCRE product is a true N tier client server application Your client knows that the Report engine could be anywhere on the network or could be on the same machine Unlike the Seagate Automation Server product there is no need to run the CPU intensive report engine on your busy Web Server To make a connection with a report server you tell the Application object what machine it should contact and ask for a report engine on App ConnectToReportServer Tampa Parallel Crystal D eveloper s M
317. ow to call its methods and properties and how to iterate through collections For brevity these samples are given using Visual Basic syntax They can be adapted to other Automation Client languages as follows e Visual Basic Dim report As ICRReport Set report app OpenReport C SampleReports Box rpt e VBScript Dim report Set report app OpenReport C SampleReports Box rpt To convert to VBScript remove the as clause from each Dim statement Use the same syntax for calling methods and properties e Visual J ICRReport report report ICRReport app OpenReport C SampleReports Box rpt To convert to Visual J use the interface name to declare an interface reference variable When calling a property that returns an interface cast the property result using the interface name as shown above Insert left and right parentheses for all method and property calls e Visual C ICRReport report report static_cast lt ICRReport gt app gt OpenReport C SampleReport Box rpt To convert to Visual C use the interface name to define an interface pointer variable When calling a property that returns an interface use a static_cast to cast the result to the interface pointer as shown Insert left and right parentheses for all method and property calls The interface descriptions are only intended as summaries Y ou should consult the PCRE Automation Server online documentation for detailed descriptions o
318. p indexes through the list of Report Servers The index values run from 1 through to the value returned by get count Parallel Crystal D eveloper s Manual 23 Version 2 4 Revised 5 27 00 The property method get rt em returns a reference to the i th Report Server O bject in the list The property returns an O bject reference that must be cast to the custom interface type IcRServerLoad The load factor for the i th Report Server is returned by the get Loadfactor property method If the value is less than minLoaa the values of minLoad and selected are updated If a Report Server was chosen the value of selected is passed to the Connect ToSelectedReport Server method which makes the client connection If the client is successfully connected to the Report Server a message box displays the server s host address Parallel Crystal D eveloper s Manual 224 Version 2 4 Revised 5 27 00 Chapter 7 Trouble Shooting ActiveX Clients This chapter describes how to solve the problems that most frequently occur with ActiveX automation clients Problems with Client Connections An attempt to connect your client to the Automation Server can fail for the following reasons 1 The Automation Server DLL cpemas1 d11 has not been installed on the client machine Y ou can check for this by any of the following means e Use the regedit tool to check the registry entries in the hive HKEY_CLASSES_ROOT With the exception of the D LL path n
319. pe HTMLFileName ailBccList ailMessage ailSubject ailToList ailCcList umberOfLinesPerPag ODBCExportTableName ODBCDataSourcePassword ODBCDataSourceUserID ODBCDataSourceName UseReportNumberFormat UseReportDateFormat Table 6 26 You must set both rormatType and Dest inat ionType and then depending upon their values set additional properties appropriately The values of Format Type are supplied by a set of constants of the form crerTxxx listed in the online documentation and the values of DestinationType are supplied by a corresponding set of constants of the form crEDTxxx When all properties are set you must call the export method of the Report Object to register the settings for the current report When you call the printout method the report is generated according to the export settings Version 2 4 Revised 5 27 00 Interface acquisition Dim options As ICRExportOptions options report ExportOptions Method and property calls Generate report in Excel format and store on disk options FormatType crEFTExcel40 options DestinationType crEDTDiskFile options DiskFileName C SampleOutputs Box xls report Export report PrintOut Generate report in Text format and send as Email options FormatType crEFTText options DestinationType crEDTMailMAPI options MailToList toby acme com options MailCcList options MailSubject Box Of
320. perty of the parent Report O bject Methods Custom Properties Navigation Properties Verify Parameters ConvertDatabaseDriver Tables Parent Report Application Table 6 16 Interface acquisition Dim db As ICRDataBase Set db report Database Methods calls db Verify ICRDataBaseTable s ICRDataBaseTables Is the collection interface exposed by the D ataBaseT ables Collection Object The methods and properties are listed in Table 6 17 A databaseT ables Collection Object is obtained from the rabies property of the Database O bject Each item in the collection is a D atabase Table O bject representing a table within the database and the number of Database Table O bjects is returned by the count property Individual D atabase Table O bjects are obtained by the rt em method that takes an index or argument identifying the table required Visual Basic clients may iterate through all items with the For Each Statement that calls the _NewEnum property to create an enumeration of D atabase Table O bjects Bl Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Methods Custom Properties Navigation Item Count Parent _NewEnum Report Application Table 6 17 ICRDat aBaseTab1e is the custom interface exposed by each D atabase Table O bject in the collection The methods and properties are listed in Table 6 18 They provide access to the attributes of the table and it
321. ple HTML Report If the reports you wish to generate are web based and intended for display exclusively through web browsers then it may be appropriate to generate the report as an HT ML file Example 8 6 below illustrates how the Boxoffice report can be generated in HTML We have omitted the reportError function for brevity include lt pcre h gt include lt stdio h gt include lt string h gt void main int argc char argv PEExportOptions options 1 UXFHTML30ptions formatOptions UXDDiskOptions diskOptions short job BOOL bOK PEInitialize NULL example host com argc argv PE_DO_CONNECT if IOK ReportError 0 goto close_app if PEOpenEngine ReportError 0 goto close_app job PEOpenPrintJob C MobileApps PCRE SampleReports Box rpt if job ReportError job goto close_engine Example 8 7 cont on next page 5 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 formatOptions fileName 2 C MobileApps PCRE SampleOutputs Box htm1 strcpy options formatDLLName u2fhtml d1l options formatType UXFNetscape2Type options formatOptions void amp formatOptions diskOptions fileName strcpy options destinationDLLName u2ddisk dll1 options destinationType UXDDiskType options destinationOptions void amp diskOptions if PEExportTo job amp optio
322. port the error using the LastErrorString oraccess the Err Description property or simply produce your own error message Microsoft Visual Basic Run time error 2147467259 80004005 Method ConnectToReportServer of object ICRApplication Failed Gontinue Figure 5 5 Parallel Crystal D eveloper s Manual 159 Version 2 4 Revised 5 27 00 Unfortunately the presence of LastErrorString properties in both the ICRApplication and ICRReport interfaces means that on reaching an error handler you must know which one to call For example in cmdRun_click the handler calls app LastErrorString This is correct if the error occurred in app OpenReport but incorrect if the error occurred in report PrintOut There are various solutions to this problem 1 You can restructure the code so that calls to rcrReport methods occur in a different procedure whose handler need only ever call 1crReport LastErrorString 2 Youcan set context flags so that acommon handler can choose the correct LastErrorString to call 3 You can use the Visual Basic on Error Resume Next Statement that will return control to the statement following the Automation Server method call Then you must test the result code in err and report an error if required For example On Error Resume Next Set report app OpenReport txtReport txt If Err Number lt gt 0 Then sgBox OpenReport amp app LastErrorString Exit Sub
323. portServer After the connection is made we call Release ON pSelectea since we are finished with the interface If no Report Server was selected an error could be reported at this point 8 The ICRReportServers and ICRReportServer interfaces are released to allow storage reclamation in the Automation Server Much of the complexity in the example derives from the need to convert from 1pispatch interfaces to custom interfaces and from the ever present need to manage object lifetimes by releasing their interfaces Using Manual Load Balancing with Visual Basic In this example we show how to use the Load Balancer in manual mode using Visual Basic We assume that app is a global reference to the Application O bject that has been established when the main form is loaded For simplicity the code is presented as a single procedure that is executed when a Connect button is pressed Parallel Crystal D eveloper s Manual 21 Version 2 4 Revised 5 27 00 Sub CmdConnect_Click Dim selected As ICRReportServer Server As ICRReportServer 1 Dim count As Integer minLoad As Double minLoad 1000 E selected Nothing Iterate through the collection For Each server In app ReportServers EEN Dim load As Double load server Loadfactor Vey If load lt minLoad Then minLoad load selected server End If Next Connect to selected Report Server If IsObject selected Then MD app ConnectToSelectedReportServer selected Msg
324. pply nut the client will be initialized with a default console that provides character based output facilities Specifies the domain name or IP address of the Report Server host Specifies the number of elements in the argv vector Traditionally it is derived from the value passed to your application s main entry function A null terminated vector of null terminated command line argument strings Traditionally it is also derived from the value passed to your main entry function argc and argv are occasionally required to provide special connection parameters to the underlying CO RBA networking layer Specifies whether or not PEInitialize should connect your client to the Report Server The possible values are specified by symbolic constants defined by macros in the header file define PE_NO_CONNEC 0 define PE_DO_CONNEC 1 define PE_LB_ CONNEC 2 where PE_NO_CONNECT prevents connection PE_DO_CONNECT enables connection and pz_B_connecr enables connection via the Load Balancer Connection via the Load Balancer is described in the section Parallel Crystal Load Balancer Parallel Crystal D eveloper s Manual 269 Version 2 4 Revised 5 27 00 Calling the function pzInitRemote which is declared with the signature BOOL PCRE_API PEInitRemote const char host is equivalent to calling PEInitialize NULL host 0 NULL PE_DO_CONNECT The connection process is exac
325. property call that can return a COM error check the number property of the built in err object If the value is non zero then an error has occurred 3 Call the LastErrorstring property of the 1CRApplication OF ICRReport interface to return the Automation Server error message 4 Always ensure that if you have called connect ToReport Server you make a corresponding call to pisconnectFromReportServer 5 Use tsobject to check object references returned by the Automation Server are valid For example here is a slightly modified fragment from the example that uses the LastErrorString property to access the error message If bOK Then Dim Report Set Report PCREApp OpenReport ReportPath If Not IsObject Report Then ReportError OpenReport amp PCREApp LastErrorString End If End If If bOK Then Report ExportToHTML OutputPath If Err Number lt gt 0 Then ReportError ExportToHTML amp Report LastErrorString End If End If Parallel Crystal D eveloper s Manual 176 Version 2 4 Revised 5 27 00 If the error does not occur in an Automation Server method or property then you can call the Err Description property that will return a generic COM error message For example Dim PCREApp Set PCREApp Server CreateObject MAS CRApplication 1 If Not IsObject PCREApp Then ReportError CreateObject Err Description End If Sometimes it may be useful t
326. psi Thereafter this same O RB will be shared by client2 and any ORB related values in args2 and props2 will be ignored This situation applies independently of whether ciienti and client2 are created on the same or different threads Normally sharing of O RBs between clients does not create problems particularly if each client is connected to the same Report Server However if the clients have distinct connection requirements that require conflicting argument values to be supplied to the ORB then you must create a separate ORB for each client You can do this with the static createorB method of the PCREORBFactory class PCREApplicationConsole console new PCREApplicationConsole org omg CORBA ORB orbl PCREORBFactory createORB argsl propsl PCREApplicationClient clientl new PCREApplicationClient console hostl argsl propsl orbl client1 Connect org omg CORBA ORB orb2 PCREORBFactory createORB args2 props2 PCREApplicationClient client2 new PCREApplicationClient console host2 args2 props2 orb2 client2 Connect ORB related arguments are supplied either as command line argument strings with the form ORBname valu Oras property name value pairs with the form ORBname value Requirements such as these are in fact pretty unusual and we advise you to consult with your System Administrator or our Technical Support Service before attempting to use customized O RBs Client
327. pure Java C C etc e A sample of some of the data being used if applicable e Information about any stored procedures being used in the report file Bl Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Telephone Support We offer telephone support at the following numbers USA 1 888 662 7771 314 205 8995 We would like to encourage you to use our Tech Support email address before calling on the telephone for support We are always happy to take your call but generally we have found that we have better and more accurate responses to inquiries when they are handled through email Thanks Getting Software Updates Updates to the Parallel Crystal software are available on our internet site at http www dynalivery com Select downloads To get permission to download you use a user name derived from your Parallel Crystal Product Serial Number and a password that is included on the back cover of your Parallel Crystal CD For example if your Serial Number is 9807 004 then your user name is 9807004 Your FTP account is valid for the period of your evaluation and for one full year thereafter if you purchase the software Bl Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Why use Parallel Crystal Parallel Crystal incorporates an enhanced version of Seagate Software s popular Crystal Report Engine into a multi user server environment Y ou can connect remotely
328. r Returns the Web Server s root directory getPCREOutputDir Returns the Web Server s output directory getPCREGatewayName Returns the name of the Parallel Crystal G ateway Server getPCREFileServer Returns the file transfer method getPCREConfigInfo Returns an aggregate of configuration strings GetPCREDORTempDir Returns the DOR temp directory StrFree Releases a configuration string Table 9 13 Parallel Crystal D eveloper s Manual 298 Version 2 4 Revised 5 27 00 Here is a simple example that shows how to retrieve the host name of your Report Server and the version of Parallel Crystal that it is running PCREAppClient client try client Connect PCREConfigServer config client getConfigServer char version config gt getPCREVersion char host config gt getPCREHostName cout lt lt Connected to PCRE version lt lt version lt lt lt lt host lt lt endl PCREConfigServer StrFree version PCREConfigServer StrFree host catch PCREError amp e e Report To avoid memory leaks you should release a configuration string when you are finished with it by calling the static st rrree method If you want to retrieve all configuration strings in a single call you can use the get PcREConfigInfo method that will copy the strings into character arrays contained in a struct called pcreconfigI
329. r amp error Li AV error Report f f 12 Example 8 3 Parallel Crystal D eveloper s Manual 239 Version 2 4 Revised 5 27 00 Generating a report in HTML looks a little more complicated since two extra statements are required rather than one In the example line 6 creates an instance of the PCREHTMLJobExport Opt ions Class using the name of the HT ML file as an argument to the constructor This object is passed to the Export To method that informs the Print Engine DLL that the output for the print job is to be exported to HTML The HTML file is generated when the job is started at line 7 Notice that when a graphical report is generated in HTML any embedded images will be stored in additional JPEG files in the same directory If the name of the HTML file is Box ntmi the JPEG files are named Box001 jpeg Box002 jpeg and so on The Parallel Crystal Report Engine supports a large number of additional export formats which allow reports to be formatted for a variety of front office tools We ll describe these formats in greater detail in Chapter 9 Summary e The preceding four sections have described how to construct simple C clients that connect to a Parallel Crystal Report Server running on a named host An exception will be generated if you give an incorrect host name or Parallel Crystal is not running on that machine e Reports are generated by getting access to a print engine and then opening a p
330. r effect can be achieved by writing an error handling class with two overloaded versions of ReportError one of which takes an rcRApplication interface and the other an rcRReport interface Trouble Shooting Simple Visual J Clients In this section we ll take a look at the most common errors that occur when programming simple clients using Visual J We ll assume that errors are reported using the ReportError from the previous section or something similar that uses the GetLastErrorString from the Automation Server e The call to the Application O bject method connect ToReport Server may fail and report the error No connection to a Server Report Engine has been made There are two possible reasons for this error either the argument string does not specify a valid host name or the Parallel Crystal Report Server was not running on the specified host Check that the string you supplied is either a valid host domain name or IP address and then check that Parallel Crystal is installed and running on that host If the problem persists check Chapter 7 Trouble Shooting ActiveX Clients Parallel Crystal D eveloper s Manual 151 Version 2 4 Revised 5 27 00 The call to the Application O bject method openreport may fail and report the error Invalid file name This error occurs when the report file specified by the argument string does not exist on the Report Server Check the location of the file and then suppl
331. rallel Crystal D eveloper s Manual 52 Version 2 4 Revised 5 27 00 Parallel Crystal Clients In this section we describe how to create Parallel Crystal clients as Java applications or Java applets Each client uses a set of service provider classes to access a corresponding set of Report Server programs that provide report generation load balancing and connection management services A client can connect to all services using a single API call or can customize individual connections by setting properties through the service providers In the following sections we describe the how clients are created how they connect to the Report Server and how they can customize their connections We begin with a short overview of the server programs running on the Report Server and the services they provide Services for Clients When a Parallel Crystal Report Server is started it makes a range of services available to your client through special purpose servers The special purpose servers include e The Gateway Server provides an initial point of contact for your client and is responsible for starting a Report Engine Server to generate your report All clients share access to a single G ateway running on the Report Server To connect to the Gateway you must specify the Report Server host and optionally the name of the Gateway e The Report Engine Server provides report customization and generation facilities The Report Engine is al
332. rcRapplication interface The reference count is reduced to zero that causes the A pplication O bject to be deleted Clearly the wrapper classes generated by import combine with the _bstr_t _variant_t and _com_error Classes to provide a far more user friendly COM programming environment for C Full documentation on these Visual C features is available in the MSDN and the book BegnningA TL COM Programming by Richard_Grimes also contains some very useful examples Parallel Crystal D eveloper s Manual 139 Version 2 4 Revised 5 27 00 Generating PDF and HTML Reports with VC and COM Changing the example in the previous section to generate reports in alternative formats such as PD F or HTML is trivial In each case the call to Printout in Step 8 is replaced with one that generates the report in the appropriate format In particular e To generate a report in PDF and save the results replace the call to printout with the following call to output ToPDF Step 8 report gt OutputToPDF C SampleOutputs Box pdf When the method returns the PDF report will be stored in the file Box pdf in the SampleOutputs directory e To generate a report in HTML and save the results replace the call to printout with the following call to Export TOHTML Step 8 report gt ExportToHTML C SampleOutputs Box html When the method returns the HTML report will be stored in the file Box htmi in the Sampl
333. re not easy to use in C The crnoarg provides a default value that allows the Printout method to ignore an argument that is missing After the report is generated the tcrreport interface is released At this point the reference count on the Report Object falls to zero and the object is deleted causing the corresponding print job to be closed If this step is omitted the Report O bject will continue to exist until the application terminates The client disconnects from the Report Server with the call to DisconnectFromReport Server If we wished we could re connect to a Report Server on another host with a subsequent call to connectReport Server If any method calls return a failure xREsutr control transfers to this handler with an instance of the crError which packages details of the error The call to the Report method is intended to display the error in an appropriate way The rcrapplication interface is released causing the reference count on the Application O bject to fall to zero prior to deletion At this point the client has relinquished all resources held on the Report Server and in the Automation Server The call counitialize matches the cotnitialize call made at Step 4 The nature of CO M s error reporting and use of sstr and vartant arguments make C automation controllers difficult to program In the example we used some simple wrapper classes to hide some of the implementation detail We ll take a brief look at th
334. red for some reason There are three possible values defined in the pcre h header file PE_NO_CONNECT Don t connect the client to the Report Server This value is used if the Load Balancer is to be used in manual mode The connection is made in a subsequent API call PE_DO_CONNEC Connect the client to the Report Server This is the default value PE_LB_CONNEC Connect the client to the Report Server using the Load Balancer Service in automatic mode The operation of the Load Balancer is described below in the section entitled Parallel Crystal Load Balancer Because C does not support default values for arguments you must supply a value for each To save typing we provide a convenience function called pztnitRemote that is defined as BOOL PEInitRemote const char host return PEInitialize NULL host 0 NULL PE_DO_CONNECT Parallel Crystal D eveloper s Manual 254 Version 2 4 Revised 5 27 00 To summarize here are some typical calls to the pEInitRemote and PEInitialize functions F F F E E Initialize an application client and connect to a PCRE Report Server on an unspecified host The client will use the default character based PCREAppConsole to report errors The call will return FALSE if there are no Parallel Crystal Report Servers running on your network BOOL bOK PEInitRemote NULL FF F F E aaah Initialize an
335. red to run them 2 If your client appears to block indefinitely inside a method then a third party component used by the Crystal Print Engine DLL may have created an error dialog that you are unable to see To diagnose this problem you need to get the System Administrator to run Parallel Crystal from the desktop so that all components are visible If a Crystal API call leads to an error dialog the Report Engine Server G UI will display the call and the dialog itself will be visible The Paralld C rystal System A dministrator s M anual describes how to run Parallel Crystal in desktop mode 3 Occasionally components of Parallel Crystal may crash or terminate abnormally To assist error diagnosis the Report Engine Server File Server and G ateway Servers generate log files that contain trace and error messages In addition components write error messages to the Windows NT event log The content of these log files is described in the Parallel Crystal System A dministrator s M anual Parallel Crystal D eveloper s Manual 229 Version 2 4 Revised 5 27 00 4 Occasionally a method may fail and report the error CORBA Error CORBA UNKNOWN The most likely cause is a Report Engine Server crash rendering the remote method that you are trying to call unknown 5 Occasionally amethod may fail and report the error CORBA Error CORBA NOIMPLEMENT This message means the method you are trying to call cannot be found in
336. regate of configuration strings PEGetPC REOutputDir Returns the PCRE Web Server output directory path REDORTempDir Returns the PCRE Data O bject Reporting temporary path Table 9 14 The entire collection of configuration strings can be retrieved in a single call to PEGetPCR PCRI PEInitialize NULL EConfigInfo info PEGetPCREConfigInfo PI EConfiginfo For example example2 host com 0 NULL PE_DO_CONNECT EGetConfigServer amp info Here is another example showing how to use the configuration information to set the Report Server s working folder to the installation s sampieReports directory PCREConfigInfo info PEInitRemote example2 host com PEGetPCREConfigInfo PEGetConfigServer amp info PEServerSetFolder PEGetServer info PCRESampleReportDir Parallel Crystal D eveloper s Manual 301 Version 2 4 Revised 5 27 00 Parallel Crystal Load Balancer When your client has access to a group of Report Servers you can use the Parallel Crystal Load Balancer service to ensure that the report processing load is distributed appropriately across the available server machines The load balancer provides two interfaces for automatic and manual use When you use automatic mode the client is connected to a Report Server chosen by the Load Balancer The choice is made by a selection algorit
337. rent and Application that respectively return the interface of the parent and root Application objects Given an interface such as ICRDataBase you use its Parent property to locate the interface on its parent Report Object and its application property to locate the interface on the Application Object You use the Parameters and Tables properties to create child D ataBase Parameters and D ataBaseT ables O bjects The upward links in the hierarchy guarantee that a parent object can never be destroyed until all its children are destroyed So the collection Automation O bject instances is created from the top down and dismantled from the bottom up An automation client MUST release every interface it acquires If you use Visual Basic VBScript JScript or Visual J interfaces are released automatically If you use Visual C you must release the interfaces yourself Interface properties and methods are specified with automation types BSTR VARIANT and vVARIANT_BOOL Every interface in the PCRE Object Model is a dual interface providing access to its methods and properties by both custom vtables and the dispatch mechanism All methods and properties that create child objects initially return a reference to the IDispatch interface on the object Y ou can access the custom interface by calling QueryInterface with the required interface identifier Conversions from dispatch to custom interfaces are made automatically by Visual Basic by casts in V
338. rget to specify the destination for your report In other words once it s generated where do you send it In the simple client line 6 specified that the final report was to be sent directly to a printer rather than be stored in a file If this line is omitted then the Print Engine D LL will raise an exception when the client executes the start command on line 7 Control will transfer to the handler on line 12 and the following line will be printed to the standard output stream Parallel Crystal D eveloper s Manual 237 Version 2 4 Revised 5 27 00 PCRE API error no print destination specified This message indicates that the Print Engine D LL could not figure out what to do with your report Y ou must respond by sending the report to a printer or to a disk file We ll explore the most common solutions in the next two sections Overall the simple client illustrates the importance of exception handling in Parallel Crystal client programming In general you should always ensure that calls to methods in the C Client Library are enclosed within an appropriate try catch block We ll describe the error handling facilities in the Client Library in more detail in the next chapter Generating a Simple PDF Report Adobe s Portable D ocument Format PD F is widely used as an alternative to PostScript or HTML on the Internet It provides PostScript quality reproduction which is far superior to HTML using a more compact document encoding
339. rint job When the print job is opened you supply the full path name of the report file on the Report Server e You must tell the Print Engine what to do with the report once it is generated e Ifyou want to print a PostScript report call the output Toprinter method of the PCREJob Class e Ifyou want to generate a PD F report call the output Toppr method and specify the full path name of the PDF file e If you want to generate an HTML report create an instance of a PCREHTMLJobExportOptions Class and supply the full path name of the HT ML file to the constructor Then call the export To method and pass the export info object as an argument e Report output files are not generated until the startgob method is called e You must enclose most PCRE method calls within try catch blocks in order to catch and handle exceptions raised by the C Client Library and the Print Engine D LL e The pecreappclient destructor automatically closes the connection to the Report Server If you create an instance of this class dynamically with new then you must have a corresponding call to delete S Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Using Parallel Crystal in a C Application When you use Parallel Crystal in a C application you customize and generate reports using a C language version of the PCRE API that is for the most part identical to the original Seagate Crystal Reports Print Engin
340. ript header Thirdly the VBScript language has only one data type called a varrant and does not understand even the simplest basic C types such as int and char Finally VBScript programs are not compiled in any conventional sense They are interpreted on demand when the web page in which they are embedded is loaded into the Microsoft IIS Web Server The solution to these problems called automation allows interpreted client languages to dynamically compose method calls at runtime using information about the interface recorded in a supplementary type library Interfaces that can be used in this way are called disp interfaces since they rely on a runtime dispatch mechanism to administer the call The methods of a disp interface are represented symbolically by numbers called DISPIDs and are constrained to use a single universal type called a varrant for their arguments and results COM contains a special generic interface called pi spat ch that dispatches calls through its invoke method An object that provides a disp interface is called an automation object and its clients are called automation controllers Automation controllers are called late bound clients because the methods they access are determined at runtime by their DISPID rather than at compile time by their identifiers Late bound clients are unfortunately very inefficient since every method call entails a translation of names into DISPIDs followed by a call to tnvoke that in turn
341. rmance not to run all of these systems in one machine since it can ease development and evaluation Parallel Crystal D eveloper s Manual 315 Version 2 4 Revised 5 27 00 The software picture on your Web Server looks like this Tuhi sie s The MAS PCRE Has ayaling T Audometion Server f F Comeon R apat E regi re The MAS Client software for ASP CHobki irii The ASP Application Script files provided The sequence of events to use an ASP reporting application is 1 The user points his browser at the URL for the script TutorialO ne asp 2 The script executes and makes the programmed calls on the Report engine 3 A Report output file is created if all goes well 4 An HTML response is sent to the user indicating success or failure 5 The user views the report results Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 316 Understanding a Simple Program The program is in VBScript and at the end we will show how it embeds into an Active Server pages script Before we go through it in detail here is the entire program On Error Resume Next Set App Server CreateObject MAS CRApplication 1 App ConnectToReportServer Tampa set Report App OpenReport c sampleReport box rpt Report ExportToHTML c temp out html PCREApp DisconnectFromReportServer This program is sufficient to cause a report to execute on the designated machine and produce its
342. rmatting D LL will store them in additional JPEG files created in the same directory If the name of the HTML file is Box ntm the JPEG files are named Box001 jpeg Box002 jpeg and so on The PEExportTo Call can be used to generate reports in many other formats and dispatch them to disk or to Email servers We ll describe these facilities in the next chapter 5 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Chapter 9 Using the C C Client Library This chapter describes the facilities provided in the C C Client Library The Parallel Crystal C C Client Library provides a range of report management facilities that you can use with C or C applications The library is accessed through a header file called pcre h that provides a set of C class headers or a set of ANSI C function prototypes depending upon whether you use aC or C compiler The two interfaces are functionally similar E nor Handling Console Management Service Providers PCREError PCREConsole PCREService PCREFatalError PCREAppConsole PCREServer PCREInternalError PCREGateway PCREClientError PCREConfigServer PCREGatewayError PCREServerError PCREAPIError Client Management PCRE API H elpers PCRE API PCREClient PCREExportOptions PCREEngine PCREAppClient PCREHTMLJobExportOptions PCREJob PCREPDFJobExportOptio
343. rom the Report Server Failure to connect to the Report Server or to locate the report file are indicated with appropriate error messages z Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 The components on the form are labeled as follows lblHost Host label txtHost Host text box lb1Report Report label txtReport Report text box cemdConnect Connect button cmdRun Run button cmdDisconnect Disconnect button w Parallel Crystal OF x Host beetle acme com Report C MobileApps pcre S ampleReports box pt Connect Ron Disconnect Figure 5 4 The code for the form contains the following outline sections Private app As ICRApplication P Ee Private bConnected As Boolean K Ri Private Sub setButtons cb As Boolean rb As Boolean _ 3 db As Boolean Private Sub Form_Load Private Sub Form_Unload Cancel As Integer Private Sub cmdConnect_Click Private Sub cmdRun_Click Private Sub cmdDisconnect_Click 0o u m A ns Each numbered paragraph below corresponds to the same numbered code statement 1 The global variable app holds a reference to the tcrapplication interface on the PCRE Application O bject The details of the interface such as its methods and properties are recovered from the Automation Server Type Library 2 The global variable bconnected is set to True when the client is connected to the Report Server and raise when it is disconnected Parallel Crystal
344. ror job goto close_job if PEStartPrintJob job TRUE ReportError job goto close_job printf Report generated n close_job if PECloseJob job ReportError job close_engine close_app PECloseEngine PEUninitialize Example 8 6 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 ECT bf bf r error function for brevity T 10 5 A PDF report is generated by calling pzoutput Toppr and supplying the job handle and the name of the PDF output file as arguments The PD F document is generated at Step 7 and is stored in the file c MobileApps PCRE SampleOutput Box pdf when PEStartPrintJob retums In order to display the file you must have access to a PDF viewer such as Adobe Acrobat Reader Most Internet browsers have this viewer pre installed as plugin The proutputToppr function uses the D ynalivery PD F Library that extends the Parallel Crystal Report Engine with facilities to render reports directly in PDF It is possible to provide a set of PDF output options as a third argument to proutputToppr but they require detailed knowledge of PDF and further discussion is deferred to the Chapter 9 In practice the default operating options are sufficient for most purposes and are automatically selected when the second argument to PEOutputToPDF is set to NULL Generating a Sim
345. rrentValueSet Report DefaultValueSet Application Kind Name NeedsCurrentValu Prompt ParameterFieldName ReportName ValueType Table 6 31 Interface acquisition Dim pfldc As ICRParameterFieldDefinitions Dim param As ICRparameterFieldDefinition Set pfldc report ParameterFields Set param pfldc Item 1 Set param pfldc 2 Collection iteration Dim pval As Variant For Each param In report ParameterFields If param NeedsCurrentValue Then param SetCurrentValue pval Else pval param CurrentValue End If Next Parallel Crystal D eveloper s Manual 210 Version 2 4 Revised 5 27 00 PDF Report Generation Parallel Crystal Report Servers can generate reports in PDF using direct and indirect formatting schemes The direct scheme uses the D ynalivery proprietary PD F Generation Library that generates PDF directly from the internal representation held in the report file The indirect scheme generates your report in a temporary PostScript file and then converts the file to PDF using a utility from A dobe called Acrobat Distiller The direct scheme is faster and is the recommended default Table 6 32 shows how these schemes are used by the various interfaces and methods in the Automation Server Interface Method PDF Generation Scheme ICRReport Output ToPDF Dynalivery PDF Library Export ToPDE Acrobat Distiller ConvertPSToPDF Acrobat Distiller Table 6 32 Direc
346. rtOptions options UXFXlsOptions formatOptions UXDMAPIOptions mailOptions strcepy options formatDLLName u2ftext d1ll options formatType UXFTextType options formatOptions void NULL strcpy options destinationDLLName u2dmapi dll options destinationType UXDMAPIType mailOptions toList director reporthost com mailOptions ccList mailOptions subject Box Office Report mailOptions message Here is your Box Office Report r n n mailOptions nRecipients 0 options destinationOptions void amp mailOptions job gt ExportTo amp options job gt Start In order to simplify the specification of output formats and destinations you can use a helper class called pcrEExport Options This class has constructors that fill in many of the default values for the PEExport Options struct for you leaving you with the task of invoking property methods to supply the remaining details For example you can use a PCRExportOpt ions helper to generate an Excel report as follows PCREJob job engine gt OpenJob C SampleReports Box rpt PCREExportOptions options PCREExportOptions crEFTExcel40 PCREExportOptions crEDTDiskFile options setDiskFileName C SampleOutputs Box xls job gt ExportTo amp options job gt Start Here the constants crEFTExce140 and crEDT
347. ry Corp Seagate Crystal Reports is a trademark of Seagate Software Inc Visibroker is a trademark of Inprise Corporation Other brand or product names are trademarks or registered trademarks of their respective holders Other brand or product names are trademarks or registered trademarks of their respective holders Dynalivery Corp 320 West Port Plaza Suite 205 St Louis Missouri 63146 USA Web http www dynalivery com Tel 314 205 8995 Fax 314 205 8622 Parallel Crystal D eveloper s Manual 2 Version 2 4 Revised 5 27 00 Table of Contents GOT Ge lp ir i elec A ees ihe c asa tics cesses EAEE S EE hen ES EA E EET EAEE EE A E E A ateelena OR Using our Web Site Email Tech Support Telephone Support Getting Softwate Updateswsteeniiaieranieaiiieeiinaiaian i a a a n a a a a 13 Why use Parallel Crystal senen uR E O EES EE E ET AES OE E at ata eee R 14 Report BASICS hae ranra Reano AEAEE EEE AET KAE DORESC PORE KATNE AVES AEEA ADNE AE EOE EECA E A EAEC ESEESE EIE Customizing REPOrts sec cccascovevaccasyeccasssy Levcoushenconsbndevasu sw eneses eu EAER E ET EERON TEAR EEE EOE Parallel Crystal Report Engine Advantages of Using a Report Server sc cecccecsavecccteccaccecvacs ceitvesdctceuscs iE seas vacendoreescievasutevrebciscauva duvevsoncdebevsdudsevaveccetavedesees 18 Distributed Report Server Processing o an atene erene EE ea en a Ee S AETA TAAA ETELA TEADS AA EAE EERTE E AEREE OERE Nre 21 Par
348. ryinfo ICRReport Summary Info is the custom interface exposed by the ReportSummary O bject The methods and properties are listed in Table 6 25 They provide access to summary information for the parent Report O bject such as author subject and title A Report Summary O bject is obtained from the report SummaryInfo property of the parent Report O bject Methods Custom Properties Navigation Properties Author Parent Comments Report Keywords Application Name Subject Template Title Table 6 25 Interface acquisition Dim info As ICRReportSummaryInfo Set info report ReportSummaryInfo Method and property calls info Title Sample Monthly Lists info Comments Just a demonstration Parallel Crystal D eveloper s Manual 205 Version 2 4 Revised 5 27 00 Parallel Crystal D eveloper s Manual 206 ICRExportOptions ICRExport Options is the custom interface exposed by the ExportO ptions O bject The methods and properties are listed in Table 6 26 They allow the output format and destination of the parent report to be specified An ExportO ptions O bject is obtained from the Export Options property of the parent Report O bject Methods Custom Properties Navigation Properties Reset CharFieldDelimiter Parent CharStringDelimier Report DestinationD11Name Application DestinationType DiskFileName ExchangeFolderPath ExchangeDestination ExchangePassword ExchangeProfile FormatD11Name FormatTy
349. rystal Reports e Methods to retrieve data from a data object which provide a means of describing a data object and giving access to the various data types it contains Implementing the DO RD ataSet interface is similar to implementing any other interface in Java Please see a java reference for the language specifics of this process The methods of the DO RD ataSet interface can be devided into 3 groups e Descriptive e Data Retrieval e Administrative Parallel Crystal D eveloper s Manual 82 Version 2 4 Revised 5 27 00 Descriptive Group getColumnCount returns the number of columns in your data set getColumnDisplaySize int if the column is a string or similar displays the width of the field getColumnLabel int returns the name of the column getColumnType int returns the data type constant for that row Data Retrieval Group Each of these methods attempts to retum the data element in the current row and the column specifed by the int argument as a specific data type If the specified element cannot be retrieved as the given type then an exception should be thrown For example if getInteger was requested on a data element that was a String since String data can t be represented very well as an integer then that method should throw an exception in that case tBlob int tBoolean int tByte int tCurrency int tDate int tDouble int tInteger int tMemo int tShort int tStri
350. s public int numberOfProcessors Number of host processors public String gatewayName Gateway Server name public String reportServerAddress Report server address Parallel Crystal D eveloper s Manual 104 Version 2 4 Revised 5 27 00 The Report Server s load factor is given by the value of the 1oadFactor member and is currently equal to NumberOfServers NumberOfHostProcessors The information given in the pcrEReportServerInfo is subject to change but is correct at the time of writing Tf you supply a host in the pcreapplicationClient OF PCREAppletClient constructor call then your client will use the Load Balancer service running on that host However the host settings for the G ateway and Configuration Servers are revised automatically whenever the client completes the connection to the selected Report Server In order to use the Load Balancer your Parallel Crystal installation has to be configured to run this service If the Load Balancer is not running then calls to RequestReportServerList and connect will throw a pcreserverError exception with the message Server error cannot connect client to Load Balancer service Parallel Crystal D eveloper s Manual 105 Version 2 4 Revised 5 27 00 Multi threaded Clients In Java support for multi threaded programming is provided in both the language and its platform dependent implementation The language provides simple syn
351. s Visual C and Visual J Error handling is provided using the standard CO M interfaces for providing error information Future versions of Parallel Crystal may add support for Java Beans and additional WebA S specific frameworks to the component layer Some final points about layered architecture and various client frameworks e The client frameworks provided span Microsoft and non Microsoft technologies For example you can choose whether to use Java via Microsoft Visual J or whether to use a 100 pure Java solution such as the Sun JDK e The C client framework has a small footprint and does not introduce dependencies upon any particular C development environment e Neither the C nor the Java client frameworks make assumptions about the end user application They can be used in graphical and non graphical applications e All client frameworks are thread safe In particular the ActiveX Automation Server conforms to the Apartment Level Threading Model required by Microsoft Active Server Pages and the C and Java clients support the construction of multi threaded applications Parallel Crystal D eveloper s Manual 26 Version 2 4 Revised 5 27 00 Parallel Crystal PDF Library Parallel Crystal provides users with a form of output known as PD F Portable Document Format This output is useful when exacting detail is required for reports because the report looks the same and prints the same from any type of computer
352. s a problem you will get an error message box and you will be in the best position to adjust the report or the machine s data sources and retest Embedding the Program in a Working ASP Page A copy of this ASP script with error handling is in the file TutorialO ne asp supplied with Parallel Crystal lt HTML gt lt HEAD gt lt SCRIPT LANGUAGE VBScript RUNAT Server gt On Error Resume Next Set App Server CreateObject MAS CRApplication 1 App ConnectToReportServer Tampa set Report App OpenReport c sampleReport box rpt Report ExportToHTML c temp out html App DisconnectFromReportServer lt SCRIPT gt lt HEAD gt lt BODY gt lt BODY gt lt HTML gt You also need a global asa script Since we are trying to keep things simple in Tutorial One this file simply says to do nothing at session and application birth and death lt SCRIPT LANGUAGE VBScript RUNAT Server gt Sub Session_OnStart End Sub Sub Session_OnEnd End Sub Sub Application_OnStart End Sub Sub Application_OnEnd End Sub lt SCRIPT gt Parallel Crystal D eveloper s Manual 320 Version 2 4 Revised 5 27 00 Finally let s add basic error handling and tracing so that we obtain feedback on what happens lt HTML gt lt HEAD gt lt SCRIPT LANGUAGE VBScript RUNAT Server gt sub CheckResponse comment if Err Number 0 then Response write comment
353. s constituent fields Methods Custom Properties Navigation SetLogOnInfo DescriptiveName Fields TestConnectivity D11Name Location Parent LogOnDatabaseName Report LogOnUserID Application Name SessionUserID Type Table 6 18 Interface acquisition Dim dbtblc As ICRDataBaseTables dbtable As ICRDataBaseTable Set dbtblc db Tables Set dbtable dbtblc Item 1 Set dbtable dbtblc 2 Collection iteration For Report End If Next Each dbtable In db Tables If Not db table TestConnectivity Then Cannot logon to table Error amp dbtable Name B Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 ICRDataBaseFieldDefinition s ICRDataBaseFieldDefinitions is the collection interface exposed by the DatabaseFields Collection O bject The methods and properties are listed in Table 6 19 A DatabaseFields Collection Object is obtained from the ricids property of the D atabase Table O bject Each item in the collection is a D atabaseField D efinition O bject representing a field within the database table and the number of D atabaseField D efinition O bjects is returned by the count property Individual D atabaseField D efinition O bjects are obtained by the Item Method that takes an index or argument identifying the field required Visual Basic clients may iterate through all items with the For Each Statement that calls the New property to create an enumeration
354. s information for the n th table in a struct called PELogonInfo int nTables job gt GetNTables for int i 0 i lt nTables i PELogOnInfo info job gt GetNthTableLogonInfo i amp info cout lt lt Table lt lt i lt lt lt lt info ServerName lt lt lt lt info DatabaseName lt lt lt lt info UserID lt lt lt lt info Password lt lt endl The methods GetNthTableSessionInfo and GetNthTableLocation use similar helper structs called pESessionInfo and PETableLocation to return their results SQL Queries The following group of methods allows you to access the SQL Query string associated with your report Get SOQLQuery SetSQLQuery The following fragment shows how to retrieve and reset the SQL query char query job gt GetSQLQuery cout lt lt SQL Query lt lt query lt lt endl GlobalFree query job gt SetSQLQuery SELECT FROM CUSTOMER Parallel Crystal D eveloper s Manual 282 Version 2 4 Revised 5 27 00 Sort Field Manipulation The following group of methods allows you to retrieve and set the sorting fields for the records and groups within your report GetNSortFields GetNthSortField SetNthSortField DeleteNthSortField GetNGroupSortFields GetNthGroupSortField SetNthGroupSortField DeleteNthGroupSortField Sort fields are accessed by an index that ranges from o to GetNSortFields 1 T
355. s of the formal parameters Y ou will need to consult the online documentation for the PCRE Automation Server to get a complete description of each method and its parameters Generating PDF and HTML Reports with Visual J The rcrReport interface provides several methods that make it easy for you to generate reports in other formats In each case the call to Printout in Step 7 in the preceding example is replaced with one that generates the report in the appropriate format In particular e To generate a report in PDF and save the results replace the call to printout with the following call to output ToPDF Step 7 report OutputToPDF C SampleOutputs Box pdf When the method returns the PDF report will be stored in the file Box pdf in the SampleOutputs directory e To generate a report in HTML and save the results replace the call to printout with the following call to Export ToHTML Step 7 report Export ToHTML C SampleOutputs Box htmL When the method returns the HTML report will be stored in the file Box htmi in the SampleOutputs directory If the report has embedded images the corresponding JPEG files will be stored in the same directory e To generate a report in PostScript and save it in a file replace the call to printout with the following call to output ToPs Step 7 report OutputToPS C SampleOutputs Box ps The report will be generated in the file Box ps in the s
356. s represented by a single method called Rungob that we ll expand below The purpose of the overriding init method is to establish the user interface provided by the applet This may be a simple text panel to display messages or something much more complicated Whatever you decide you need to have at least elementary knowledge of Java user interface programming to provide the implementation of this method Remember init is called when the applet is first loaded into the browser So it seems appropriate to build and display the user interface at that point amp Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 10 The start o method is called each time the browser displays the page containing the applet This means it is called immediately after init and each time you subsequently return to the page Within the framework illustrated the purpose of start is to create a PCRE applet client and connect it to a Report Server The connection will exist for as long as the applet is displayed 11 The purpose of the stop method is to break the connection established by start This means that whenever you navigate away from the page the Report Engine allocated to the applet client is terminated and the applet client is destroyed When you navigate back to the page the browser will invoke start again anda new applet client will be connected to a new Report Engine on the Server 12 The destroy method
357. s to the Parallel Crystal Report Engine Server The Report Engine Server provides the report customization and generation functionality that you use to generate reports PCREConfigServer The PCREConfigServer class provides client access to the Parallel Crystal Configuration Server The Configuration Server provides information about the current configuration of your Parallel Crystal installation PCRECustomServer The pcrECustomServer Class provides special purpose functionality to clients Its function may vary depending upon your installation Parallel Crystal D eveloper s Manual 56 Version 2 4 Revised 5 27 00 Using Get property Methods The following fragment shows how the get property methods can be used to access the Gateway and Configuration servers PCREApplicationClient client new PCREApplicationClient PCREGateway gateway client getGateway PCREConfigServer config client getConfigServer The pcREApplicationClient and PcREAppletClient Classes are responsible for managing the life cycles of the service providers they contain You should not attempt to create a service provider independently or access its methods after you have called the client s Disconnect Or Quit methods The pcreGateway and pcREServer providers are described briefly in the next two sections The pcreconfigServer is described in the section entitled Parallel Crystal Configuration Server If you don t plan to use th
358. s with Visual Basic cccescssessceseeseeseeseceeceseeseesecsecsececeesecsecsecsececeeaeeseesesseceeceeeeaeeaeeaeeneeeaes 158 Haridling Errors from Visual Basic is ci ci dieesssceeccscsus ccseavev iata Kaeni aiee s RNE TEER ES EVE NEEE AET 159 Trouble Shooting Simple Visual Basic Clients 0 ccececcescssseeeceseeseeseeseesecseceeeseeseesecaeeseceaeeaeesecsecsecaeseseaeeaeeaecseeeeseaeeaeeaeeaeeeeeee 160 Using Parallel Crystal with Active Server PAQ S scssccsccsssseesseseessenecseceseeseeseesecsecseeceesesseeseesecseceeeseeseeaeesecseesecseeeaeeaeeaeeaeserseaeeaeens 162 ASP Preliminari eso EAA KA NATE OE AERIENE TEE E 165 Generating HTML Reports with ASP 166 Retrieving Reports with ASP eee 173 Generating PDF and PostScript Reports with ASP 175 Handling Errors from ASP 2 0 s iisissessosasacsscsasecs cesasasevevssavs ceca sacascvegavavcossasancangavavesvasancnsaaseansaiauancpesuseensavavasesavasdeieeaavatesarveaesesesates 176 Trouble Shooting Simple ASP Che mts 2 wssccseisecscvececsecsavexcvesveesiccevenvcucodeieconsodeervvasdedersendeosvenpetesvansacesband evneancarevvauabevveencendseasses 177 Chapter 6 Using the PCRE Automation Server sssscsssssssssssssssssssssssscsssesssssesssssesesssssssessseassssessasessessssesscssssasessessassssesseseseeeee 179 Automaton Server CUERIS ies ereo are Eeee EAS a AA ssuvarcatuviaseassvondstosvuasetovtunssesvededuasvbuidiceruuedsesnsuseicuvutedte urges sepsntesosei sete reise 180
359. scribes how to build software from re usable object based components Automation describes interfacing mechanisms that allow components to be controlled or automated from high level macro or scripting languages such as Visual Basic The Parallel Crystal Automation Server provides a set of automation objects whose methods and properties allow CO M enabled clients to access Parallel Crystal Report Servers The object collection is hierarchical and reflects the logical structure of a Seagate Crystal Reports D ocument The following sub sections provide preliminary material on COM Automation and the Automation Server Y ou l find references to recommended textbooks for all the major Microsoft CO M development tools later in the Chapter Microsoft COM The Component O bject Model specifies the requirements for binary re usable object based software components called COM objects These requirements include e COM objects are specified by an interface that is a list of methods and properties The properties embody the state of the object and the methods describe its functionality Interfaces are expressed in the COM Interface D efinition Language ID L that allows the methods properties and parameters to be described in a C like syntax COM interfaces have names beginning with a capital I such as tcrapplication e COM objects enforce data encapsulation by exposing only their interfaces Clients have no access to their data members a
360. scribes how to write Visual J clients that use the PCRE Automation Server to generate simple reports in PostScript PDF and HTML Since there is no direct Java interface to CO M ActiveX Visual J provides a Type Library Wizard that generates Java wrapper classes for the interfaces provided by the Automation Server These classes hide the details of COM completely so that you need only understand how to use the methods of the tcrapplication and ICRReport interfaces in order to generate simple reports Visual J Preliminaries In order to use the PCRE Automation Server you must generate the Java wrappers and import them into your project as follows First check that PCRE Automation Server has been installed AND registered on the machine running Visual J Run Visual J and create or select your Java project Select the Visual Studio menu entry Tools Java Type Library Wizard A list box appears similar to the one shown in Figure 5 2 on page 146 Search for the entry cpemasi 1 0 Type Library and check the box to the left Click on OK This causes the Type Library Wizard to read the PCRE Automation Server Type Library which is held within the cpemas1 DLL and to generate a wrapper class for each interface in the library The wrappers are compiled and stored in the sub directory cpemas1 of the Visual J trusted library at C WINNT4 0 Java TrustLib You do not have access to the Java source code for the wrappers However t
361. sgBox app GetLastErrorString End Sub The procedure checks the report file path name has been specified and then calls the Application O bject s openreport method This method opens a print job in the Report Engine Server and returns a reference to the rcrreport interface on the corresponding Report O bject The details of the interface such as its methods and properties are recovered from the Automation Server Type Library Parallel Crystal D eveloper s Manual 157 Version 2 4 Revised 5 27 00 Parallel Crystal D eveloper s Manual If the report is opened successfully the method printout is called to generate and print a PostScript version of the report The method returns when the report has been generated When the control returns from the procedure the report variable is implicitly reset to Nothing This releases the interface causing the Automation Server to close the print job in the Report Engine Server and delete the Report O bject Note that on return from this procedure the client is still connected to the Report Server If the Run button is pressed again a new report will be generated using the path name currently entered in the Report text box 8 The procedure cmaDisconnect_Click is executed when the Disconnect button is pressed Private Sub cmdDisconnect_Click On Error GoTo fail app DisconnectFromReportServer setButtons True False Fals bConnected False Exit Sub fail sgBox app Get
362. ssor Report Servers B Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Formula Manipulation The following group of methods allows you to retrieve and adjust the formula fields and record or group selection formulae in your report GetNFormulas GetNthFormula GetFormula SetFormula CheckFormula GetSelectionFormula SetSelectionFormula GetGroupSelectionFormula SetGroupSelectionFormula CheckGroupSelectionFormula Formula fields are accessed by an index that ranges from o to GetNFormulas 1 The retrieval methods return a string that is allocated with the Win32 function GlobalAlloc You should release the string with a corresponding call to GlobalFree The following fragment returns all the formula fields in a report int nFormulas job gt GetNFormulas for int i 0 i lt nFormulas i char nameBuffer formulaBuffer job gt GetNthFormula i nameBuffer formulaBuffer cout lt lt n lt lt i lt lt name lt lt nameBuffer lt lt formula lt lt formulaBuffer lt lt endl job gt StrFr nameBuffer job gt StrFree formulaBuffer The methods Get Formula and Set Formula allow formula fields to be accessed by name rather than index The remaining methods have simple get and set methods Parameter Field and Stored Procedure Manipulation The following group of methods allows you to manipulate the parameter fields and stored pr
363. stablished by any calls to the selectPrinter method of PCREJob Parallel Crystal D eveloper s Manual 314 Version 2 4 Revised 5 27 00 Appendix A Simple ASP VBScript Tutorial Overview N ote The files for this tutorial are located in the M obileA pps PC RE A utomation Server V isualBasic Tutorial directory A dditional N ote TheMA S A utomation Server does not support the Seagate Smart V iewer The MAS PCRE product offers a variety of clients that are designed to facilitate report generation in an N tier or multiple tier client server environment This document describes how to use one of them the MAS PCRE Automation Server client to generate a report under Microsoft Active Server Pages using VBScript The context is Active Server Pages 2 0 as supported by IIS 4 0 ASP is an ISAPI application running under IIS which is designed to construct scripts of considerable power by interfacing to external COM compliant software components such as the MAS client A typical reporting system based on ASP will involve two or more computers Logically there are four systems involved End User using a browser in mele ct Web Sewer mening Report Se e Database Sawar and aun the ASP script om tha Web ASP 165 and tha runing MAs Seiver MAS chal Paralel Crystal Ragot angine This is the most efficient configuration with server machines performing the roles for which they are optimised However there is no reason apart from perfo
364. start method If your report requires access to a database server then you must call the Logonserver method before calling openJob Or PrintReport NthTableLogon methods allow per table database connections Since you only have access to a single report engine it is only possible to open a single database connection at a time You should call the corresponding LogOf Server method when your report has been generated The ciose method closes the engine and releases resources within your Report Engine Server You cannot subsequently call any of the report management methods unless you re open the engine with another call to open Parallel Crystal D eveloper s Manual 273 Version 2 4 Revised 5 27 00 The following code fragment shows some typical calls to the pcREEngine methods PCREAppClient client try PCREServer server client getServer client getServer gt setArguments folder C MobileApps pcre SampleReports client Connect PCREEngine engine client OpenEngine Generate the Box Office report engine gt PrintReport Box rpt Customize Box Office report PCREJob job engine gt OpenJob Box rpt job gt OutputToPDF C MobileApps pcre SampleOutput Box pdf null job gt Start job gt Close Finished with print engine engine gt Close catch PCREError e e Report The lif
365. t report error if PEInitAPI PCREAPI report error API calls PEUninitialize 8 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 4 You tried to connect using the Load Balancer but the Load Balancer could not locate any Report Servers In this case it is possible that the Report Servers were not configured to use the Load Balancer Service or there is an inconsistency in the way the Load Balancer Service has been configured Y ou should get your System Administrator to check the current Load Balancer configuration If the problem persists the causes may be more obscure First you should check the status of the O SA gent that administers client server connections by keeping a dynamic record of the CORBA servers running on your network The following problems can arise with O SA gents 5 If there are no O SAgents running on your network then no client will be able to connect to a Report Server Y our application may hang for around 15 seconds before you get a message from the CORBA implementation indicating that an O SA gent could not be found Normally you require at least one Report Server to be running the O SAgent O SAgents communicate with CO RBA clients and servers by listening for UD P broadcasts on port 14000 Sometimes its useful to be able to modify this port number either because its already in use or to form a separate domain in which your client
366. t 1 Parallel Crystal C clients use a Parallel Crystal Client Library called cppclient d1l In order to access the classes in the library you must include the header file pcre h into your program at compile time and you must ensure that the installation directories C MobileApps pcre CppClient include C MobileApps pcre Visigenic vbroker include are on your include path 2 The declaration creates an instance of the pcrEaAppclient Class The constructor call specifies the host name of the machine running the Parallel Crystal Report Server as an argument string The value example host com is fictitious and you must supply a valid host name if you are trying out this code for real 3 This statement connects the client to the Report Server running on the machine specified in Step 2 It is included in a try catch block so that if the call to connect fails and an exception is raised then control will transfer to the exception handler at statement 11 We ll discuss connection failures in detail in the next chapter but the most common reasons are that the Parallel Crystal Report Server is not running on the machine identified by the host name or an incorrect host name was specified 4 This statement declares a reference to a PCRE print engine The reference is initialized with the value returned by the call to the openEngine method of the client In statements 2 through 4 you can see a progression get a client connect the client to
367. t nFormulas i nameBuffer setLength 0 formulaBuffer setLength 0 job GetNthFormula i nameBuffer formulaBuffer System out printin n i 4 name nameBuffer formula formulaBuffer The methods Get Formula and Set Formula allow formula fields to be accessed by name rather than index The remaining methods have simple get and set methods Parameter Field and Stored Procedure Manipulation The following group of methods allows you to manipulate the parameter fields and stored procedure parameters in your report GetNParameterFields GetNthParameterField SetNthParameterField GetParameterField SetParameterField Parameter fields are accessed by an index value ranging from o to GetNParameterFields 1 TheGetnthParameterField method accesses the n th field and returns its attributes in a helper class called pcrEParameterFieldiInfo Parallel Crystal D eveloper s Manual 75 Version 2 4 Revised 5 27 00 The following code fragment sets the value of a report s parameter PCREParameterFieldinfo pinfo job GetNthParameterField 0 PCREValueInfo value pinfo CurrentValue value viString Parameter value pinfo CurrentValue value pinfo CurrentVlueSet true job SetNthParameterField 0 info The GetParameterField and setParameterField methods allow more convenient access by using the name of the field rather than its index value The
368. t Customization API for C clients is exposed through the methods of the pcreEngine and pcrEJob Classes These classes partition the API into two parts methods that are report engine related and methods that print job related In this section we ll give a general overview of each class and provide some additional information on how to generate reports in particular formats To understand the class interfaces in depth you should consult the documentation supplied online with Parallel Crystal Assuming installation on drive C this is located in the directory C MobileApps pcre docs where you should find the following files CppAPIDocumentation index html is the root index to the PCRE package documentation The documentation is formatted and cross referenced in a format similar to the JavaD oc standard e developr hip is the Windows help file for the Seagate Crystal Reports Print Engine API You may need to consult both files to understand how the customization function is mapped to an equivalent method of the pcreEngine OF PCREJob Classes Accessing Report Engines and Print Jobs Once you have connected your C client to the Report Server you get a reference to the Report Engine by calling the client s openEngine method PCREAppClient client xy client Connect PCREEngine engine client OpenEngine run print jobs engine gt Close catch PCREError amp e
369. t PD F generation using output ToPDF has already been described in the previous Chapter The equivalent indirect method Export Toppr is used in the same way For example Visual Basic Dim app As ICRApplication report As ICRReport report app OpenReport C SampleReports Box rpt Direct generation with Dynalivery PDF Library report OutputToPDF C SampleOutputs Boxl pdf Indirect generation with Acrobat Distiller report ExportToPDF C SampleOutputs Box2 pdf Although outputTopor is the faster of the two methods export Toppr may be preferable if your report is image rich In general we recommend that you try output Topo first of all and then use Export TopoF if the results are not satisfactory Parallel Crystal D eveloper s Manual 211 Version 2 4 Revised 5 27 00 Parallel Crystal Configuration Server When Parallel Crystal is installed a number of directories are created with sample Crystal Reports and demonstration materials In order to help you locate path names for these directories Parallel Crystal incorporates a Configuration Server that returns configuration and installation dependent information to the client Automation clients access the Configuration Server through the properties of the ICRServer interface that is returned by the serverSettings method of the ICRApplication interface serverSettings is declared as follows Visual C HRESULT get_ServerSettings LPDISPATCH pConf
370. t code that is tested with the macros succezbep and Farren Consult a COM book for further details 3 Itis good COM programming practice to initialize variables that will receive interface pointers to NULL 4 TheCOM API must be initialized with a call to cotnitialize If the call succeeds a matching call to couninitialize must be made before the application terminates 5 Thecall to cocreateInstance connects the client to the PCRE Automation Server The call uses the CLSID supplied as the first parameter to locate the path name of the cpemas1 d11 in the registry The DLL is then loaded into your process so that interface method calls can be made The call will fail if the D LL is not located on the client machine or if the necessary information is not in the system registry Otherwise it will return a pointer to the tcrapplication interface 6 The methods invoked through a COM interface are not allowed to throw exceptions In order to simplify flow control the client tests the nresuLTt and throws a local exception for those that fail The exception is an instance of a helper class called CRError 7 COM API calls take pointers to wide character strings rather than C style character strings In addition disp interfaces used by automation objects use a special kind of wide character string called a estr that is identical to Visual Basic s st ring data type Raw pstr s are rather tedious to program and so the e
371. t for the report specified by the ReportPath argument Once more it is necessary to use rsob ject to test the result since the method will fail if the file specified by the argument does not exist 15 The export Toutmt method of the Report O bject generates the report and exports it to the file specified by the outputPath argument Note that the HTML file is generated on the Report Server and not on the Web Server where the script is running We ll discuss various options for retrieving the file below 16 If the call to export TonTmi executes successfully a final confirmation message is written to the response page 17 It is extremely important to disconnect from the Report Server before the script terminates However we test the pcrEApp reference for validity first of all Note that inspecting box is not good enough because we could have a situation in which PCREApp Was Valid but box was False because a subsequent call to the Report Server failed 18 The call to set PCREApp tO Nothing releases resources in the PCRE Automation Server In the following sections we ll discuss various issues relating to report retrieval and error handling and show how the script can be trivially changed to generate reports in other formats Retrieving Reports with ASP If the Report Server and the Web Server run on different machines then you need to retrieve the generated report back to a suitable location the Web Server before yo
372. t include the Automation Server s message and you have to recover this in a context dependent way yourself For example the RunReport procedure from Example 5 2 on page 136 could be re written as follows static void ReportError LPCSTR source LPCSTR msg cout lt lt source lt lt lt lt msg lt lt endl static void RunReport void ICRApplicationPtr pApp __uuidof CRApplication try pApp gt ConnectToReportServer flea acme com _bstr_t name C SampleReports Box rpt ICRReport report static_cast lt ICRReport gt pApp gt OpenReport name try report gt PrintoOut catch const _com_error e ReportError e Source report gt LastErrorString report gt Release pApp gt DisconnectFromReportServer catch const _com_error e ReportError e Source app gt LastErrorString Parallel Crystal D eveloper s Manual 142 Version 2 4 Revised 5 27 00 The respective catch clauses access the LastErrorString property of the ICRApplication OF ICRReport method and the message is reported by the procedure ReportError Notice that the helper classes generated in the t1i n header file allow the LastErrorString property to be accessed as if it was a data member Trouble Shooting Simple C COM Clients In this section we ll look at the most common errors that occur when programming simple clients using C with the Automation Server We
373. t stream PCRE API error invalid file name The PCRE API error prefix indicates that the Print Engine D LL raised the error Generally this is an indication that something went wrong in a Print Engine API call and the most likely cause is an invalid argument value Unfortunately the error messages returned by the Print Engine D LL are quite terse One way to compensate for this is to enclose smaller groups of calls within separate try catch blocks so that you can be sure which call failed Missing Report Destination Specification A third error that is easy to make is to forget to specify the destination for your report In other words once it s generated where do you send it In the simple client line 6 specified that the final report was to be sent directly to a PostScript printer rather than be stored in a file If this line is omitted then the Print Engine D LL will raise an exception when the client executes the start command on line 7 Control will transfer to the handler on line 12 and the following line will be printed to the standard output stream PCRE API error no print destination specified This message indicates that the Print Engine D LL could not figure out what to do with your report Y ou must respond by specifying output to a printer or to a disk file We ll explore the most common solutions in the next two sections Overall the simple client illustrates the importance of exception handling in Parallel Crystal
374. t to report catastrophic errors An internal error usually indicates a logic failure within the code while a fatal error indicates an external condition that makes it impossible to continue When handling these errors you should normally terminate your application in an appropriate way In addition to its constructors each error class has a set of methods for throwing and reporting errors The report methods use a corresponding method in the pcrEconsole class to display the error message So if you call the Report method of PCREAPIError then this method will in turn call the pcre API ErrorMsg method of the client s console The hierarchy of error classes allows you to distinguish between various kinds of errors and to handle them individually or as a group For example in most of the programming examples we have used a simple try catch block in the following way PCREAppClient client example2 host com try client Connect PCREOpenEngine engine client Open Open job do API calls engine gt Close catch PCREError amp e e Report Although this code is correct errors with very different causes will transfer control to the same exception handler and this may leave your program in an uncertain state We can be more discriminating in the treatment of errors by using specialized try catch blocks in a variety of ways
375. t to a disk file then the dest inationOptions member should be a pointer to a uxpDiskoOptions struct that holds the path name of the file to be created In Table 9 9 on page 277 we list the possible values for format DLLName the corresponding sub type values and the format dependent helper structs Then entry none means that the format options member should be set to nui Parallel Crystal D eveloper s Manual 276 Version 2 4 Revised 5 27 00 DLL Name Format Sub type Format Options u2fcer dll UXFCrystalReportType none u2fdif dll UXFDIF Type UXFDIFOptions u2Zfrec dll UXFRecordType UXFRecordStyleOptions u2frtf dll UXFRichTextFormatType none u2fsepv dll U XFCommaSeparatedType XFTabSeparatedType XFCharSeparatedType UXFCommaTabSeparatedOptions UXFCommaTabSeparatedOptions UXFCharSepatedOptions u2ftext dll XFTextType XFTabbedTextType UXFPaginatedTextOptions UXFPaginatedTextType u2fwks dll UXFLotusWksType none UXFLotusWkilType UXFLotusWk3Type u2fwordw dll UXFWordWinType none u2fdoc dll UXFWordDosType none UXFWordPerfectType u2fgqp dll UXFOP5Type none u2fxls dll UXFX1s2Type UXFXlsOptions UXFX1s3Type UXFX1s4Type UXFX1s5Type UXFXls5TabType u2fhtml dlil UXFHIML3Type UXFHTML30ptions u2fmaspdf dl1l UXFPDFDistillerType UXFPDFOptions Table 9 9 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 277
376. tPrintJob or one of the APIs the report will be generated and then retrieved to the file specified on the client The following example shows how the service is used to return a PDF report to the client machine Some implementation details such as ReportError have been ommitted include lt pcre h gt include lt stdio h gt void main int argc char argv short job BOOL bOK PEInitialize NULL example host com argc argv PE_DO_CONNECT if boK ReportError 0 goto close_app Enable report retrieval PESetRetrieveMode TRUE if PEOpenEngine ReportError 0 goto close_app job PEOpenPrintJob C MobileApps PCRE SampleReports Box rpt if job ReportError job goto close_engine Parallel Crystal D eveloper s Manual 296 Version 2 4 Revised 5 27 00 Specify output file on client machine if PEOutputToPDF job C MyReports Box pd f NULL ReportError job goto close_job if PEStartPrintJob job TRUE ReportError job goto close_job printf Report generated n close_job if PECloseJob job ReportError job close_engine PECloseEngine j close_app PEUninitialize Automatic report retrieval is enabled by the call to ppset Ret rieveMode after the client is initialized The report is retrieved to the fi
377. takes care of de allocation automatically which is particularly convenient in applications where exceptions will be thrown However you have to be careful In the example the strings host and name are not de allocated until the try block is exited at Step 15 Parallel Crystal D eveloper s Manual 131 Version 2 4 Revised 5 27 00 2 Handling COM Error Results In order to re package return codes as exceptions we followed each method call with a statement like if FAILED hr throw CRError where the crError Class is used to capture the details of the error This class is defined as follows class CRError public CRError const char msg m_msg msg CRError ICRApplication pApp BSTR str HRESULT hr pApp gt get_LastErrorString amp str m_msg str SysFreeString str CRError ICRReport pRpt BSTR Sir HRESULT hr pRpt gt get_LastErrorString amp str m_msg str SysFreeString str CRError const CRError msg m_msg msg operator CRStr const return m_msg ostream amp Report const return cout lt lt char m_msg lt lt endl private CRStr m msg When the constructor is called with a string argument the string is copied and stored in the m msg member However when the constructor is called with an ICRApplication OF ICRReport interface pointer get_ LastErrorString retrieves the error message generated by the
378. tested using the default err object We ll consider various options for error handlers in the next section This statement connects the script as a client of the PCRE Automation Server CreateObject isamethod of the built in server object that loads the Server DLL and stores a reference to the Application O bject in the variable pcreapp The string argument to createob ject is the Automation Server s procrp It corresponds to an entry in the System Registry that should be established at installation time We ll return to this topic in Chapter 7 Notice that the box flag is used to control execution of the remainder of the script If this variable becomes raise then control falls through to Step 17 If the call to createob ject fails then the result will not be a valid reference The IsObject function provides a way to test for this possibility If the test fails the error message is inserted into the response by the call to ReportError Parallel Crystal D eveloper s Manual 172 Version 2 4 Revised 5 27 00 13 Once aconnection to the Automation Server is established the script calls the Connect ToReport Server method passing the host name as an argument It is vital to check the result since the name supplied might not be valid or the Report Server might not be running on the nominated host 14 If the connection to the Report Server is established the openReport method is used to return an instance of the Report O bjec
379. th a call to the pcregob Start method a PostScript report is generated first and then translated into PD F using Adobe s Acrobat Distiller tool This provides an alternative method for PD F generation which can occasionally compensate for deficiencies in the O utputT oPD F method described previously pcREExport Options is used to generate PD F as follows PCREJob job engine gt OpenJob C SampleReports Box rpt PCREExportOptions options PCREExportOptions crEFTPDFDistiller PCREExportOptions crEDTDiskFile options setPDFFileName C SampleOutputs Box pdf job gt ExportTo amp options job gt Start The helper class pcrEPDFJobExport Options allows this code to be abbreviated to a single constructor call specifying the name of the PDF output file PCREPDFJobExportOptions options C SampleOutputs Box pdf job gt ExportTo amp options job gt Start A similar helper class called pcREHTMLJobExport Options is available for generating reports as HTML documents This class was used in Example83 above This class is a specialization of PcREExport Options that automatically sets the formatting DLL to u2fhtm1 d11 and the destination DLL to u2ddisk dii Note that the version of u2fhtm1 d11 supplied with Parallel Crystal yields performance improvements when rendering image rich reports on multi proce
380. the Report Server and acquire a Parallel Crystal Report Engine e Clients use the openReport method of the tcrapplication interface to acquire a reference to one or more Report O bjects Clients can then customize and run these reports through the methods and properties of the rcrReport interface e The rcrreport interface conveys the structural composition of a report through a generic automation interface called a collection Collections are designed to be used with the Visual Basic For Each statement that allows clients to iterate through each member in turn Collections are identified by the rounded boxes in Figure 5 1 and by pluralized interface names e Child objects are created with properties that allow their immediate parent the associated report object and the root application object to be located e All interfaces are derived from tpispatch so that they are accessible from automation clients such as VBScript that cannot use custom v tables The Parallel Crystal O bject Model is based closely on the O bject Library distributed with Seagate Crystal 6 and 7 1 However the PCRE Object Model contains extra methods to provide Parallel Crystal functions relating to remote connection report retrieval and load balancing and also omits many methods in the Seagate Library that are concerned with Report Design The Parallel Crystal O bject Model is implemented by a component of the Parallel Crystal Client Distribution called the Parallel
381. the collection The methods and properties are listed in Table 6 6 They provide access to the area properties and its constituent sections Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Methods Custom Properties Navigation Kind Sections GroupNumber Options CopiesToPrint GroupOptions Parent Report Application Table 6 6 Interface acquisition Dim Set Set ac As ICRAreas areal As ICRArea area2 As Area ac report Areas areal ac Item 1 Set area2 ac 2 Collection iteration For Nex Each area In report Areas Select Case area Kind Case CrReportHeader To CrGroupHeader Case CrDetail Case CrGroupFooter To CrReportFooter End Select t ICRAreaOptions ICRAreaOptions is the custom interface exposed by the Area Options Object The methods and properties are listed in Table 6 7 They allow you to control details of the layout and format for the area An Area Options O bject is obtained from the options property of the parent Area Object Methods Custom Properties Navigation KeepTogether Parent KeepTogetherFormula Report NewPageAfter Application NewPageAfterFormula PrintAtBottomOfPage PrintAtBottomOfPageFormula ResetPageNumberAfter ResetPageNumberAferFormula Visible VisibleFormula Table 6 7 Interface acquisition Dim options As ICRAreaOptions Set options area Options Property calls options Ne
382. the name of the input file When the browser is directed to this file with the URL http www acme com ASPDemo SimpleDemo asp the browser displays the page shown in Figure 5 8 Ej Simple ASP Report Generator Microsoft Internet Explorer T http www acme com amp SPDemo Simy Norns Epa ne BS E SampleReports A SE POS ne area ENEN g Figure 5 8 Parallel Crystal D eveloper s Manual 167 Version 2 4 Revised 5 27 00 The contents of simpleDemo asp are shown below with minor details of font and layout ASP Report Generator lt TITLE lt FORM METHOD post ACTION SimpleAPICalls asp gt BACKGROUND democolor gif gt D gt lt b gt Report Server name lt b gt lt TD gt lt TR gt E text NAME ServerNam tterfly acme com gt lt TD gt D gt lt b gt Report Folder lt b lt TD gt lt TR gt E text NAME ReportFolder SIZE 40 MobileApps PCRE SampleReports gt lt TD gt D gt lt b gt Report Name lt b gt lt TD gt lt TR gt E text NAME ReportName SIZE 40 rpt gt lt TD gt tput Folder lt b lt TD gt lt TR gt tput Name lt b gt lt TD gt lt TR gt E html gt lt font gt lt TD gt omitted lt LANGUAGE VBScript gt lt HTML gt lt HEAD gt lt TITLE gt Simpl lt HEAD gt lt BODY
383. tion Server that is registered on the web server In particular an ASP page can connect to the PCRE Automation Server with a script such as lt Dim app Set app Server CreateObject MAS CRApplication 1 Set app Nothing 5 gt Parallel Crystal D eveloper s Manual 162 Version 2 4 Revised 5 27 00 Parallel Crystal D eveloper s Manual 163 This fragment loads the PCRE Automation Server and stores a reference to the Application O bject in the variable app This gives us the ability to use the methods and properties to customize and produce reports For example the script lt On Error Resume Next Dim app Set app Server CreateObject MAS CRApplication 1 app ConnectToReportServer flea acme com Set report app OpenReport C SampleReports Box rpt report PrintOut app DisconnectFromReportServer Set app Nothing 5 gt shows how we can use the PCRE Automation Server to connect to a Report Server and generate a report Notice how the script makes an independent connection to the Report Server with the call to ConnectReportserver In a busy environment this allows you to offload report generation to a dedicated machine and preserve the performance of your Web Server In general ASP based report generation will use a configuration similar to that shown in Figure 5 6 on page 164 The sequence of events is as follows 1 The client navigates to an ASP page with a URL which is typically something l
384. tion manufactures an instance of the smart pointer papp and binds it to the crapplication Co class The declaration is equivalent to steps 5 and_6 of the previous example The constructor call takes a single argument that uses the VC __uuidof keyword to retrieve the CLSID for the crapplication co class The smart pointer gives access to the methods of the tcrapp1ication wrapper Class generated by the import statement Parallel Crystal D eveloper s Manual 137 Version 2 4 Revised 5 27 00 4 The call to connect ToReport Server executes the following wrapper class method internally inline HRESULT ICRApplication ConnectToReportServer _bstr_t ip HRESULT _hr raw_ConnectToReportServer ip if FAILED _hr com_issue_errorex _hr this _uuidof this return _hr The parameter is specified with the COM support type_bstr_t that Wraps BSTR in an appropriate class providing allocation and conversion methods for estr The caller supplies an ASCII string and the constructors for_bstr_t automatically perform the conversion to str The body of the method wraps a local nREsutt that is examined after the actual method renamed raw_CconnectToReport Server returns If the call fails COM error information is retrieved and thrown as a local exception by a call to the COM helper function _com_issue_errorex 5 The declaration of name shows explicit use of the_bstr_t type to create a wrappered BSTR initializ
385. tion of the Report Engine Parallel Crystal client programming always follows the same pattern you instantiate your client refine its configuration and connect to the Report Server O nce you have finished your report customization you disconnect from the Report Server Y ou don t have to worry about deleting the instances of your clients because the Java language implementation does that for you We ll explain these operational details in greater detail in the following sub sections Application Client Instantiation The pcREApplicationClient Class allows stand alone Java application clients to connect to the Parallel Crystal Report Server The client has connect and disconnect methods and acts as a container for service provider classes that provide client side access to Report Server services Y ou can install a console in the client to adapt the client s error reporting facilities to the user interface provided by your application A PCREApplicationClient is instantiated using a constructor like this PCREApplicationClient PCREConsole console String host int port String args Properties props org omg CORBA ORB orb throws PCREClientError The constructor argument console specifies an instance of a class implementing the PCREConsole interface If you call an abbreviated constructor then your client will be created with an instance of the default console class pcREApplicationConsole The
386. tly the same as that for C clients The client connects to the G ateway server first then the G ateway allocates a uniquely named Report Engine Server and passes the name back to the client then the client completes the connection to the Report Engine If you want to tailor the connection process in any way then you must supply a PE_NO_CONNECT Value to PEInitialize Once you have set the additional connection properties you must then complete the connection with a call to pEconnect followed by acall to pzEtnitapr The following example shows how to connect to a Report Server using the logical name of a G ateway rather than its network host address PEHANDLE gateway Must call PEInitialize with PE_NO CONNECT PEInitialize NULL NULL 0 NULL PE_NO_CONNECT Get Gateway handle and specify logical name gateway PEGetGateway if PEGatewaySetName gateway purple ReportError goto close Connect to Report Server with purple Gateway if PEConnect ReportError goto close Complete initialization if PEInitAPI PCREAPI ReportError goto close Other API calls close PEUninitialize Parallel Crystal D eveloper s Manual 270 Version 2 4 Revised 5 27 00 When your client is connected you can access a variety of G ateway and Report Engine Server properties via the handles to their s
387. to dump memory and display threads Netscape and Internet Explorer use different implementations of Java and this can cause problems with the appearance of your applet and programming errors that derive from the lack of support for the most recent Java features You need to check Netscape and Microsoft web sites for the most recent information on their respective Java implementations The following checklist summarizes the points made in Chapter 2 in the section entitled Applet Client Connection If Parallel Crystal is not running on the same machine as your Web Server you need to run the IIO P GateK eeper as a proxy server on the Web Server The G ateK eeper forwards IIO P requests across the network to the Report Server and returns the replies Check with your System Administrator that the G ateK eeper is running The G ateK eeper can also be used as a simple Web Server However it normally runs on port 15000 so if the Web Server host is www acme com you should connect to the GateK eeper with a URL of the form http www acme com 15000 MyApplets monthly html Applet class files are normally downloaded from the same directory as the HTML page and this directory is normally located relative to the Web Server root directory Make sure you know what the root directory is and that your applet class file is indeed located where you think it should be If you store applet class files in a different directory to the HTML files then you need t
388. tring Visual J void ConnectToReportServer java lang String host The argument string host specifies the Report Server to which your client will connect It may take the form of either a symbolic host computer name or a dotted computer IP address For example Visual C app gt ConnectToReportServer mantis Visual Basic app ConnectToReportServer example host com Visual J app ConnectToReportServer 123 456 654 321 The method will return a COM error if host does not specify a valid computer name or if a Parallel Crystal Report Server is not running on the nominated machine If you supply an empty string for the host name then your client will be connected to a Report Server somewhere on your network This is okay if you know that there is only one Report Server and you don t necessarily care about its location However if you have multiple Report Servers and you leave the host unspecified you cannot predict which server the connect ToReport Server method will select Therefore you must take steps to ensure that your report files are accessible on all of the Report Servers to which you could possibly connect This may not be easy so we recommend that you specify a host whenever possible A single call to connect ToReport Server is normally sufficient to establish a connection to a Report Server running on your local network However if the Report Server runs on a remote
389. ts sctevssecececcancevevsccssvcteasesusessastseticsnenns s lasses etesssontexatacevvescaercanassbbyaeata tcccaansuyacouona EEO aN ROE OKADEK PEE AENEASE 203 ICRPrinterInfo i ICRRep ritSummar yN O o aensensreneiass isona en OAT E AAE ES E A AEE D AEEA EAEOI OEA ETE r R aS 205 ICREXportOp ttm cc daccssvsssscavezacsaaevs toss saxevesusevs cosa sncavevisava secs aneavevanssacsnsnaseccatesatanacvasaceasuscuvsavavsvevssasagotaveustevbavarsosaveastevessenestaaeaats ICRReportOptions i JCRFormulaFieldDetimition sy seis vescccecccacsoussvansaxcseaidactsousavssavedsaseusutavssasadesseasuva EPEE ERTENED rO SEPEN RNEER EEOSE COKE VSTE ERNEK SOENS 208 JI RParameterFieldDefiniti on S eose iriiria Ea eai AE EEA E EA E EEE EA EETAS Sah E E RNE AE E A aN 209 PDE Report Generat otieririr aiie sa EEA AEA A R TR O ENRE E RAS ORM SRE E NANDE 211 Parallel Crystal Configuration Servere cisien t e e e E E NEAN EE EE EE i 212 Parallel Crystal Report Retrieval oroen EKE EEE EEEE EE S E E ENEE EAEE E A EE EEES 215 P rallel Cryst l Load Balancer vss sisiess discs cevssievedsissvnscieceavescasgasiateisa sescassaussvavessecesasassenedesassessessacaasaaascsasavasinesiancuasavadavaanasnscaseietoseans 217 Using the Load Balancer in Automatic Mode ccscceccesssseeseesecsecceeseeseeseesecseeeseeseesecseesececesecsecseeseceeseeeeeeeaeeaecseseeseaeeaesaeeneeeeeeas 217 Using the Load Balancer in Manual Mode ccscesesccesceceesseseesecsceeseeseesecsecseeeseeseesecsee
390. u can view it in your browser If you return this location as a hyperlink in the response then you can navigate directly to the report The modifications that are required to the example s ASP pages are as follows 1 In the page simpleDemo asp Change the form so that the Output Folder entry box holds the name of a sub directory called samp1eoutputs rather than the full path Name c MobileApps pcre SampleOutputs When the report HTML file is retrieved it will be placed in the samp1eout puts sub directory of the Web Server s root directory To get the report s HT ML file back to the Web Server we use the ReportRet rieval method in the Automation Server To use this method the following changes to the SimpleAPICalls asp page are required Parallel Crystal D eveloper s Manual 173 Version 2 4 Revised 5 27 00 2 At Step 7 in the example insert the line WebRoot C InetPub wwwroot If your web server has a different root directory then insert the appropriate value 3 Insert the following new code between the end of Step 14 and the start of Step 15 If bOK Then PCREApp RetrieveMode True If Err Number lt gt 0 Then ReportError RetrieveMode cannot enable End If End If This code sets the ret rieveMode property of the Application Object to True which enables automatic retrieval of the report once it is generated However when you enable report retrieval you must specify the location of the file on the Web Server
391. ucceed if you have a Parallel C running somewhere on your network The client w the default character based PCREAppConsole to r errors F FF F F F F ty Q DN EAppClient client 2 Create an application client for use with a PCR Server on the specified host A subsequent call Connect will succeed if the host name is vali Parallel Crystal is running on that host The c will use the default character based PCREAppCon to report errors F F F F go Q ve EAppClient client butterfly acme com 3 Create an application client with a user specif that implements the PCREConsole interface and p output console that is integrated with the appl user interface The host is unspecified and a c Connect will succeed if Parallel Crystal is r where on your network F FF FF F F F PCREAppClient client new MyConsole 4 Combine examples 3 and 4 above The client is c K a specified console and Connect will connect specified host ae PCREAppClient client new MyConsole ant acme com ANSI C Application Client Initialization E Report 1 to rystal ill use eport E Report to d and lient sole ied console rovides an ication s all to unning some reated with it to the Parallel Crystal C clients are initialized rather than instantiated using the API function BOOL PEInitialize PEConsole console const char ho char argv int c
392. uctor passes the host to the pcrEGateway instance If you omit the host the pcrEappletClient constructor will pass the Web Server s host to the pcrEGateway and the PCREApplicationClient Will leave it unset Either way you can override these settings by using the setHost method as shown When you call the client connect method the PCREGateway Class is connected to the G ateway Server on the nominated host It only makes sense to use a set property before you call the client s connect method If you call a set property after connecting the client the method will throw a PCREClientError exception try client Connect String hostName HostNameDialog client getGateway setHost hostName Exception thrown catch PCREError error error Report PCREServer Properties The pcreserver Class provides client access to the Parallel Crystal Report Engine Server running on the Report Server machine Table 3 3 summarizes the property methods which allow you to supply or retrieve a string of command line arguments to be used when the G ateway Server starts the Report Engine Server The command line arguments for the Report Engine Server are summarized in Table 3 4 Property Name Purpose setArguments Supply the command line argument string getArguments Return the command line argument string addArgument Append a command line argument to the string Table 3
393. uely named server and then returning the name and host to the client e The client establishes a connection to the Report Engine Server using the name and host returned by the G ateway Once the G ateway has been located the applet client s connect method proceeds in the same way as the application client The connections remain until the client s quit method is called Although the Java code you write to connect an applet client or application client is very similar there are substantial differences at network level that arise because of the restrictions imposed on applets by the browser s Security Manager We ll devote the rest of this section to describing how applets get loaded into your browser and how the underlying CORBA framework establishes network connections to remote servers Applets are initially loaded using the lt applet gt tag in your HTML page The code attribute specifies the name of a class with the class suffix omitted The name may itself be a simple name such aS TravelApp or a fully qualified name such as com acme apps TravelApp To locate the class the browser adds a class suffix and then searches an internal cache of loaded classes This cache is partitioned into structured name spaces so the browser will search for the class TravelApp class in the first case and com acme apps TravelApp class in the second case If the class is not already loaded the browser continues the search using the CLASSPATH of the host machi
394. ula Manipulation Parameter Field and Stored Procedure Manipulation cccescssccscceseeseesecsecseceecesecsecsecseceeeseesecsececeaeeeseceaeeseeaeseceeseseeseeaeeateneee 75 Database Table Manipulation eee 76 SQL Queries Sort Field Manipulation 77 Sections and Groups coeire Er ir sE TEE rs ESETERE EE EEKE E savereodsassasuyavexesioas4 sicasevayesdvasd sisasevayesdvausviss ESO FEIE TESEN tias 78 Atea and Section Formatting v v cic scssccocsvasusesvvauceecvcassssvansecusnacsabntsrseenswasescouvaucussvenhessaveaicestes tudes ovtaudeeeevansesvreundeeeskoasdessvercecestasesevs 78 Sub report Management Graph Matiipulati ont iieis riari iR aE E EE REN ATA AEREE AEAEE E e oe TANS UNOS i RS EUs UU AEEA ES Data Object Repotting reissaa ena a OAOE R EAEE AES ENE eT EENE TRE Tee AEE 8l Overview Preparati Oleo sereine neen tosa en E EAT EERIE TAARE ENE AE EDREAL OEE VEETEREN EATERS 81 Analyze th Data SOurCe cirese siseste re E NOE EE EENE E T EE causvaseagaesesecey 82 DOR Design Utility 85 DOR to RPT Utility 85 Final Report Design 86 Running a DOR REPOrtcescoscvseseceavacssovsenceicvsvucceeueonecsevavunceenengcscbessscesevuedecestesdeessvasdedeeencessoveeeuvrvusdsceavessecsveundereusdacsevsvarceeevapeaess 87 Tips for Usine DOR roeren raae EIRE E EER E EEA AE AAE EAA AEA EEEE AN EAEE A EEEE E EAA EREE Ee 88 Error Recovery asor vrina A N E Aa AAAA OSRE EEEa AAEE AEAEE KEES NESE EADE VES ERE ANE AAEE AE EEA T 92
395. up of methods allows you to adjust the areas and sections in your report GetSectionFormat SetSectionFormat GetAreaFormat SetAreaFormat GetMinimumSectionHeight SetMinimumSectionHeight GetSectionFormatFormula SetSectionFormatFormula GetAreaFormatFormula SetAreaFormatFormula Sections and areas are accessed by a section code returned by the Get sect ionCode method The formatting details of each section or area are specified in the members of a section is retrieved and reset int section job gt GetSectionCode n PESectionOptions options job gt GetSectionFormat section amp options adjust formatting options job gt SetSectionFormat section amp options Subreport Management PESectionOptions Struct The following fragment shows how the formatting of the n th The following group of methods allows you to access sub reports within a given report OpenSubReport CloseSubreport GetNSubreportsInSection GetNthSubreportiInSection Subreports are accessed by GetNthSubreportInSection which returns a the sub report by passing the name to the opensubreport method of the pcreEngine class The following fragment iterates through all the sub reports in the n th section int section job gt GetSectionCode n int nSubReports job gt GetNSubreportsInSection section for int i 0 i lt nSubReports i PESubreportInfo info job gt GetNthSubreportiInSection sect
396. urally the Web Server must be running on the same machine as the Report Server If this is not the case then it is possible to use the IIOP G ateK eeper as a substitute Web Server The G ateK eeper is part of the Parallel Crystal installation so it is always available on the Report Server However it normally runs on external port 15000 so that you require a URL of the form http www mantis com 15000 sales html to retrieve the file from the host www mantis com You should also note that the G ateK eeper is not a high performance Web Server and can only serve HTML files The automatic Report Retrieval Service is not available for Java applet clients since it is generally not possible for applets to write to the file store Parallel Crystal D eveloper s Manual 100 Version 2 4 Revised 5 27 00 Parallel Crystal Configuration Server When Parallel Crystal is installed a number of directories are created with sample Crystal Reports and demonstration materials In order to help you locate path names for these directories Parallel Crystal incorporates a Configuration Server that returns configuration and installation dependent information to the client Java clients access the Configuration Server through the methods of the PCREConfigServer service provider class that are summarized in Table 3 7 on page 73 Y our client is automatically connected to the Configuration Server when you call the Connect method Thereafter you can get
397. ure 1 1 Parallel Crystal D eveloper s Manual 14 Version 2 4 Revised 5 27 00 Figure 1 1 Customizing Reports The report files produced by the Crystal Report Designer support an additional modification process called customization which allows many of the design time properties of the report to be adjusted at runtime just prior to report generation Customization is performed by a software component called the Crystal Reports Print Engine that reads the original report file applies modifications to the report properties and then merges the data to produce the final report Customization is frequently used to modify the selection criteria that are used to filter data records from a database or to specify the database at runtime Report customization is illustrated in Figure 1 2 E Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 Customization commands Parallel Crystal Report Engine The Crystal Report Print Engine is provided as a Dynamic Link Library D LL that accepts customization commands delivered as procedure calls across an API In order to perform customization you must write a program or script that calls the appropriate API functions in the DLL The Parallel Crystal Report Server provides report customization through a licensed version of the Crystal D LL called the Parallel Crystal Report Engine PCRE The PCRE is an extension and enhancement for the Crystal Report Print En
398. vadeosaadesve unvseouti aseevs vusssebveusveves snecscuteavexsvsteecbeiteasessvenevedons sketorveussadevcasets 283 Area and Section Formatting Subreport Management Graph Manipulation secsossscssssscscscssssscvevcsceovensousessccsnsscnnsssocnecssanasssnveccenvsnseuveseenvasteunsenvnsensnnsntennvsecevanssseusseseesvansousessennns D5 Report Generation for GC CU ents civcrccscivcaiciues chess iccesasis shea sinc ase us sabi eae eee tas eee aa pe Saas as aa eae aha E a EE AES AAAA 286 Error Recovery in CCUCNIS coreia ea EA E E E gabe E AEE sound EEE EE E EA E EAE EEEa AAS 288 Error Recovery in C CUENts ccscvssescaicssisceseasessascsstecedossescaacsstevades sectaasaasevasanavcsissvascnasdeavcuassvasiadsdaavcvasavacseaasaguseacedstensdsasnseasoisteseoes 289 Console Tnterfac ssers riir esaea EN EE REEE EETA EEAO ORA NAE a EA rA aus A SEEEN SEESE AES 293 Report Retrieval nosiris a eein iA REEE A RAE veka AAEE A AEE EPE EEEE ER vous ced OVEA wecad eve Bac EEE aad EEE EASAN E TA 295 Retrievalto O m CuEMS AEE ESE EE E EO E EE EE 295 Retrieval toC CMEMS AEn E a E NTE EA AA tetsu NER A AET E ee saa EEEN 296 Parallel Crystal D eveloper s Manual 6 Version 2 4 Revised 5 27 00 Parallel Crystal Configuration Servet s iccicacsiscctcasescccusea tect si aR aaa Stee GSAS VN ELAN RSV SA AE NADA Elen SE E aban ee oes 298 Configuration Server for C Clients 3 Configuration Server for C Clients Parallel Crystal Load Balancer iranier ri
399. velApp codebase http www acme com classes gt Once your applet s class file begins to execute it will initiate searches for other classes in the PCRE package and the underlying CORBA framework If you happen to have the Parallel Crystal Java Client installed on the same machine as the browser then the classes will be loaded locally O therwise they will be downloaded from the Web Server In attempt to reduce download time some versions of Netscape Communicator have a CORBA framework pre installed However we cannot guarantee that it will be compatible with the rest of the PCRE package So we recommend that you always specify the applet parameter lt param name org omg CORBA ORBClass value com visigenic vbroker orb ORB gt This will force the client to download the CORBA framework distributed with the Parallel Crystal Java package and should ensure version compatibility in the client and the Report Server Once the CORBA framework and the core of the Java Client package have been downloaded the client will try to connect to the Report Server using CO RBA IO P protocol 1 IIOP stands for Internet Inter O RB Protocol Parallel Crystal D eveloper s Manual 63 Version 2 4 Revised 5 27 00 The IIOP connection will fail if either of the following is true e The host specified for the Report Server is not the machine running the Web Server e The applet is running behind a firewall that permits only outgoing HTTP requests Run
400. veloper s Manual 108 Version 2 4 Revised 5 27 00 Chapter 4 Trouble Shooting Java Clients This chapter describes how to solve the problems that most frequently occur when developing Parallel Crystal clients in Java Problems with CLASSPATH In order to construct a Parallel Crystal Java client you must import the PCRE package into your application with an import statement of the form import com mobileapps pcre When the Java compiler encounters this statement it uses an environment attribute called the CLASSPATH to locate the class files in the package The CLASSPATH contains a list of directories separated by semicolons that tell the compiler where to start in its search for the package If your Parallel Crystal Java Client distribution was installed on your client machine in the directory c MobileApps pcre then your CLASSPATH should have the form 7C MobileApps pcre jars PCREJjavaclient jar This tells the Java compiler to search for the PCRE package in the current directory and then in the jar file pcrEjavaclient jar Most compilers will also look in some implementation dependent standard place before finally giving up the search Unfortunately as Java has evolved the way in which applications are distributed has changed and so has the way Java D evelopment Environments use the CLASSPATH Currently the Parallel Crystal Java Client Distribution is packaged as a single jar file called PCREjavaclient jar This f
401. w acme com ASPDemo SimpleDemo asp z Links ee he eke a eee re Report Server Name butterfly acme com E _ Report Path Name ue MobileAppsIPCREISampleReportsFTE rt Putra Path Name ee NE PONE ERAMU TE html Report generated in G C MobileAppsIPCREISample Outputs IFTE h html Figure 5 9 The contents of the simpleaPICcalls asp page are shown below Note that the Visual Basic quote comments are included for the commentary that follows The HTML lt gt comments are too bulky to accommodate on a line The error handling for the code is for ASP 2 0 You can use the Error ojbect in ASP 3 0 for better error handling Parallel Crystal D eveloper s Manual 169 Version 2 4 Revised 5 27 00 The response that is returned to the browser is derived from the static HTML sequences enclosed between conventional tags and the dynamic sequences that are generated by the embedded VBScript The lines in the page that are particularly important are highlighted in bold lt LANGUAGE VBScript gt L RE lt HTML gt lt HEAD gt lt TITLE gt Simple ASP Report Generator lt TITLE gt lt HEAD gt lt BODY gt lt CENTER gt M2 lt b gt Simple ASP Report Generator lt b gt lt CENTER gt lt br gt lt br gt A oe w Sub ReportError msg ay Response write SimpleAPICalls asp amp msg bOK False Err Clear aro or End
402. wPageBefore Fals options NewPageAfter Tru Set report options Report Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 ICRGroupAreaOptions ICRGroupAreaOpt ions is the custom interface exposed by the Group Area O ptions Object The methods and properties are listed in Table 6 8 They allow you to control the details of the layout of a group area A Group Area Options Object is obtained from the GroupOptions property of the parent Area O bject Methods Custom Properties Navigation Condition Parent DiscardOtherGroups Report KeepGroupTogether Application NumberOfTopOrBottomGroups Repeat GroupHeader SortDirection TopOrBottomNGroups Table 6 8 Interface acquisition Dim options As ICRGroupAreaOptions Set options area GroupOptions Property calls options SortDirection crAscendingOrder options NumberOfTopOrBottomGroups 3 options TopOrBottomNGroups crTopNGroups ICRSection s ICRSect ions is the collection interface exposed by the Sections Collection Object The methods and properties are listed in Table 6 9 A Sections Collecction O bject is obtained from the sections property of the Area O bject Each item in the collection is a Section O bject representing a section within the parent area and the number of Section O bjects is returned by the count property Individual objects are obtained by the rt em method that takes an index or string argument identifying the sectio
403. wever the extent to which truly concurrent behavior is sustained depends upon a combination of factors including the number of available processors the number of connected clients the overall loading on the machine and the resulting contention for shared resources Were now in a position to look at a simple Java Application Client that generates a report as a PostScript document Parallel Crystal D eveloper s Manual 31 Version 2 4 Revised 5 27 00 Generating a Simple PostScript Report The sample Java program shown in Example 2 1 generates a report from the Box rpt report file and sends it to a PostScript printer We ll describe it line by line import com mobileapps pcre class PostScriptExample public PCRI try SLI ca fi static void main String args EApplicationClient client null ent new PCREApplicationClient example host com client Connect PCREEngin ngine client OpenEngine j PCREJob job engine OpendJob C MobileApps PCRE SampleReports Box rpt job OutputToPrinter 1 job Start job Close System out printin Report generated engine Close tch PCREError ex System out printin Exception ex nally if client null client Quit Example 2 1 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 1 2 3 4 5
404. will see are E_FAIL 0x80004005 E_ UNEXPECTED 0x8000FFFF You will be able to get a much more informative error code and error description string from the product This information can be obtained by using the LastErrorCode and LastE rrorString methods in the A pplication object and in the Report object or by looking at the Server Log The Server Log is a very useful list of all the commands that have been accepted by the Report Engine process on the server Its name is server log and it lives in mobileapps pcre server log In the server log following a command that has failed you will normally find an explanation of why it failed Here is an extract from a Server Log OpenPrintJob File c mobileapps pcre SampleReports rubbish RPT CREAPI Error returned for job 0 Error text Invalid file name It can be helpful in development to run the PCRE product in foreground instead of as an NT service The log entries for PCREG ateway and PCREserver processes are then visible in G UI form on the Report Server s screen To do this stop the Parallel Crystal service and then execute osagent exe and pcregateway exe Parallel Crystal D eveloper s Manual 323 Version 2 4 Revised 5 27 00 Diagnosing Server side Setup Problems Connection You are unable to get started The app Connect machine is failing e Check that the machine name or IP number is correct e Check that the machine is up
405. x fof Ves System out printin Exception ex finally 12 if client null client Quit de WB Example 2 2 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 A PDF report is generated by calling the output Toppr method of the pcrevob class and supplying the name of the output file as an argument The PD F document is produced when the job is started at line 7 and is stored in the file C MobileApps PCRE SampleAppsOut put Box paf In order to display the file you must have access to a PDF viewer such as Adobe s Acrobat Reader Most Internet browsers have this viewer pre installed as plugin The outputToppr method call uses the D ynalivery PD F Library that extends the Parallel Crystal Report Engine with facilities to render reports directly in PD F It is possible to provide a set of PDF output options as a second argument to output Toppr However these options require detailed knowledge of PD F and further discussion is deferred to the Chapter 3 In practice the default operating options are sufficient for most purposes and are automatically selected when the second argument to output ToppF is set to null Generating a Simple HTML Report If the reports you wish to generate are web based and intended for display exclusively through web browsers then it may be appropriate to generate the report as an HT ML file Example 2 3 below illustrates how the Box Office r
406. xample host com client Connect PCREEngin ngine client OpenEngine j PCREJob job engine OpenJob Box rpt job OutputToPrinter 1 job Start job Close engine Close catch PCREError ex System out printin Exception ex finally if client null client Quit Example 1 1 Advantages of Using a Report Server Crystal Reports supports report customization by allowing desktop application programs to be linked to the Print Engine DLL In most cases the application is written in Visual Basic and uses a version of the customization API distributed with the Visual Basic environment If the report requires access to data the database is located either in the same desktop machine or in a networked database server For example a typical arrangement involving a SQ L DBMS is shown in Figure 1 3 5 Parallel Crystal D eveloper s Manual Version 2 4 Revised 5 27 00 H Database Server mw FL mme fA i O BT Desktop Reporting PC Deddtop Reporting PC Figure 1 3 Each PC runs the customization application linked with the Crystal Print Engine DLL However executing an appropriate SQL query in the database server performs the selection of data records The records are returned to the PCs for incorporation into the report An application in which clients communicate with a single server is sometimes referred to as having a two tier client
407. xample uses a crst r helper class to manage string storage and the translations between normal and wide character formats 8 Thecall to connectReport Server connects the client to a Report Server on the machine identified by the host name parameter If the connection cannot be made the call will return a failure nResuLT The tcrapplication interface contains a get_LastErrorString method that is the reason for failure 9 The call to openReport opens a print job for the report file and returns a pointer to the 1pispatch interface on the Report O bject Parallel Crystal D eveloper s Manual 129 Version 2 4 Revised 5 27 00 10 11 12 13 14 15 16 17 Making C method calls through 1Dispatcnh is extremely tedious and very inefficient SO QueryInterface is Called to return a pointer to the rcrreport custom interface Methods on this interface are accessed using the v table to make normal virtual function calls The call to Querytnterface increases the reference count in the Report O bject to 2 There are no further accesses to the tpispatch interface so it is discarded with a call to Release and the reference count on the Report O bject falls to 1 The report is generated by calling 1CRReport PrintOut to run the print job This method takes six optional arguments that are initialized with values of type crNoArg Optional arguments were originally designed for Visual Basic or VBScript controllers and a
408. y then pdfdistiller will attempt to run a program called acropist and will rely on the System PATH environment variable to locate this program You can run pdfdistiller manually on the Report Server to check its operation The command line is pdfdistiller command input psfile output pdffile By default the program runs silently and writes its error messages to the Windows NT Event Log Check this log file before you do anything else If you supply the optional command argument then error messages will be written to the standard output stream as well Since Acrobat Distiller relies on the existence of the PostScript file you should take care to ensure that the file does indeed exist before calling padfdistiller When you generate PDF via the export Toppr method the Report Engine Server applies internal checks to ensure that the PostScript file has been completely generated before returning control to the client This is because the PostScript file is not generated directly by the Server but by the Windows Print SubSystem This process can take several seconds on a busy machine processing large files Problems with the Report Server The following problems can arise with the Report Server 1 The Load Balancer and Report Retrieval Service can be turned on and off in the Report Server If you get connection errors when trying to use either of these services check with the System Administrator that the Report Server is configu
409. y its full path name tO OpenReport The call to the Report O bject method export TontTmL may fail and report the error Disk full This highly misleading message is actually returned by the Report Engine and means that it was unable to create the HTML file to hold the generated report It does not mean your disk is full Check the argument string for Export ToHTML specifies a valid drive and path name and that access permissions on the Report Server file store allow the file to be created The call to the Report O bject method printout may fail and report the error Cancelled by user This message is returned by the Report Engine when it is unable to locate a suitable printer This is either because the printer has become inaccessible because of network problems or because the printer settings inserted into your report at design time are no longer valid You may need assistance from either your System Administrator or Dynalivery Technical Support Staff to fix this problem Parallel Crystal D eveloper s Manual 152 Version 2 4 Revised 5 27 00 Using Parallel Crystal with Visual Basic This section describes how to write Visual Basic clients that use the PCRE Automation Server to generate simple reports in PostScript PD F and HTML The contents apply to 32 bit versions of Visual Basic 5 and 6 Automation which used to be called O LE Automation was originally designed for Visual Basic 4 and many of its features
410. yReports The server will be started with arguments supplied client Connect catch PCREError amp error error Report Add arguments in multiple calls cry PCREServer server client getServer server gt addArgument client toby server gt addArgument folder C MonthlyReports The server will be started with arguments supplied client Connect catch PCREError amp error error Report In each case the argument string is supplied when the Report Engine Server is launched by the G ateway This implies that you must know the values of the arguments before you issue the connect Call In the section Parallel Crystal Configuration Server we ll show how you can change the Report Engine Server s working folder after you have established the Report Server connection C Client Configuration A Parallel Crystal C client gets access to the service provider classes through handles which are returned by the set of API function calls listed in Table 9 5 Each handle carries the value of a read only opaque type called PrHaNDLE Parallel Crystal D eveloper s Manual 259 Version 2 4 Revised 5 27 00 Service Provider Function Purpose PEGet Gateway Return a handle to the PCRE G ateway Server PEGet Server Return a handle to the PCRE Report Engine Server PEGetConfigServer Return a

Parallel Crystal Developers Manual

Contents

Download Pdf Manuals

Related Search

Related Contents