Obsydian OLE Automation l Ranjit Sahota l Chief

Obsydian OLE Automation l Ranjit Sahota l Chief Architect l Obsydian Development

Session Outline l Obsydian OLE Automation Overview l Microsoft OLE Automation Overview l Obsydian OLE Automation Framework l Obsydian OLE Properties and Methods l Examples and Demonstrations l Obsydian DCOM Support l Summary, FAQ and Questions © 1998 Synon, Inc. Obsydian OLE Automation 2

Obsydian OLE Automation Overview l Obsydian Functions can be used other application environments such as VB, Office 97, C++ l Obsydian Functions can be used with MTS l Functions can seamlessly inter-operate with multiple development environments l Functions can be used simultaneously with OLE and with normal Obsydian applications l Functions can be remoted using DCOM l Microsoft OLE Automation Supported © 1998 Synon, Inc. Obsydian OLE Automation 3

Microsoft OLE Automation Overview OLE Automation Controller Create an Object Get Existing Object Get / Set Properties Invoke Methods OLE Type Library (. TLB) Dispatch Methods Automation Server Description Object Property and Method Interfaces Help Text for Objects OLE Automation Server Expose Object Properties & Methods Manage Object Creation Manage Object Properties Implement Object Methods © 1998 Synon, Inc. Obsydian OLE Automation 4

OLE Automation Objects l An Instance of a Class ( same as COM) l Exposes Properties l Exposes Methods l Exposes Events l Automation Controller Use Objects l Automation Server Implement Objects © 1998 Synon, Inc. Obsydian OLE Automation 5

Excel 97 Object Model © 1998 Synon, Inc. Obsydian OLE Automation 6

OLE Automation Type Libraries l Define Object Properties and Methods l Source Code with ODL Syntax l ODL = Object Description Language l ODL Syntax based on DCE RPC IDL l Compiled as. TLB File l Interfaces and Methods Exposed © 1998 Synon, Inc. Obsydian OLE Automation 7

OLE Automation Servers l Provides Automation Object Services l Manages and Implements Objects l Implements Business or Service Logic l In Process and Out of Process Servers l DCOM and Active. X Servers © 1998 Synon, Inc. Obsydian OLE Automation 8

OLE Automation Controllers l Clients of OLE Automation Objects l Manipulates and Drives Objects l OLE Automation Client Environments l OLE Automation Support l Visual Basic, VBA and VB Script l Java and Visual C++ l Delphi, Power Builder and Others l Any COM capable environment © 1998 Synon, Inc. Obsydian OLE Automation 9

Obsydian Automation Framework C++ OLE Java Automation OLE VBA Client Automation OLE Basic Visual Client Automation OLE Client Automation Client Microsoft OLE Automation COM Component Object Model Architecture Overview © 1998 Synon, Inc. Obsydian OLE Automation IPC Obsydian OLE Automation Framework Obsydian Generated Function 10

Obsydian OLE Automation Features n Obsydian Functions can be called from: • Visual Basic, VBA for Office 97, C/C++, VB Script • Java, Power Builder and other Tools n Provides automatic data type mapping • Obsydian data types <-> OLE data types n No changes required to existing designs © 1998 Synon, Inc. n Exposes Simple Generic Programmable Objects n Obsydian Functions can be used by DCOM Obsydian OLE Automation 11

Obsydian OLE Objects n App Object • Obsydian Application Environment • Manages Run Time System Objects • Corresponds to one OBRUN. EXE Process n Function Object • Obsydian generated function proxy • Wrapper to actual generated function • Call method allows function to be invoked © 1998 Synon, Inc. Obsydian OLE Automation 12

Obsydian Process Model Client Process Server Process OLE Automation Client Obsydian OLE Automation Framework App Object Function Object Microsoft OLE Automation OBRUN Application Process Obsydian Generated Function Microsoft OLE Automation © 1998 Synon, Inc. IPC Obsydian OLE Automation 13

Obsydian OLE Cardinality Model Client Process OLE Automation Client © 1998 Synon, Inc. Server Processes IPC App Object Function Object Function Object App Object Function Object Obsydian OLE Automation 14

App Properties and Methods n Properties: • enviornment. Key – This key is used to control the application environment settings for Obsydian. These environment settings are specified in the OBRUN. INI file for (16 and 32 Bit clients) or in the System Registry (for 32 Bit NT Servers). These settings include ODBC data source configuration and other variables used by the runtime system. This environment. Key property allows you to control which INI file (or registry entry key for NT) should be used to get the environment settings. n Methods: • Function(file. NME As String, implementation. NME As String) – This method creates and returns an Obsydian OLE Function object. This Function object is used to make the actual function call to the generated function. The file. NME string parameter specifies the function’s external DLL file name. © 1998 Synon, Inc. Obsydian OLE Automation 15

Function Properties and Methods n Properties: • file. NME – This name represents the implementation object that is loaded when the Obsydian run time system attempts to call this function. • implementation. NME – This name represents the entry point of the DLL. This is normally the same as the file. NME. n Methods: • Call(In. Parms As Variant, Out. Parms As Variant) – This method locates, loads and calls an Obsydian generated Function. – The In. Parms and Out. Parms are OLE Safe. Array Variant objects that contain the input, dual and output parameters for the function to be called. All of the input and dual parameters for the function should be contained as elements in the In. Parms array and all of the output parameters should be contained in the Out. Parms array. © 1998 Synon, Inc. Obsydian OLE Automation 16

Obsydian OLE Class Table Ob. Run and OLE Class Name Table The table above represents the OLE class names and the corresponding OBRUN EXE that is called when an App is created. The class name is used to qualify the App object to create the correct type of Application environment object. For example, if you use the Class Name “Ob. Run. OLE 300 RSD. App”, to create the App object, OLE Automation will start up a process that begins with OB 300 RSD. EXE. This will then create the Application environment designed to call Obsydian generated functions built for Obsydian 32 Bit NT Debug execution. © 1998 Synon, Inc. Obsydian OLE Automation 17

Visual Basic 5. 0 Example Microsoft OLE Automation © 1998 Synon, Inc. Obsydian OLE

Visual Basic Code Create Obsydian App and Function Objects: Dim Fnc. File. Nme As String Dim Fnc. Impl. Nme As String '--------------------------------' 'Create the Obsydian application object' '--------------------------------' Set Ob. App = Create. Object("Ob. Run. OLE 300 RCD. App") '--------------------------------' 'Create the Obsydian functions that we want to call' 'Category. Get Sequential' '--------------------------------' Fnc. File. Nme = "AAVF" Fnc. Impl. Nme = "AAVF" Set Category_Get. Sequential = Ob. App. Function(Fnc. File. Nme, Fnc. Impl. Nme) © 1998 Synon, Inc. Obsydian OLE Automation 19

Visual Basic Code Define and Populate Parameters: '--------------------------------' 'Define the Input, Dual and Output Parameter Arrays '--------------------------------' Dim In. Parms(5) As Variant '6 Element Variant Array' Dim Out. Parms(24) As Variant '25 Element Variant Array' '--------------------------------' 'Set the input and dual parameters for Category. Get. Sequential' '--------------------------------' In. Parms(0) = "" 'D: Returning Status' In. Parms(1) = "" 'I: Positioner. Category Code' In. Parms(2) = "1" 'I: Input. Instance to get' In. Parms(3) = 500 'I: Input. Instances to filter' In. Parms(4) = "" 'I: Selections. Category Code' In. Parms(5) = "" 'I: Selections. Category Name' © 1998 Synon, Inc. Obsydian OLE Automation 20

Visual Basic Code Invoke the Obsydian Function: '--------------------------------' 'Set the input and dual parameters for Category. Get. Sequential' '--------------------------------' In. Parms(0) = "" 'D: Returning Status' In. Parms(1) = "" 'I: Positioner. Category Code' In. Parms(2) = "1" 'I: Input. Instance to get' In. Parms(3) = 500 'I: Input. Instances to filter' In. Parms(4) = "" 'I: Selections. Category Code' In. Parms(5) = "" 'I: Selections. Category Name' '--------------------------------' 'Call Category. Get. Sequential' '--------------------------------’ Category_Get. Sequential. Call In. Parms, Out. Parms © 1998 Synon, Inc. Obsydian OLE Automation 21

Visual Basic Code Use the Dual and Output Parameters: '--------------------------------' 'Read Out. Parms and Populate the VB Grid Control' '--------------------------------' n. Rows = Out. Parms(24) ' Instances Fetched’ ' Add the retrieved records to the grid' For Row = 0 To (n. Rows - 1) 'Build a grid entry for each column' For Col = 0 To (n. Cols - 1) Col. Text = Out. Parms(Row * n. Cols + Col) Entry = Entry & Chr(9) & Col. Text Next Grid 1. Add. Item Entry, Row + 1 Next © 1998 Synon, Inc. Obsydian OLE Automation 22

VBA Office 97 Excel Example Microsoft OLE Automation IPC Obsydian OLE Automation Framework AAVF

Visual C++ Example Microsoft OLE Automation IPC Obsydian OLE Automation Framework AAVF Category Get

“Live” VBA Power. Point Demo Microsoft OLE Automation IPC Obsydian OLE Automation Framework AAVF

Installation and Registration n Install Obsydian Runtime System(s) n Register the Obsydian Runtime Systems() • OB 300 RC. EXE /Register • OB 300 RS. EXE /Register • OB 300 RN. EXE /Register © 1998 Synon, Inc. n Updates Windows OLE Registry Database n Install Type Libraries with Visual Basic • OB 300 RC. TLB, OB 300 RN. TLB etc. n Online Obsydian OLE Help File • OLE. HLP Obsydian OLE Automation 26

DCOM Overview Client Machine Server Machine Visual Basic OLE Automation Client Microsoft OLE Automation © 1998 Synon, Inc. COM DCOM Services DCE RPC Obsydian OLE Automation Obsydian Generated Function Obsydian OLE Automation Framework COM DCOM Services Microsoft OLE Automation 27

DCOM Configuration l DCOMCNFG. EXE l Specify Application Locations l Specify Security Attributes l Configure DCOM on Remote System(s) l Install Application on Remote System(s) l Run Client Application as Normal l Client now Creates App Objects Remotely © 1998 Synon, Inc. Obsydian OLE Automation 28

DCOM Configuration Example © 1998 Synon, Inc. Obsydian OLE Automation 29

Obsydian OLE Automation Summary l Functions can participate in MS Component and Object Integration Technologies l Functions can seamlessly inter-operate with multiple development environments l Functions can be used simultaneously with OLE and with normal Obsydian applications. l Functions can be remoted using DCOM l Obsydian applications can be tightly integrated into MS based applications © 1998 Synon, Inc. Obsydian OLE Automation 30

Obsydian OLE Automation FAQ n How do I prepare a function to be used as an OLE Automation Server? n How do I set up the parameter interface for the function I want to call? n Why do I have to pass parameters in Safe. Arrays? n Why can’t I just pass in each variable or field as structures? n How are Obsydian data types mapped between Variants? n What is a Type Library and how are they used for OLE Automation? n What is a Variant and Safe. Arrays and how do they work? n How do I find out more information about COM and OLE Automation? n How do I find out more about using VB and OLE Automation Servers? © 1998 Synon, Inc. Obsydian OLE Automation 31