Concept

Think of a client application for the Exact Venice SDK as a regular user of Venice. A user starts Venice, logs on, selects a dossier and if desired a financial year and starts a module like customers or sales.

The SDK client application performs similar actions by creating objects. First it creates the Venice-object (i.e. starting Venice). The newly created Venice object has several logon methods: Logon, LogonSecure , LogonDialog and LogonCurrent . One of these methods must be called by the client application to log on into the Venice object.
The next step is to select a dossier. This is done by creating a DossierContext object (CreateDossierContext). In that DossierContext object, a module is launched by calling the create method of the corresponding interface, e.g. launching the customer module is done by creating a Customer object (CreateCustm).

Done! The customer module is started and is ready to accept your commands. Most commands which are available in the customer module have equivalent methods in the customer object. You can e.g. browse the customer file (Browse), start a dialog to insert a new customer (Insert) or import new customers from a text file (Import).

Each object can only be created in its appropriate context. The Venice object must be created first. This Venice object contains methods which are only meaningful at the root level (e.g. Logon) and cannot create other objects than the DossierContext object. The Dossier context has a few properties (the name, the last financial year,...) and can create many objects that run on the dossier level (customers, articles,...). It can also create a YearContext object (CreateYearContext). That object has some properties too (begin and end date of the financial year), and can create many objects that run on the year level (sales, purchase, invoice...)

CreateVenice
Properties
    WindowsUser
    LogonID
    ...
Methods
    Logon
    IsActionAllowed
    ...
    CreateDossierContext
    Properties
        Name
        Path
        ...
    Methods
        IsActionAllowed
        CreateCustomer
        CreateSupplier
        ...
        CreateYearContext
        Properties
            Begin
            End
            ...
        Methods
            CreateSales
            CreatePurchase
            ...

' Start Venice
ObjVenice = CreateVenice()

' Log On
ObjVenice.Logon ("13.30_", "ApplName", "Your Name", "Your Password")

' Select the dossier
ObjDossier = ObjVenice.CreateDossierContext ("C:\Venice\Data", "MyDossier")

' Start the module customers
ObjCustomer = objDossier.CreateCustm ()

' Browse in the customer file and select a customer card
ObjCustomer.Browse ()

' Update the selected customer using a dialog box
ObjCustomer.Update (umDialog)

' Select the financial year 2024
ObjYear = ObjDossier.CreateYearContext (2024)

' Start the module sales
ObjSales = objYear.CreateSales ()

' Import a text file
ObjSales.Import ()

If you understand this concept, you’re almost there. A smart editor with Intellisense or auto-complete will do the rest...

...and with the object viewer of your development tool, you get an overview of all objects and methods in the Exact Venice SDK.

But, before we get to the examples with real code, read on: there is a bit more to know...

Since we wanted the Exact Venicer SDK to be usable from VB Script (important for ASP webpages), the data types that can be used are limited to those that exist in VB Script. This is important information for developers familiar with more advanced languages which have many more data types: they should keep this limitations in mind.

VB Script has no 'unsigned' short or long integers, so pay attention when casting unsigned types to signed types!

VB Script can handle the normal data types only for [in] parameters. When using [out] parameters (references), only VARIANTs are supported. An example of a method that uses VARIANTs as reference is GetFieldVal. It returns a VARIANT, not the data type you would expect for a particular field. Also properties are often implemented as a GetFieldVal-method and that is why it are mostly VARIANTs too.

Other methods return a VARIANT_BOOL, but be aware that this is true when its value is -1! In C++, don't compare a VARIANT_BOOL with true/false but with VARIANT_TRUE/VARIANT_FALSE.

We refer to the documentation of your development tool to learn more about converting VARIANTs to traditional data types and vice versa. We also refer to the manual of VB Script to learn more about data types supported by VBS. A good VBS editor 'MSE7.EXE' which includes the VBS help file is shipped with Microsoft Office©.

Another important limitation of VB Script is its lack of support for enumerations. Although the SDK defines them, VB Script can't 'see' or use them. Therefore the include file 'ClSdkConstants.inc' is provided that lists all the enumerations as constants. If you want to make use of these constants, this file must be included in your script. It can be found in the SDK-directory in the root of your Venice installation.

The SDK has (for the moment) been successfully tested in the following programming languages:

		C++
		C#
		Visual Basic .NET
		Visual Basic for Applications
		Visual Basic Script
		Visual FoxPro
		Java
		Borland Delphi

Due to a limited number of database connections and the fact that each SDK-object uses one or more database instances, it is important to restrict the number of 'active' objects.
You can find more info on how to destroy an object in the help of the Create-topic of each interface (f.i. Venice::Create).
Keeping objects alive (for too long) can lead to the following error: 'errTooManyObjects: Too many objects created. Destroy the unneeded objects ASAP.'.

The rules for COM prescribe that the objects of every version of a COM server should have an interface, compatible with previous versions. If this cannot be achieved, a new interface for the object must be created, while maintaining the old compatible interface.

For the Exact Venice SDK, this is not feasible because the SDK is dependent on Venice. Venice evolves in a way which can not be compatible with previous versions. Consequently, if the lay-out of a data file changes, a special conversion routine must be executed to update the old data files. There is no way back! Because of this, the interfaces of future versions of the SDK are not guaranteed to be compatible with previous ones. Another consequence of this dependency is that every new version of Venice is shipped with a new version of the SDK. This means that every new version of Venice might introduce incompatibilities with previous versions of the SDK.

In order to protect your development efforts, the Exact Venice SDK uses a separate version control for every single object/interface to check possible incompatibilities between the current version of Venice and the one for which the client application was written. If a version mismatch is detected, execution of the client is suspended and an adequate error is returned. For you, the third-party developer, this version control is very easy to use. In the logon call, declare the version of Venice for which the client application was written.

Not every new version of Venice introduces incompatibilities, and if there are, that doesn’t mean it affects your application. If you haven’t used objects that are influenced by the change in Venice, your application will continue to run.

If you want an automatic system for checking incompatibilities when installing a new version of Venice, you should use the method Venice::RegisterApp in your application.

If Venice has the 'Access Management' option enabled, it makes sense to create one or more special SDK users and add them to groups that grant them just enough rights to use the objects your client application creates.

Suppose you have created a client application in VB Script and another programmer can read your script. If you haven't created a special SDK user, you have to use a regular Venice user for the script, betraying his password to the other (less talented than you of course) developer! Suppose you have created a special SDK user, and gave him administrative rights. That opens the door to everything the other developer might think of (and remember he is less talented than you)!

With compiled languages, this isn't an issue. But when using scripts, the source code is human readable, including the user identifiers and passwords. Try to hide the passwords in one of the two ways we describe here:

	Use NTFS file permissions to make sure the script file is readable only by people authorized to see the passwords.
	Use user identifiers that can log on without supplying a password. You can create such users by checking 'Only allowed if logged in to Windows as:' and providing the Windows username in the dialog of the module 'Users' of your Venice installation.

If you also enabled automatic logon, you don't even have to provide a user identifier in the script. Enabling auto logon is secure and has the advantage that different users can launch the same client application without the need for asking them their name and password or without changing the script for every user that can use the client application.