|
|
|
|
|
Think of a client application for the Exact C-Logic 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.10_", "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 C-Logic SDK.
But, before we get to the examples with real code, read on: there is a bit more
to know...
|
|
|
|
|
|
|
Since Exact C-Logic wanted the 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 Exact C-Logic
provides an include file, 'ClSdkConstants.inc', 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 C-Logic 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, Exact C-Logic cannot guarantee the
interfaces of future versions of the SDK 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, Exact C-Logic 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.
|
|
|
|
|