Vine OLE Objects Overview

Vine for Windows OLE Objects Overview

Vine OLE Automation server included into the Vine windows client exposes the following types of objects: Vintage, VintageObject, VintageObjects, VintageObjectsSet, VintageStream, VintageWindow.

You can programmatically manipulate these objects by invoking their methods or by getting and setting the objects' properties. The Type Library contains definitions of all the objects the Automation server provides, including definitions for all available methods, properties, and events.

Below you will find a description of all the Automation objects. Their properties, events and methods are grouped by the type of objects and described in alphabetical order.

About obsolete interfaces

A number of interfaces better suited for use with .Net have been introduced in Vine. It is highly recommended to start using the following new interfaces:

• IVintage4 interface instead of IVintage

• IVintageObject4 instead of IVintageObject

• IVintageObjects4 instead of IVintageObjects

• IVintageWindow4 instead of IVintageWindow.

• _IVintageEvents4 instead _IVintageEvents

Old Vintage, VintageObect, VintageObjects and VintageWindow interfaces will still be supported for some time, but they are going to be discarded in future versions of Vine for Windows.

Note: All the new interfaces are the default ones for the corresponding COM objects. That is why you have to explicitly specify the old interface if you have to use it.

For example, if you want to compile your old VB6 code which uses the old interafces then you might have to change

Dim vapp As Vintage

Dim vobj As VintageObject

into

Dim vapp As IVintage

Dim vobj As IVintageObject

Otherwise, the compiler will generate errors since

Dim vapp As Vintage

implies the use of the IVintage4 interface.

Vintage interface

The first thing you will always need to do in order to use the Vine Automation objects is to create a Vintage application object.

Note: Please note that "Vintage" is the former name of the Vine for Windows application. Hence, "Vintage" is the name of the main application object and is included in names of most interfaces.

For brevity, the creation of the Vintage application object will be often omitted in the examples below. Using early binding this can be done with the following code:

C#:

Vintage vapp = new Vintage();

VB6:

Dim VintageApp As Vintage

Set VintageApp = New Vintage

The Vintage object gets you access to a variety of methods, properties and events that can be used to manipulate Vintage functionality.

Object Management

Methods:

• NewObject creates a new Vine object.

• SearchObjects/SearchObjectsAsync returns a VintageObjects collection that contains Vine objects matching the given ObjectType and ObjectName strings.

• Events:

The Vintage object is able to raise events, what gives you the ability to customize Vine functionality by intercepting main user operations and executing your own code.

• ObjectKeyChanging is triggered before the object ID changes.

• ObjectKeyChanged is triggered after the object ID changes but before the connections are updated.

• ObjectSaved is triggered when the object is saved. The corresponding VintageObject with an already generated ID is passed.

• StartConnectingObjects is triggered when a connection is about to be created, but before it is actually created.

• StartDeleteObject triggered when the Vine user tries to delete an object, but before it is actually deleted.

• StartDisconnectingObjects is triggered when a connection is about to be removed, but before it is actually removed.

• StartEditObjectInWindow is triggered when the Vine user tries to open an object's edit form, but before the form actually opens.

• StartMenuCommandInWindow is triggered when user selects a command in a menu or toolbar. Context menu does not send any events.

• StartOpenObjectInWindow is triggered when the Vine user tries to open an object, but before the object opens.

• StopEditObjectInWindow triggered when the Vine user tries to close an object's edit form by clicking Save, but before the form window closes.

Getting Object Reference

• GetDefaultObject returns a VintageObjects collection that contains the default object, i.e. the object of a given type last used in Vintage.

• GetLocalObjects returns Vintage objects of the defined object type. The result set contains references to all Vintage objects from the defined table located in the current local database.

• GetObject/GetObjectAsync returns a VintageObjects collection that contains the Vintage object identified by its type and ID.

• GetSelectedObjects returns a VintageObjects collection that contains selected objects of a given type.

• GetPossibleConnectionTypes returns a VintageObjects collection that contains all possible connection types between the given object types.

SQL

• ExecuteSQL & ExecuteSQLAsync gives you two different ways to execute SQL clauses.

• GetSQLForTableView takes an object type and a "where" SQL part as parameters and returns a complete SQL string to get all object fields. This string can then be directly used in the ExecuteSQL method.

• NewSQLParameterObject creates a VintageObject collection to be used as a parameter set for ExecuteSQL. AddSQLParameterField should be used to add fields to this collection.

Server Connection/Sync

Methods

• IsConnected checks the server connection

• SynchronizeWithServer forces synchronization process.

Events:

• StartSync triggered when the local and server databases are about to be synchronized.

• ContinueSync triggered when the synchronization between the local and server databases is about to be continued.

• EndSync triggered when the synchronization operation has ended.

• The ServerConnect and ServerDisconnect events notify you of the server connection status.

• StartQuit triggered when the Vintage user tries to quit the program, but before the program is terminated.

• Quitting triggered when the Vine application is going to quit. It is different from StartQuit in that it doesn’t have a parameter which can cancel quitting. That is when plugin receives this event it can be sure that no one will cancel quitting of the Vine application.

Windows/Menu Management

• The TopWindow property contains the currently topmost Vine main window. If the value is changed to contain some other main window, it will be changed to be the topmost main window.

• The NewWindow method creates a new Vine window and optionally loads an ActiveX control in it.

• The NewDotNetWindow method creates a new Vine window and loads a .NET control in it.

• The UpdateMenu method forces menu update. It queries the active VintagePlugin to refresh menu and toolbar items state.

Clipboard

• CopyObjectsToClipboard copies objects to the Clipboard

• GetObjectsFromClipboard returns a VintageObjects collection of objects in the Clipboard.

• CheckObjectsInClipboard checks whether there are objects in the Clipboard.

Drag and Drop

The following methods support drag and drop functionality:

• VintageObjectsToObjectData transforms Vobjs into the format acceptable for the DataObject type which is the OLE drag&drop repository.

• ObjectDataToVintageObjects transforms DataBuffer from the DataObject OLE drag&drop repository into Vobjs.

The ObjectDragType property indicates the type of data that is dragged to the receiving application.

Phone / SMS

• PhoneEnabled returns true if the phone support has been enabled in the Vine application (phone numbers are shown as hyperlinks.

• SMSEnabled returns true if the sms support has been enabled in the Vine application (small SMS icons are shown after mobile phones.

• PhoneCall initiates a phone call.

• SendSMS sends a message.

Misc

• VintageVersion is a read-only property that returns the version of the Vine application.

• GetUser is a method that returns the current database user name.

• LaunchPlugin is a method which runs one plug-in from another.

• LaunchReport creates a vintagewindow and loads crystal (type 8) or vine (type 7) report in it.

• LaunchReportEx can be used to launch a crystal report and print or export it to a file directly without showing the report window.

VintageEmailer

VintageEmailer is an interface provided by Mail Wizard to send an e-mail from a plugin without showing standard Mail Wizard’s user interface. It allows using an existing emtex file and passing a parameter object to fill in the template text place holders

Methods:

• GeneratePreview creates an html that can be for example passed to a WebBrowser control to be shown to the user.

• SendEmail generates and sends an email (passed as an emtex file) to a collection of Vine persons.

Events:

• RecipientProcessed is triggered for each recipient which allows you to check whether the email was sent successfully to each recipient or if there was some problem.

Properties:

Use the EmailEvent property to receive a Vine event (as a VintageObject) created for a sent email (one event is created for a SendEmail call).

If an error happend while sending an email to each recepient, you can get information about the error, using the errorCode and errorMessage properties.

Service Request Send Email Tool

The Send Email tool (used in service requests) expects custom .emtex files (stored as support plug-ins in the database) to have "services_" at the beginning of the file name.

VintageObject

VintageObject is a reference to a Vine database object. The following objects are currently supported:

• Regular Vine objects, i.e. nine standard objects and any custom objects.

• The following not regular objects: connections, parameters (i.e. phase / type tables), VY_TABLE, VY_TABLE_FIELD. These objects have considerable limitations, for instance the Open, Edit methods cannot be invoked for these objects.

The ID, ObjectName and ObjectType properties are for getting the object's ID, type and name respectively.

You can get or set the value of any object's field by using the Value property.

Note that it is necessary to always explicitly save changes, using the SaveChanges method, after making any changes using the Value property. Changes can be cancelled by calling CancelChanges.

General

The VintageObject contains the Open, Delete methods to respectively open, delete an object and the Edit method that permits you to open the object's edit form.

• DuplicateObject creates a copy of the current object.

Binary Fields

A number of methods support writing/reading raw binary data into/from an object's field. For instance, the FileToLongRaw and LongRawToFile methods support data exchange with files and the BytesToLongRaw and LongRawToBytes methods operate with bytes stored in the memory.

The NewStream method creates a Vine binary stream object.

Connections

With the GetConnectedObjects/GetConnectedObjectsAsync method you can get all the object's connected objects and with the GetConnections/GetConnectionsAsync method you can get a list of all the object's connections.

• AddConnection creates a connection of a given type between current and traget objects.

• DuplicateConnections copies all connections of one object into connections of another.

• ConnectObjects creates a connection between two objects using their references. It should be used to:

• Connect objects to excluding collections;

• Handle "limited" connections, i.e. when only a single connection of the type is permitted for one or both of its ends. If the method finds that the "From" or "Target" object has a connection of that "limited" type already, then it removes the found connection and creates the new one.

• Handle connections to repeating events

SQL

Using AddSQLParameterField you can add fields to a VintageObject collection created with NewSQLParameterObject.

VintageObjects

VintageObjects is a collection of Vine objects. Vine OLE functions often return a reference to the VintageObjects collection even if it includes a single returned object. It is because the VintageObjects type receives events from Vine but the VintageObject type does not.

To get a reference to a particular object in the collection, use the Item property by providing a numeric index of the object in the collection.

Use the Count property to get the number of objects in the collection.

GetEnumerator is implemented which makes VintageObjects an enumerable collection and allows using the foreach method.

VintageObjects exposes methods that greatly simplify common set operations:

• DeSelect - Deselects the objects selected by the preceding Select method and selects the other objects.

• Intersection - Takes intersection of two VintageObjects collections.

• Minus - Removes the objects of one collection from the objects of the other.

• Select - Selects objects in the specified range.

• SelectLike - Selects objects by text in a field.

• SortBy - Sorts the items of a collection.

• Union - Combines objects from two collections.

• Delete – Deletes all objects in a collection. Can show a confirmation dialog, if needed.

• MarkObjects - Marks row or row range "selected" in a VintageObjects collection.

• SelectMarkedObjects - Return a new VintageObjects collection containing all the rows marked "selected" with previous MarkObjects calls. The selection will be cleared.

The important method SQLResultToVintageObjects converts a group of objects returned by the ExecuteSQL method into real Vine objects.

GetConnectedObjects allows you to get:

• Connected objects(e.g. employer companies) from a vintageobjects set of connections

• Connection types from a set of connections

• Connections (e.g. “employer” connections) from a set of objects (e.g. persons).

LockChanges locks/unlocks a vintageobjects collection, so that one can safely use it. Calling lockchanges with false needed to start getting events for the collection.

ConnectObjects connects all objects in a vintageobjects collection to another object.

PrintObjects prints objects in a vintageobjects collection.

Events:

The AddObject, DeletingObject, ObjectChanged and ObjectDeleted events notify you about any changes that happen in the collection so that you can adequately react to them.

QueryReady is triggered for this vintageobjects collection when an async operation with it is over.

QueryReceivedBinaryPiece informs about the progress of downloading big binary fields.

VintageObjectsSet

VintageObjectsSet is a collection of VintageObjects objects. A VintageObjectsSet can include several VintageObjects collections with different object types.

To get a reference to a particular object in the collection, use the Item property by providing a numeric index of the object in the collection.

Use the Count property to get the number of objects in the collection.

Use the Add method to add a VintageObjects collection and the Remove to delete a collection.

The object uses exactly the same events AddObject, DeletingObject, ObjectChanged and ObjectDeleted as VintageObjects with only one additional argument specifying the place of the target VintageObjects collection in the set. The events are needed to pass information about VintageObjects changes to a correct collection.

VintageStream

VintageStream is a stream of an ordered sequence of bytes with a pointer always showing the current position at that sequence. When created, a Vine stream is connected to a binary ("long raw"/blob type in Oracle) field of the specified Vine object. Reading and writing sequences of bytes directly from/to that field is possible using the methods of the VintageStream object.

To get or set the size of a stream, use the Size property.

To get or set the current position in a stream, use the Position property.

• ReadByte reads and returns a byte at the current position from the open stream.

• ReadBytes reads a number of bytes from the stream to BytesToRead.

• ReadInteger reads and returns an integer at the current position from the open stream.

• ReadLong reads and returns a long number at the current position from the open stream.

• ReadPascalString reads and returns a Pascal string from the current position of the open stream.

• ReadString reads and returns a string at the current position from the open stream.

• ReadUnicodeString reads and returns a Unicode string at the current position from the open stream.

• WriteByte writes a given byte to the current position of the open stream.

• WriteBytes writes the contents of the BytesToRead variable from the current position in the stream.

• WriteInteger writes a given integer from the current position of the open stream.

• WriteLong wites a long number at the current position from the open stream.

• WritePascalString writes a Pascal string (the first byte keeps the length of the string) from the current position of the open stream.

• WriteString writes a given string (StringToWrite) from the current position of the open stream.

• WriteUnicodeString writes a given Unicode string (StringToWrite) from the current position of the open stream.

VintagePlugin

The VintagePlugin COM interface passes information to/from plug-ins running inside the main Vine window. Plug-ins can implement the interface in case they need any of the information passed through the interface.

Properties

• SelectedObjects – read-only property which the plug-in should implement in order to return selected objects to the caller. Called if CanEnableMenuCommand returns EnableIfObjectSelected or DoMenuCommand returns Handled = False.

• Title – read-only property returning the title of the plug-in.

• VintageObjects passes vintage objects to the plug-in.

• VintageWindow passes to the plug-in the VintageWindow which the plug-in works in.

Methods

• CanEnableCommand called to find out whether a specific menu command can be enabled.

• DoCommand called when the user selected some menu command.

VintageWindow

The VintageWindow COM interface can be used to handle requests to the main window functionality. The interface can be implemented by a plug-in to provide main window functionality.

Properties

• ActiveWindowObject sets the active window object. Used e.g. to change the window title.

• DefaultObject sets/gets a default object of the given type.

• height sets / gets the height edge of the main window.

• historyPanelVisible sets / gets the visibility of the history panel.

• left sets / gets the left edge of main window.

• toolBarVisible sets / gets the visibility of the toolbar.

• toolPanelVisible sets / gets the visibility of the tool tabs panel.

• top sets / gets the top edge of main window.

• Vintage read-only gets the current instance of IVintage

• Visible sets / gets the visibility of the main window.

• width sets / gets the height edge of the main window.

Methods

• BringPluginToTop brings the given plug-in to the top

• BringWindowToTop brings this main window to the top.

• CloseWindow closes this main window.

• LaunchPlugin/LaunchPluginEx/LaunchdotNetPlugin runs a plug-in inside a Vine main window. LaunchPluginEx has a parameter controlling whether a standard Vine plugin border is shown. LaunchdotNetPlugin is able to launch .NET plugin.

• move moves (and resizes) the window to a new position on screen.

• OpenObject opens an object in this main window.

• OpenCalendar opens the calendar and loads a vintageobjects collection

• SetHelpText sets the help text in the bottom of the main window.

• ShowContextMenu shows the context menu for objects (& their connections) in the passed vintageobjects collections and returns the selected command.

• ShowDialog shows a dialog with given Title, Description and Style. Returns the result of the user action.

Error Handling

Errors can occur inside Vine OLE methods.

The following table lists the defined error constants:

Constant	Code	Err.Description
Err_NoPrivileges	-2	"Not enough privileges to do that"
		Explanation: The user tries to change or delete a protected object.
Err_ObjectIsDeleted	-4	"Objects data do not exist anymore. You try to use Vine object that is already deleted."
Err_NoSuchField	-6	"There is no such field in this object"
		Explanation: Using the VintageObject.Value property, you attempted to access a nonexistent field.
Err_FieldTypeMismatch	-7	"Field type mismatch"
		Explanation: Using the VintageObject.Value property, you attempted to assign a value of the wrong type to an object field, e.g. a string to a number field.
Err_ObjectTypeEmpty	-11	"Object type cannot be empty"
Err_ObjectTypeUnknown	-12	"Object type is unknown"
Err_ObjectNotFound	-13	"Object is not found"
Err_ConnectionTypeUnknown	-14	"Connection type is unknown"
Err_FieldNameEmpty	-15	"Field name cannot be empty"
Err_InvalidDate	-17	"Invalid date format. Try DD.MM.YYYY HH:MI or just DD.MM.YYYY with day events"
Err_FieldLocked	-20	"You cannot change Objects ID,Status, CHANGEDATE, CHANGEUSER fields"
Err_StringTooLong	-22	"String is too long for this field"
Err_NumberOverflow	-23	"Number is too long for this field"
Err_ObjectChangedButNotSaved	-25	"You changed object but you did not call SaveChanges"
		Explanation: You need to call the VintageObject.SaveChanges method after altering any object's field.
		Attention: This error has been removed in Vine/Vintage 4.5.4. It is the developer’s responsibility to call SaveChanges.
Err_SqlResultNotSupported	-26	"Sorry - You cannot do that with SQL query result"
		Explanation: You cannot save or delete objects which are returned by the ExecuteSQL method.
Err_SqlParseFailed	-27	SQL clause is invalid. Check SQL command syntax
Err_SqlNeedsServerConnection	-33	"ExecuteSQL needs connection to server. It is not working with local DB."
Err_EmptyObject	-34	"Cannot save empty object. You must change at least one field before calling SaveChanges."
Err_ConnectionTypeMismatch	-101	"Connection type mismatch. Object types are different that given LinkType parameter defines"
		Explanation: The connection's type (recognized by its ID or, what is the same, its LinkType) specifies the "from/target" object types. If the types of the objects to be connected do not match the LinkType, the error will be generated.
Err_ConnectionExist	-102	"Connection already exists"
		Explanation: You attempted to create the connection that already exists between the from/target objects.
Err_ConnectionCountFull	-103	"Exclusive connection error. Similar connection between one of these objects already exists."
		Explanation: Certain types of connections cannot have more than one "from" or "target" object. If you try to create one more connection of this type the error will be generated.
Err_NoTopWindow	-104
Err_UnknownException	-105
Err_NotProperObjectType	-106
Err_FieldTypeIsNotBinary	-201	"Field type is not binary"
Err_FileOpenFailed	-204	"File not found or is locked"
Err_IndexOutOfRange	-209	"Line number is out of range"
Err_InvalidParameter	-210	"Invalid parameter"
Err_EndOfStream	-212	"End of stream"
Err_CannotDeleteSelf	-241	Cannot delete self person object
Err_NoConnectionType	-242	There is no connection type between these objects
Err_ObjectParameterNull	-243	Object parameter cannot be NULL
Warn_UserCancel	-246	User canceled operation
Err_CannotDeleteAllLocalObjects	-247	Cannot delete all local objects
Err_UnknownServerError	-248	Unknown server error
Err_NameEmpty	-249	Name Empty. Returned on attempt to set name field to empty string using vintageobject.value
Err_LocalDBNotOpen	-250	Local database not open. Returned when the local db is not yet open or shutting down.
Err_NotSQLParameterObject	-253	"This operation is used only with SQLParameterObject."