1. technology and computing
2. programming languages
3. visual basic

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