Chapter 11 Programming for OLE automation support
Transcription
Chapter 11 Programming for OLE automation support
UNIFACE V7.2 DEMO : Purchase from www.A-PDF.com to remove the watermark Chapter 11 Programming for OLE automation support This chapter describes the Object Linking and Embedding (OLE) automation DLL which is installed by default. OLE allows the use of all features given by OLE Automation Servers, such as Microsoft Office 95 Applications, in their own UNIFACE application development. It also allows you to create OLE automation objects and provide a standard implementation of functions to access the objects. You can manipulate objects with a variety of 3GL functions, using the public properties and methods that the OLE automation object supports. i Note: OLE automation support is only available for the Microsoft Windows 95 and Microsoft Windows NT environments. 11.1 What is OLE? Microsoft’s OLE is the standard for component-based development. Objects created by one application using OLE can be reused by other applications and the other way around. A prerequisite for a mix and match of foreign objects is a standard way of interobject communication. In the Windows environment, this communication standard is called OLE. Applications can contain objects that are made available by other, associated applications. These associated applications are used to manipulate the objects. The objects that can be made available by foreign applications are called OLE objects. Proc Language Reference Manual, Volume 1 (Feb 1999) 11-1 UNIFACE V7.2 OLE Servers and OLE Clients The application that displays OLE objects is called the OLE Server. The application that uses and contains the objects is called the OLE Client. For example, you can embed a Microsoft Excel spreadsheet in a Microsoft Word document. In this case, Excel is the OLE Server and Word is the OLE client. Using OLE you can, for example, change cell values in the Excel spreadsheet, which will then be automatically updated in the Word document. i Note: All Microsoft applications referred to in this chapter are Microsoft Office 95 applications. The examples are all specific to that version of Microsoft Office. UNIFACE and OLE UNIFACE applications can store and display OLE objects in the standard OLE container widget, and start the associated application (the OLE server) for data manipulation. On a UNIFACE form, a field that is painted as an OLE container widget can be embedded or linked in a Word document. By double-clicking, for example, the OLE container widget, Word will start up with the contents of the OLE container, and enable the user to edit the data. The OLE container data is automatically updated at the moment the user closes Word. 11.2 The OLE container widget The following section briefly describes OLE and the properties available to you in the container widget. 11.2.1 Object linking and embedding The OLE container widget of UNIFACE allows you to embed or define links to OLE objects such as Word documents, Excel spreadsheets, bitmaps, .wav files, and so on. 11-2 11.2 The OLE container widget (Feb 1999) Programming for OLE automation support UNIFACE V7.2 Linking When you link an object, such as a file, changes you make to the object appear in the linked object as well as in the source file. Changes you make to the source file also appear in the linked object. Embedding If you embed the object, changes you make to the object do not appear in the source file, and changes to the source file do not appear in the embedded object. 11.2.2 Field and widget properties The following section describes the properties and effects available to you in defining the appearance of the OLE container. Field definition The OLE object in the OLE container widget of a particular occurrence can be stored in the database as a Binary Large Object or BLOB. The data type of the OLE container should be defined as raw data, with an interface definition of raw data, length unknown, or ‘R*’. It is recommended that the OLE container field be defined as the last field in the Define Name List dialog box. For example, see figure 11-1: Figure 11-1 Define Component Field Properties. Proc Language Reference Manual, Volume 1 (Feb 1999) 11.2.2 Field and widget properties 11-3 UNIFACE V7.2 Figure 11-2 specifies options for the visual appearance of the widget on the form: Figure 11-2 Define OLE Container Properties. Frame and 3D Effect The 3D Effect property is not available for Microsoft Windows 95 and Microsoft Windows NT. Display as Icon Specifies whether the widget displays a representation of the data, or an icon (default). For example, you can show the representation of a bitmap image in an OLE container or show its Bitmap Image icon. Allow Linked Object, Allow Embedded Object The OLE container can contain only one embedded or linked OLE object. Use the check boxes to specify which is required (default = True). Attach to Window Border Specify whether the widget is attached to one or more edges of the form or form border at run time. 11-4 11.2.2 Field and widget properties (Feb 1999) Programming for OLE automation support UNIFACE V7.2 Label Font The font for the label associated with the widget. Mouse Activation Specifies how the object in the OLE container widget is activated. The default is left double-click. Allowed Classes The classes of an object can be held in the OLE container widget. Enter a list of class names of the objects which can be held in the OLE container (separated by commas) or ALL (the default) for all classes. In this way, UNIFACE can be instructed to store Word documents, for example, and nothing else. 11.3 Parameter lists Parameter lists are used in functions such as OAINVOKE and OAEXECMULTI to pass the input parameters to a method of an OLE object. The list consists of one or more parameters separated by the item list delimiter. Each parameter has a type qualifier and a value (also separated by the item list delimiter). For a complete list of type qualifiers, see table 11-2. The following example assigns a parameter list with three parameters to $14: $14 = "S ;Hello ;E ;;I ;123" Where: • S is a string. • E is an empty parameter and has no value. • I is an integer number. Proc Language Reference Manual, Volume 1 (Feb 1999) 11.3 Parameter lists 11-5 UNIFACE V7.2 Table 11-1 contains a list of data types that can be used in parameter lists: Table 11-1 Table of data types. Type Description Range of Values Examples B Boolean value 0 for False or 1 for True B;1 CY Currency (approx.) +/-1.7E +/- 308 CY;-59777.15 E Empty n/a E; ERR Error error codes ERR;0x80000042 I Integer value -2147483647 to 2147483647 I;123456 F Floating point value (approx.) +/-1.7E +/- 308 F;3.141 (See OAFLOATFORMAT) S Strings any string (w/o ;) S;Hello world† DT Date and time 01/01/1753 ... 12/31/2078 DT;12/20/1963 08:09:10 ‡ P Object pointer any valid object pointer P;0x005e5540 Table notes: † If you want to pass the list delimiter ; by itself, you must escape with GOLD+Exclamation mark. The sequence !; is passed as a single ; to the OLE. Likewise, a ! is placed before a ; when it comes back from the OLE. ‡ These values are either passed as ‘Date and Time’ in the form of ‘mmddyy HH:MM:SS’ or ‘Date only’, and the time is internally set to 00:00:00, or ‘Time only’, and the date is set to the current date. 11.3.1 Array parameters Array parameters are used to pass arrays to a method. This type of parameter starts with ‘A’, followed by the number of array dimensions and the size of each dimension. After that, the array elements are listed. Each element is composed of a type qualifier and a value, as described above. The following example assigns a 3x2 two-dimensional array to $14. The first row of the array contains the strings ‘One’, ‘Two’, ‘Three’ and the second row the numbers 1, 2, 3: $14 = "A ;2 ;3 ;2 ;S ;One ;S ;Two ;S ;Three ;I ;1 ;I ;2 ;I;3" 11-6 11.3.1 Array parameters (Feb 1999) Programming for OLE automation support UNIFACE V7.2 11.3.2 Method list A method list is used in the functions OAEXECMULTI and OAEXECMULTIV to pass the names of methods and properties together with parameters to the OLE Server application. See table 11-2. The list consists of one or more calls of methods and/or properties, the name of the method or property, the count of parameters, and the actual parameter list. In case of setting a property the PS call is followed by the property value. Table 11-2 Call types in method list. Call type Description M Method PG Property Get PS Property Set The following example writes the value 123 into cell A1 of the worksheet named ‘Sheet2’ in the current workbook of an Excel Application: $12 = $EXCEL_SHEET$ ; get application object $13 = "M;Worksheets;1;S;Sheet2;M;Range ;1;S;A1;PS ;Value ;I;123" perform OAEXECMULTI With the exception of the first invocation (as each one is made on the result of the previous invocation), the result types are object pointers for all, except the last. Therefore, you can only set the property at the end of the list. 11.4 Error information Errors are returned from an OLE automation function in $result. When this is not empty, it contains the information (as found in table 11-3) in an indexed list: Proc Language Reference Manual, Volume 1 (Feb 1999) 11.3.2 Method list 11-7 UNIFACE V7.2 Table 11-3 Error information. Item Description First Numeric error code. Second Name of application that caused the error. This is either ‘UNIOA’ when the error comes from the DLL itself, or the name of the OLE Automation Server. Third Description of the error. This field can also be blank. Fourth Name of a help file with further information about the error. This field can also be blank. Fifth Topic ID in the above help file. This field can also be blank. The following example is a typical error returned from an OLE Automation Server: "1005;Microsoft Excel;The value property of the range object cannot be changed;VBA_XL.HLP;12345" 11.5 3GL Functions for OLE automation The 3GL functions for OLE automation are described in table 11-4. These functions are called by the Proc perform statement. These 3GL functions use general variables to pass and return their arguments. By default, the base general variable for these functions is $12. When more than one argument is required, successive general variables are used, $13 and $14 for example. This base variable can be changed by using the OASETBASEREG function; see section 11.5.3 Service functions. The maximum size of an argument (such as $12) is 32k characters. The results of these 3GL functions are returned in $result. The success of the function, unless stated otherwise in this chapter, is returned in $status as zero on success, otherwise $status has a nonzero value. 11-8 11.5 3GL Functions for OLE automation (Feb 1999) Programming for OLE automation support UNIFACE V7.2 Table 11-4 Summary of OLE automation 3GL functions. Function Name Description OLE Automation Functions OACREATEOBJECT Create OLE automation object. OADESTROYOBJECT Delete OLE automation objects. OAINVOKE Invokes a function/method in an OLE automation object. OAINVOKEV Invokes function/method in OLE automation object without return value. OAEXECMULTI Invokes several methods for an object in sequence. OAEXECMULTIV Invokes several methods for an object in sequence without return value. OASETPROPERTY Changes the property value of an OLE automation object. OAGETPROPERTY Gets the current value of a property for an OLE automation object. OAGETDISPID Gets the ‘dispatch Id’ for a name of a method or property. OAGETCLSID Gets Global Unique Identifier (GUID) of OLE Automation Server object. OLE Widget Functions OACRFROMWIDGET Creates an OLE automation object from an object stored in an OLE container widget. OACLOSEWIDGET Closes the OLE container object and ends its activation. OADOVERBWIDGET Invokes the primary verb defined for an OLE container object. OAUPDATEWIDGET Updates the object stored in an OLE container field. UOLEINSERTOBJECT Allows access to the OLE pointer held in UNIFACE. Service Functions OASETLOCALE Changes the language to use in interpretation of the $13 name variable. OASETBASEREG Changes the global variables to user-specified variables. OAFLOATFORMAT Changes the way floating point numbers are passed from the DLL to the UNIFACE application. OASHOWERROR Used to display a message box after an error is returned by a function. OAHELPONERROR Used to display help about an error returned by a function. OLE Enumeration Functions OAENUMQUERY Used to retrieve an enumeration object from an OLE automation object. OAENUMRELEASE Used to release a previously retrieved enumeration object. OAENUMRESET Used to reset an enumeration to the beginning. OAENUMNEXT Used to get the next object of an enumeration. Proc Language Reference Manual, Volume 1 (Feb 1999) 11.5 3GL Functions for OLE automation 11-9 UNIFACE V7.2 Microsoft Office 97 support UNIFACE supports Microsoft Office 97. However, some properties in Microsoft Office 95 have become methods in Microsoft Office 97, and the other way round. Therefore, if you are migrating applications from Microsoft Office 95 to Microsoft Office 97, it is recommended that you review their operation. 11.5.1 OLE automation functions The 3GL functions for OLE automation are described in the following section. OACREATEOBJECT This function is used to create OLE automation objects. It returns a value in $12 which is used in subsequent calls to OAINVOKE, OASETPROPERTY, and OAGETPROPERTY. When finished with the object, use OADESTROYOBJECT to delete the object and free up resources. On input, the function receives the name of the object in $13. Usually the name consists of the server name, for example ‘Excel’, followed by a period and the name of the object’s class within the server application. The following example creates a Microsoft Excel Application object and checks the status: $13 = "Excel.Application" perform "OACREATEOBJECT" if ( $status != 0 ) askmess/nobeep "Excel Server not available!","OK" else $EXCEL_APP$ = $12 endif 11-10 11.5.1 OLE automation functions ; set object’s name ; create the object ; check status ; save object for later use (Feb 1999) Programming for OLE automation support UNIFACE V7.2 OADESTROYOBJECT Deletes objects created by OACREATEOBJECT or another OLE. On input, the function receives the object pointer in $12. On output, $12 is cleared, because the object pointer is no longer valid and should not be used any further. Any error information is returned in $result.The following example demonstrates how to delete an object returned by OADESTROYOBJECT: $13 = "Excel.Application" perform "OACREATEOBJECT" if ( $status = 0 ) $EXCEL_APP$ = $15 . . . $12 = $EXCEL_APP$ perform "OADESTROYOBJECT" endif ;set object’s name ; create the object ; check status ; save object for later use ; do something ; destroy the object OAINVOKE, OAINVOKEV These functions are used to invoke a function or method in an OLE automation object. On input, the function receives the object pointer in $12, and the method’s name in $13. $14 can be used for input or output, and specifies the method’s parameter list. On output, $15 contains the method’s result when OAINVOKE is used. When OAINVOKEV is used, this variable is empty on return. The following example calls the ‘PrintOut’ method of an Excel Sheets object. This method receives four parameters that are all optional. In the following example, the ‘Number of copies’ parameter is set to 2, and the other parameters to ‘not set’ or ‘empty’: . . . $12 = $EXCEL_SHEET$ $13 = "PrintOut" $14 = "E;;E;;I;2;E;" perform "OAINVOKE" ; ; ; ; ; create the get object set method set method invoke the object from local variable name parameters method An ‘R’ modifier in the parameter list indicates that the parameter is passed by reference, and not by value. The following example passes an integer reference to the ‘GetVolume’ method: $12 = "P;0x01250984" $13 = "GetVolume" $14 = "RI;0;RI;0" perform "OAINVOKEV" $VOL$= $14 Proc Language Reference Manual, Volume 1 (Feb 1999) ; Now something like RI;10;RI;60 11.5.1 OLE automation functions 11-11 UNIFACE V7.2 OAEXECMULTI, OAEXECMULTIV These functions are used to invoke several methods for an object in sequence. On input, the function receives the object pointer in $12, and the method list in $13. The method’s parameter lists are passed along with the method’s name. On output, $15 contains the method’s result when OAEXECMULTI is used. When OAEXECMULTIV is used, this variable is empty on return. Any error information will be returned in $result. The following example gets the ‘Worksheets’ property from an Excel Application object, then calls the method ‘Add’ (which has no parameters on the Worksheets object), to add a new worksheet. This method returns an object pointer for the new worksheet. It then sets the property ‘Name’, to rename the new worksheet to ‘Forecast’. As the return value from the ‘Name’ property is not important, the OAEXECMULTIV variation of this function is called: . . . ; create the object $12 = $EXCEL_APP$ ; get object from local variable $13 = "PG;Worksheets;M;Add;0;PS;Name;S;Forecast" perform "OAEXECMULTIV" ; invoke OASETPROPERTY This function is used to change the property value of an OLE automation object. On input, the function receives the object pointer in $12, and the name of the property in $13. $14 can used for input or output, and contains the new value for the property. On output, $15 contains the operations result value. Any error information will be returned in $result. The following example sets the ‘Visible’ property of an Excel Application object. This property receives a Boolean value: . . . $12 = $EXCEL_APP$ $13 = "Visible" $14 = "B;1" perform "OASETPROPERTY" 11-12 11.5.1 OLE automation functions ; ; ; ; ; create the object get object from local variable set property name set value to TRUE set the property value (Feb 1999) Programming for OLE automation support UNIFACE V7.2 OAGETPROPERTY This function is used to get the current value of a property for an OLE automation object. On input, the function receives the object pointer in $12 and the name of the property in $13. $14 can be used for input or output, and contains the parameters for the property. However, if the property does not accept any parameters, $14 should be left empty. On output, $15 contains the operations result value. Any error information will be returned in $result. The following example retrieves the ‘Worksheets’ property of an Excel Application object. The value of this property is also an object pointer: . . . $12 = $EXCEL_APP$ $13 = "Worksheets" $14 = "" perform "OAGETPROPERTY" if ( $status = 0 ) . . . ; ; ; ; ; create the object get object from local variable set property name no parameters set the property value ; $15 now contains an object pointer ; to the Excel workbooks object endif OAGETDISPID This function is used to get the dispatch ID for a name of a method or property. The dispatch ID is a number representing the method or property. This number can be used instead of a name in calls to OAINVOKE, OAGETPROPERTY, and OASETPROPERTY. The following example gets the dispatch ID for the ‘Visible’ method of an Excel Application object: . . . $12 = $EXCEL_APP$ $13 = "Visible" perform "OAGETDISPID" ; ; ; ; create the object get object from local variable set method name get the dispatch-id OAGETCLSID This function gets the Global Unique Identifier (GUID) of an OLE Automation Server object. Every interface exposed by an object must have a unique ID; this ID must not conflict with an ID generated by another user. GUIDs are very large numbers which uniquely identify the interface. This function is used to get the GUID of an OLE Automation Server object. By calling this function an application can check the availability of a server without actually creating an object for this server. Proc Language Reference Manual, Volume 1 (Feb 1999) 11.5.1 OLE automation functions 11-13 UNIFACE V7.2 On input, the function receives the name of the server object in $13. On output, $15 contains the GUID if the server object is available on the local machine, otherwise $15 is empty. $status is zero, when the returned GUID is valid. Otherwise $status has a nonzero value. The following example gets the GUID for the ‘Excel.Application’ object, (‘00020841-0000-0000-C000-000000000046’), and checks the result: $13 = "Excel.Application" perform "OAGETCLSID" ; get the GUID if ( $15 = "") askmess/nobeep "Excel server not available!" endif 11.5.2 OLE Widget functions The 3GL functions available for the OLE Widget functions are described in the following section. OACRFROMWIDGET This function creates an OLE automation object from an object stored in an OLE container widget. After the automation object is created, you can manipulate it using the other OLE functions. The effects of manipulating the object should be reflected automatically in the OLE container. On input, the function receives the name of the OLE container widget in $13. On output, $12 contains a pointer to the object, when successful; otherwise $12 is empty. The following example creates an OLE automation object from an OLE container named ‘CONTAINERFIELD’: $13 = "CONTAINERFIELD" perform "OACRFROMWIDGET" if ( $status != 0 ) askmess/nobeep ". . .","OK" else $CONTAINEROBJ$ = $12 endif 11-14 11.5.2 OLE Widget functions ; name of OLE container in form ; get the object from container ; check status ; save object for later use (Feb 1999) Programming for OLE automation support UNIFACE V7.2 OACLOSEWIDGET This function closes an OLE container object and ends its activation. On input, the function receives the name of the OLE container widget in $13, then closes the OLE container object. The following example closes the OLE container object named ‘CONTAINERFIELD’: $13 = "CONTAINERFIELD" ; name of OLE container in form perform "OACLOSEWIDGET" ; get the object from container if ( $status != 0 ) ; check status askmess/nobeep ". . .","OK endif OADOVERBWIDGET This function invokes the primary verb defined for an OLE container object. For most OLE objects, the primary verb is ‘open’ to open the object within its server and change it, however, there are servers that define other primary verbs. On input, the function receives the name of the OLE container widget in $13. The following example invokes the primary verb of an OLE object stored in the container named ‘CONTAINERFIELD’: $13 = "CONTAINERFIELD" ; name of OLE container in form perform "OADOVERBWIDGET" ; get the object from container if ( $status != 0 ) ; check status askmess/nobeep ". . .","OK" endif OAUPDATEWIDGET This function updates the object stored in an OLE container field. On input, the function receives the name of the OLE container widget in $13. The following example updates an OLE object stored in the container named ‘CONTAINERFIELD’: $13 = "CONTAINERFIELD" ; name of OLE container in form perform "OAUPDATEWIDGET" ; get the object from container if ( $status != 0 ) ; check status askmess/nobeep ". . .","OK" endif Proc Language Reference Manual, Volume 1 (Feb 1999) 11.5.2 OLE Widget functions 11-15 UNIFACE V7.2 UOLEINSERTOBJECT This function allows you to access the OLE pointer held in UNIFACE. The function will automatically start the insert dialog to allow the user to define an embedded or linked object for a field. It must be exported as follows: XEXPORT (void) UOLEINSERTOBJECT (void) If the user focuses on the OLE Container by pressing either GOLD+D or Control+D, the <Detail> trigger is activated. 11.5.3 Service functions OASETLOCALE This function is used to change the language to use in interpretation of the $13 name variable in calls of OAINVOKE, OASETPROPERTY, OAGETPROPERTY, and OAGETDISPID. On input, the function receives the new language, or locale, as a string, either in decimal or hexadecimal form, preceded by ‘0x’. This value will become the first language used when interpreting names. The second language is the system, or OLE server’s, default language, and the third one is US English, as most of the servers are able to handle this language. i Note: Changing the language also affects the way floating point numbers are transferred to the application, see OAFLOATFORMAT in section 11.5.3 Service functions. The following example changes the default language to ‘German’, which has a locale ID of 1031: $13 = "0x0407" perform "OASETLOCALE" 11-16 11.5.3 Service functions ; 0x0407 = 1031 = German locale (Feb 1999) Programming for OLE automation support UNIFACE V7.2 Locale identifiers For list of locale identifiers and languages, to be used in calls to OASETLOCALE, see table 11-5: Table 11-5 Locale Identifiers. part 1 of 4 Locale identifier Description 0x0436 Afrikaans 0x041C Albania 0x1401 Algeria 0x0409 American 0x0C09 Australian 0x0C07 Austrian 0x3C01 Bahrain 0x042D Basque 0x080C Belgian (French) 0x0813 Belgian (Flemish) 0x0809 British 0x0402 Bulgaria 0x0423 Byelorussia 0x1009 Canadian 0x0403 Catalan 0x041A Croatian 0x0405 Czech 0x0406 Danish 0x0413 Dutch (Standard) 0x0C01 Egypt 0x0425 Estonia 0x0429 Farsi 0x040B Finnish 0x040C French (Standard) 0x0C0C French Canadian 0x0407 German (Standard) 0x042E Germany Proc Language Reference Manual, Volume 1 (Feb 1999) 11.5.3 Service functions 11-17 UNIFACE V7.2 part 2 of 4 Table 11-5 Locale Identifiers. Locale identifier Description 11-18 0x0408 Greek 0x0C04 Hong Kong 0x040E Hungarian 0x040F Icelandic 0x0421 Indonesia 0x0801 Iraq 0x1809 Ireland 0x040D Israel 0x0410 Italian (Standard) 0x0411 Japan 0x2C01 Jordan 0x0412 Korea 0x3401 Kuwait 0x0426 Latvia 0x3001 Lebanon 0x1001 Libya 0x1407 Liechtenstein 0x0427 Lithuania 0x140C Luxembourg (French) 0x1007 Luxembourg (German) 0x042f Macedonia 0x080A Mexican 0x0818 Moldavia 0x0819 Moldavia 0x1801 Morocco 0x1409 New Zealand 0x0414 Norwegian (Bokmal) 0x0814 Norwegian (Nynorsk) 0x2001 Oman 0x0415 Polish 11.5.3 Service functions (Feb 1999) Programming for OLE automation support UNIFACE V7.2 Table 11-5 Locale Identifiers. part 3 of 4 Locale identifier Description 0x0416 Portuguese (Brazilian) 0x0816 Portuguese (Standard) 0x0804 PRC 0x4001 Qatar 0x0417 Rhaeto-Romanic 0x0418 Romania 0x0419 Russian 0x0401 Saudi Arabia 0x081A Serbian 0x1004 Singapore 0x041B Slovak 0x0424 Slovenia 0x0C0A Spanish (Modern Sort) 0x040A Spanish (Traditional Sort) 0x0430 Sutu 0x041D Swedish 0x100C Swiss (French) 0x0807 Swiss (German) 0x0810 Swiss (Italian) 0x2801 Syria 0x0404 Taiwan 0x041E Thailand 0x0431 Tsonga 0x0432 Tswana 0x041f Turkish 0x3801 U.A.E. 0x0422 Ukraine 0x0420 Urdu 0x0433 Venda Proc Language Reference Manual, Volume 1 (Feb 1999) 11.5.3 Service functions 11-19 UNIFACE V7.2 part 4 of 4 Table 11-5 Locale Identifiers. Locale identifier Description 0x0435 Xhosa 0x2401 Yemen 0x0436 Zulu OASETBASEREG This function changes the global variables to user-specified variables. Usually the information exchange between UNIFACE and the OLE Automation Controller DLL is done by global variables $12, $13, $14, and $15. These variables can be changed by the function OASETBASEREG, and can be changed to any value between 1 and 96. The following example changes the number of the base variable to $31. Thereafter, all functions will use variables $31 through $34 for input and output: $status = "31" perform "OASETBASEREG" OAFLOATFORMAT This function is used to change the way floating point numbers are passed from the DLL to the UNIFACE application. On input, the function receives the new floating point format in $13. The default float format is ‘%lf’. The following example changes the floating point format to ‘%012lf’: $13 = "%012lf" perform "OAFLOATFORMAT" OASHOWERROR This function is used to display a message box after an error is returned by a function in the $result variable. When the $result variable contains information about an error, the error number, the application causing the error, and the error description is displayed in a message box. When $result is empty and does not contain error information, the function does nothing. $status is not changed by this function. 11-20 11.5.3 Service functions (Feb 1999) Programming for OLE automation support UNIFACE V7.2 The following example displays error information after invoking a method: . . . perform "OAINVOKE" perform "OASHOWERROR" if ( $status = 0 ) ... ; ; ; ; set parameters for OAINVOKE invoke a method show error to the user $status still from OAINVOKE! OAHELPONERROR This function is used to display help about an error returned by a function in the $result variable. When the $result variable contains help information about an error, the appropriate help file will be opened. In general, calling this function directly is not recommended because the function is also invoked by OASHOWERROR, when the user clicks the ‘Help’ or ‘Yes’ button in the message box. $status is not changed by this function. The following example displays error help information after invoking a method: . . . perform "OAINVOKE" perform "OAHELPONERROR" if ( $status = 0 ) ... ; set parameters for OAINVOKE ; invoke a method ; show help ; $status still from OAINVOKE! 11.5.4 OLE enumeration functions The OLE enumeration functions are described in the following section. OAENUMQUERY This function is used to retrieve an enumeration object from an OLE automation object. Enumerations are collections of other objects. The user can step through the different objects by using the OAENUMNEXT function. On input, the function receives the pointer to the OLE automation object in $12. On output, $15 contains the pointer to the Enumeration object. Proc Language Reference Manual, Volume 1 (Feb 1999) 11.5.4 OLE enumeration functions 11-21 UNIFACE V7.2 The following example retrieves the Enumeration object containing all worksheets of an Excel Application object, and changes the titles of the worksheets to ‘Doc 1’, ‘Doc 2’, and so on: $12 = $EXCEL_APP$ ; get application object $13 = "Worksheets" $14 = "" perform "OAGETPROPERTY" ; get worksheets object $12 = $15 perform "OAENUMQUERY" ; get enumeration of object $12 = $15 $91 = 1 ; initialize counter perform "OAENUMNEXT" ; first enumeration object while ( $status = 0 & $15 != "") $90 = $12 ; keep enumeration $12 = $15 $13 = "Name" $14 = "S;Doc %%$91" perform "OASETPROPERTY" ; change title $91 = $91 + 1 ; increment counter $12 = $90 perform "OAENUMNEXT" ; next enumeration object endwhile perform "OAENUMRELEASE" ; release enumeration OAENUMRELEASE This function is used to release a previously retrieved enumeration object. The following example releases an enumeration object after working on it: $12 = $EXCEL_APP$ $13 = "Worksheets" $14 = "" perform "OAGETPROPERTY" $12 = $15 perform "OAENUMQUERY" $12 = $15 . . . perform "OAENUMRELEASE" 11-22 11.5.4 OLE enumeration functions ; get application object ; get worksheets object ; get enumeration of object ; do something ; release enumeration (Feb 1999) Programming for OLE automation support UNIFACE V7.2 OAENUMRESET This function is used to reset an enumeration to the beginning, so that the next call to OAENUMNEXT will get the first object. The following example starts two loops on an enumeration, and resets the enumeration in between: $12 = $EXCEL_APP$ ; get application object $13 = "Worksheets" $14 = "" perform "OAGETPROPERTY" ; get worksheets object $12 = $15 perform "OAENUMQUERY" ; get enumeration of object $12 = $15 perform "OAENUMNEXT" ; start first loop while ( $status = 0 & $15 != "" ) . . . perform "OAENUMNEXT" endwhile perform "OAENUMRESET" ; reset enumeration perform "OAENUMNEXT" ; start second loop while ( $status = 0 & $15 != "" ) . . . perform "OAENUMNEXT" endwhile perform "OAENUMRELEASE" ; release enumeration OAENUMNEXT This function is used to get the next object of an enumeration. i Note: An enumeration must contain not only the objects, but also simple values, such as strings. On input, the function receives the pointer to the enumeration object in $12. On output, $15 contains the next object of the enumeration. This value is stored in the form of ‘Type ; Value’. When the enumeration contains no more objects, $15 is empty. The following example retrieves the enumeration object containing all worksheets of an Excel Application object, and changes the titles of the worksheets to ‘Doc 1’, ‘Doc 2’, and so on: $12 = $EXCEL_APP$ $13 = "Worksheets" $14 = "" perform "OAGETPROPERTY" $12 = $15 perform "OAENUMQUERY" $12 = $15 Proc Language Reference Manual, Volume 1 (Feb 1999) ; get application object ; get worksheets object ; get enumeration of object 11.5.4 OLE enumeration functions 11-23 UNIFACE V7.2 $91 = 1 ; initialize counter perform "OAENUMNEXT" ; first enumeration object while ( $status = 0 & $15 != "") $90 = $12 ; keep enumeration $12 = $15 $13 = "Name" $14 = "S;Doc %%$91" perform "OASETPROPERTY" ; change title $91 = $91 + 1 ; increment counter $12 = $90 perform "OAENUMNEXT" ; next enumeration object endwhile perform "OAENUMRELEASE" ; release enumeration 11.6 Examples The following examples help clarify the usage of the 3GL statements described in this chapter: • • • • Creation of an Excel object and transfer of data to it Creation of a Word object and transfer of data to it Interaction with a UNIFACE OLE container widget Creation of an Excel Chart based on data in UNIFACE 11.6.1 Creating an Excel object and transferring data to a worksheet This example creates an Excel object and transfers data into a sheet: 1. Create Excel Application. $13 = "Excel.Application" perform "OACREATEOBJECT" perform "OASHOWERROR" ; set object’s name ; perform function and create object This creates an Excel object. After the object has been created, the global variable $12 contains the value of the pointer to the object. Save the value of this pointer in a local variable. $EXCEL_APP$ = $12 11-24 11.6 Examples (Feb 1999) Programming for OLE automation support UNIFACE V7.2 2. Add a workbook to the Excel object. $12 = $EXCEL_APP$ $13 = "m;workbooks;m·;add;0" perform "OAEXECMULTI" perform "OASHOWERROR" ; set $12 to the saved value ; ; add workbook to the Excel object When the function OAEXECMULTI is performed, it returns the value of the pointer to a workbook object in the global variable $15. 3. Show the Excel Application. $12 = $EXCEL_APP$ $13 = "visible" $14 = "b;1" perform "OASETPROPERTY" perform "OASHOWERROR" ; set $13 to the visible property ; set $14 to the boolean value TRUE 4. Transfer data to Excel. $12 = $EXCEL_APP$ $13 = "pg;ActiveSheet;m;Range;1;s;a1;ps;Value;s;Data Value" perform "OAEXECMULTI" perform "OASHOWERROR" After the function is performed, the cell ‘A1’ in the current Excel sheet contains the value ‘Data Value’. 5. Delete the Excel object. At the end of testing this example, do not forget to delete the OLE object. $12 = $EXCEL_APP$ perform "OADESTROYOBJECT" perform "OASHOWERROR" i Note: The Excel application is not closed with this action. 11.6.2 Creating a Word object and transferring data to a document This example creates a Word object and transfers data into a document. 1. Create a Word Application. $13 = "Word.Basic" perform "OACREATEOBJECT" perform "OASHOWERROR" ; set object’s name ; perform function and create object After the object has been created, the global variable $12 contains the value of the pointer to the object. Save this value in a local variable. $WORD_APP$ = $12 Proc Language Reference Manual, Volume 1 (Feb 1999) 11.6.2 Creating a Word object and transferring data to a UNIFACE V7.2 2. Add a Document to the object. $12 = $WORD_APP$ $13 = "pg;FileNew;m;NewTemplate;0" perform "OAEXECMULTI" perform "OASHOWERROR" ; set pointer to object ; Word Basic command to open new document The contents of $13 depends on the language of the installed version of Word. Do not use the function OAINVOKE instead of OAINVOKEV because the Automation Server Word defines the function to create a new document as VOID, therefore OAINVOKE would create an error. 3. Show the Word Application. $12 = $WORD_APP$ $13 = "AppShow" perform "OAINVOKEV" perform "OASHOWERROR" ; set pointer to object ; Word Basic command ; Transfer data to Word. $12 = $WORD_APP$ $13 = "m;Insert;1;s;This is a new Text created by UNIFACE" perform "OAEXECMULTIV" perform "OASHOWERROR" To transfer data to Word, use the function OAEXECMULTIV and a command string in the register $13. Again, this function must be a void function which returns no value. 4. Delete the Word object. At the end of testing this example, do not forget to delete the OLE object. $12 = $WORD_APP$ perform "OADESTROYOBJECT" perform "OASHOWERROR" The Word application ends when performing this function. 11.6.3 Interaction with UNIFACE OLE container widget This example demonstrates the interaction between Word as OLE Automation Server and a UNIFACE container widget. Before this interaction takes place, create a link for the UNIFACE container widget to a Word document, click the right mouse button on the container widget and choose Insert, then close the Word application. The link between the container widget and Word is now established. 11-26 11.6.3 Interaction with UNIFACE OLE container widget (Feb 1999) Programming for OLE automation support UNIFACE V7.2 1. Create a Word object and get the pointer of this object. $13 = "fieldOLE.entry" perform "OACRFROMWIDGET" perform "OASHOWERROR" ; fieldOLE.entry is the Container Widget This call gets an OLE object so that you are able to show and edit the data held by the OLE object in your application. The function returns the pointer to the OLE object in the global register $15. You should save this value in a local variable. $WORD_APP$ = $15 2. Create a Word Basic object and get the pointer. $12 = $WORD_APP$ $13 = "pg;Application;pg;WordBasic" perform "OAEXECMULTI" perform "OASHOWERROR" This function call returns a pointer to the WordBasic object in the register $15. You should save this value in a local variable because you have to set register $12 to this value while working with the WordBasic object. $WORD_BASIC$ = $15 3. Activate the WordBasic object. $12 = $WORD_BASIC$ $13 = "<Name of the OLE Container Field in UNIFACE>" perform "OADOVERBWIDGET" perform "OASHOWERROR" Word has to become active as OLE Automation Server (to establish a link to the Word document of the Container Widget) before you can interact with the Word document. 4. Move the application window out of the screen display. Move the Word application out of the screen display, so that the UNIFACE user does not see the Word application. $12 = $WORD_BASIC$ $13 = "AppMove" $14 = "i;0;i;1000" perform "OAINVOKEV" perform "OASHOWERROR" Proc Language Reference Manual, Volume 1 (Feb 1999)11.6.3 Interaction with UNIFACE OLE container widget 11-27 UNIFACE V7.2 5. Transfer data to the OLE object. $12 = $WORD_BASIC$ $13 = "Insert" $14 = "s;sample text..." perform "OAINVOKEV" perform "OASHOWERROR" These instructions update the data in the OLE object. The update in the Container Widget is controlled by a timer. If you want to see the update you can use the function ‘OAUPDATEWIDGET’. 6. Update the widget. $12 = $WORD_BASIC$ $13 = "<Name of the OLE Container Field in UNIFACE>" perform "OAUPDATEWIDGET" perform "OASHOWERROR" This command updates the view of the widget in your application. Move the widget back to the screen display After interacting with the Word application, move the window of the OLE Automation Server, MS Word, back into the screen display. To do so, use the commands above (point 4), but replace the value 1000 with 0. 7. Close the widget. $12 = $WORD_BASIC$ $13 = "<Name of the OLE Container Field in UNIFACE>" perform "OACLOSEWIDGET" Close the widget and destroy the link on it. 8. Delete the pointer to the object. $12 = $WORD_APP$ perform "OADESTROYOBJECT" This deletes the pointer to the OLE object. 11.6.4 Creating an Excel Chart object This example creates an Excel Chart object. 1. Create the Excel Application. $13 = "Excel.Application" perform "OACREATEOBJECT" perform "OASHOWERROR" 11-28 11.6.4 Creating an Excel Chart object ; set object’s name ; perform function and create object (Feb 1999) Programming for OLE automation support UNIFACE V7.2 This creates an Excel object. After the object has been created, the global register $12 contains the value of the pointer to the object. Save the value of this pointer in a local variable. $EXCEL_APP$ = $12 2. Add a workbook to the Excel object. $12 = $EXCEL_APP$ $13 = "PG;workbooks;M;add;0" perform "OAEXECMULTI" perform "OASHOWERROR" ; set $12 to the saved value ; add workbook to the Excel object When the function OAEXECMULTI is performed, it returns the value of the pointer to a workbook object in the global register $15. Save the value of this pointer in a local variable. $EXCEL_WORKBOOK$ = $15 $12 = $EXCEL_APP$ $13 = "visible" $14 = "B;1" perform "OASETPROPERTY" perform "OASHOWERROR" ; Show the Excel Application ; set $13 to the visible property ; set $14 to the boolean value TRUE 3. Get a pointer for the active sheet object. $12 = $EXCEL_APP$ $13 = "PG;ActiveSheet" perform "OAEXECMULTI" perform "OASHOWERROR" ; set $12 to the saved value ; get the active sheet When the function OAEXECMULTI is performed, it returns the value of the pointer to a sheet object in the global register $15. Save the value of this pointer in a local variable. $EXCEL_SHEET$ = $15 4. Transfer data to Excel. $12 = $EXCEL_SHEET$ $13 = "M;Range;1;S;a1:c2;PS;Value;A;2;2;3;I;1;I;2;I;3;I;4;I;5;I;6" perform "OAEXECMULTI" perform "OASHOWERROR" After the function is performed, the cells ‘A1:C2’ in the current Excel sheet contain the data values. 5. Get a pointer for a Range object to create a chart. $12 = $EXCEL_SHEET$ $13 = "M;Range;1;S;a1;c2" perform "OAEXECMULTI" perform "OASHOWERROR" Proc Language Reference Manual, Volume 1 (Feb 1999) ; set $12 to the saved value ; get the range 11.6.4 Creating an Excel Chart object 11-29 UNIFACE V7.2 When the function OAEXECMULTI is performed, it returns the value of the pointer to a range object in the global register $15. Save the value of this pointer in a local variable. $EXCEL_RANGE$ = $15 6. Create a chart. $12 = $EXCEL_SHEET$ ; set $12 to the saved value $13 = "M;ChartObjects;0;M;Add;4;F;0.0;F;0.0;F;200.0;F;100.0;M;Select;0" perform "OAEXECMULTI" perform "OASHOWERROR" When the function OAEXECMULTI is performed, a chart is created. Set data rows of the chart. $12 = $EXCEL_APP$ ; set $12 to the saved value $13 = "PG;ActiveChart;M;ChartWizard;11;%%$EXCEL_RANGE$;%\ I;-4100;I;4;I;1;I;0;I;0;I;1;S;;S;;S;;S;" perform "OAEXECMULTI" perform "OASHOWERROR" When the function OAEXECMULTI is performed, a chart contains data. 7. Delete the Excel Range object. At the end of testing this example, do not forget to delete the OLE object. $12 = $EXCEL_RANGE$ perform "OADESTROYOBJECT" perform "OASHOWERROR" 8. Delete the Excel Sheet object. At the end of testing this example, do not forget to delete the OLE object. $12 = $EXCEL_SHEET$ perform "OADESTROYOBJECT" perform "OASHOWERROR" 9. Delete the Excel Workbook object. At the end of testing this example, do not forget to delete the OLE object. $12 = $EXCEL_WORKBOOK$ perform "OADESTROYOBJECT" perform "OASHOWERROR" 11-30 11.6.4 Creating an Excel Chart object (Feb 1999) Programming for OLE automation support UNIFACE V7.2 10. Delete the Excel object. At the end of testing this example, do not forget to delete the OLE object. $12 = $EXCEL_APP$ perform "OADESTROYOBJECT" perform "OASHOWERROR" i Note: The Excel Application is not closed with this action. Proc Language Reference Manual, Volume 1 (Feb 1999) 11.6.4 Creating an Excel Chart object 11-31 UNIFACE V7.2 11-32 11.6.4 Creating an Excel Chart object (Feb 1999) Programming for OLE automation support