AN-016 Protégé Server ODBC Database Connectivity

AN-016
Protégé Server
ODBC Database Connectivity

PUBLICATION INFORMATION
This application note covers the use of the protégé system to perform a specific function and may be used in conjunction with
other publications. Specifications may change without notice, for updates visit the Integrated Control Technology website at
www.integratedcontroltechnology.com. No other hardware was used to prepare this application note and will not affect the result
of the application using the programming information presented.

CONTENTS
Contents........................................................................ 1
Protégé system ............................................................. 2
Introduction ....................................................................................................................... 2
Application Note Information ............................................................................................. 2
Firmware Version ............................................................................................................... 2
Connectivity .................................................................. 3
Overview ............................................................................................................................ 3
Database Block Diagram..................................................................................................... 3
Enabling MSDE/SQL Network Access .................................................................................. 3
Database Overview............................................................................................................. 4
Making The Connection....................................................................................................... 6
External User Table ..................................................... 11
Introduction ..................................................................................................................... 11
External User Table Structure........................................................................................... 11
Example Application .................................................... 13
Introduction ..................................................................................................................... 13
Connecting With ODBC ..................................................................................................... 13
Example MS Access Form.................................................................................................. 13
Information................................................................. 14
Introduction ..................................................................................................................... 14
Contact ............................................................................................................................. 14
AN-015 Protégé Server ODBC Database Connectivity
1

PROTÉGÉ SYSTEM
Introduction
The Protégé System is a powerful integrated alarm and access control management system designed
to provide integration with building automation, apartment complex control and HVAC in one flexible
package. Communicating through a proprietary high speed protocol across an encrypted RS-485
network using modular-based hardware design, system installers have the flexibility to accommodate
any installation from small or large, residential or commercial.
Application Note Information
Focusing on interoperability and flexible database integration the Protégé System allows Integrated
Control Technology to provide access to the external global user table for programming from a remote
application or database. Connectivity with remote Microsoft Access, Microsoft SQL Server, MSDE,
MySQL and Oracle databases can be achieved using a simple linked table approach.
Connections can also be used with any application that is able to utilise SQL and Database connections
from a programming environment.
The following application note describes the procedures to connect to the Protégé SQL Server
Database using an ODBC connection. The example details an interface in to the global external users
table which automatically adds and downloads users to the Protégé System Controllers. This example
uses a simple MS Access *.MDB file with a linked table. The example can be downloaded from the
software download section.
Firmware Version
This application note does not utilise firmware from the system controller or Protégé Modules. We
recommend that this application note is used in conjunction with the latest available release of the
Protégé Integrated System Management Suite.
2 AN-016 Protégé Server ODBC Database Connectivity

CONNECTIVITY
Overview
This document describes the methods used to connect an external third party application or
database to the Protégé System Management Suite to update and manage users within the
protégé installation.
Connecting to the Protégé System Management Suite using the external database and
ODBC connections requires extensive knowledge of networking, database
connectivity and security configuration parameters which are beyond the scope of
this document.
Database Block Diagram
The external users table is provided to allow a remote database (student database, SAP, ERP or
custom application) to connect and program users in the Protégé System.
Figure 1 – Basic Database Structure
Enabling MSDE/SQL Network Access
Depending on the configuration of your MSDE or SQL Server Database that is installed it may
not be possible to connect to the database remotely without enabled the network interface
connection.
The following procedure explains how to connect to the Protege Instance of the
MSDE/SQL Server that is installed as part of the server installation. Other SQL Server
installations may require different administration requirements which are beyond the
scope of this application note.
1. Using the file explorer browse to the C:\Program Files\Microsoft SQL
Server\80\Tools\Binn directory and execute the program SVRNETCN.EXE. Your directory
may be different depending on your installation.
2. Before using the application below ENSURE that you have selected the correct SQL
Server Instance or configured server. Verify that the correct computer name and
database are located at the top right hand side BEFORE proceeding.
AN-015 Protégé Server ODBC Database Connectivity
3

3. You will be shown the screen above, as in the above screen enable the connection type
that suites your environment. If you are not sure then you need to consult a network or
database administrator and close this application immediately.
4. In the examples contained in this application note the TCP/IP connection is used to the
standard SQL Server Port 1433.
5. Close the SVRNETCN.EXE application.
Database Overview
The ability to connect from remote applications that require user data to be updated in real
time allows for many possible interfaces and configurations. In most cases the data connectivity
function will allow applications such as an external photo id issuing station, employee database
or custom applications to connect to the protégé system. This functionality may be used
permanently or only at the initial stages of installation to get all users within a company in to
the database in real time.
Figure 1 - Basic Database Connection
In the above example a remote database is being used to store user data, this database is
connected to the protégé external user table allowing data for the access control system to be
updated in real time.
4 AN-016 Protégé Server ODBC Database Connectivity

In most cases this is the typical use of the database connectivity, the database can be an
employee or administration database maintained by a larger company wide application and
example of this is SAP, PeopleSoft, DataCard Image Works or similar Photo ID, Company or
employee management applications.
For an example of a connection using ODBC and Microsoft Access complete with example forms
and reports refer to the Example Application Section on Page 13.
Figure 2 - Advanced Database Connection
In the above example a remote application is being used for Photo-ID and is using data from
the remote database to attach additional user information (Photo, Issue Number). This
database then uses a trigger or internal update method to send the information to the Protégé
System when the data changes.
The example is further complicated by the external database being modified and maintained by
a distributed data entry application used for the initial entry and data processing portion of the
users being added to the system.
It is important to note that in the advanced connection the remote database is the primary
database and the Protégé System external user table is a secondary portion being updated
from data within the remote database.
To import users into the Protégé System Management Suite from an external file use
the Import User wizard available from the File Menu in the Protégé System
Management Application. Many formats are already included and user definable
formats available, for more information consult the Protégé System Management
Suite Help File.
To import users from an existing database use an appropriate update query or code
to write the users in to the External Database Table. This will mean the protégé
system controllers will be updated at the same time. It is recommended to batch load
users in smaller groups.
AN-015 Protégé Server ODBC Database Connectivity
5

Making The Connection
Making the connection to the protégé server is done by a ODBC link. The following example
shows how to link a table in Microsoft Access using ODBC and the Protégé System Management
Suite.
1. Open MS Access and create a test database, this is typically DB1.MDB, in our example
we have used the name ProtégéExternalUsers.MDB
2. As shown in the above example right click in the table window and select the Link Tables
option from the context menu.
3. When prompted for the filename scroll the file types and select the ODBC Database()
option which will be located towards the end of the available entries.
6 AN-016 Protégé Server ODBC Database Connectivity

4. From the select data source screen select the button new located to the right of the DSN
Name text box. You will now be presented with the data source type selection.
5. Select SQL Server and then select the next button to proceed with the data source
configuration. You will now be prompted to give the connection you are creating a name,
this allows the information relating to this connection to be stored so that it can be used
when you link other tables or information. In our example we have given it the name
ProtégéExternalUsers which clearly describes the use of this DSN file. Select the next
button and then select finish.
6. When you have the create new data source to SQL server dialog box presented to you,
select the Protégé SQL Server Instance from the drop down selection.
AN-015 Protégé Server ODBC Database Connectivity
7

7. When you have the create new data source to SQL server dialog box presented to you,
select the Protégé SQL Server Instance from the drop down selection. If the instance is
not presented in the drop down list type in the name of the computer as shown above
(PCNAME) followed by a backwards slash and PROTEGE in capitals. Select the next
button to move to the next step.
8. You will now be presented with the Login ID and Password, the default logon ID and
Password is ‘ProtegeEx’ for the User and ‘ProtegeEx’ for the password, please note the
password is case sensitive. Select the next button to proceed.
8 AN-016 Protégé Server ODBC Database Connectivity

9. Once the SQL Database is found and the user information verified the above screen will
be presented to you. Select the default database as Protege and then select the next
button to proceed.
10. The next screen of the process does not get altered and you should select the finish
button to complete the creation of the connection.
AN-015 Protégé Server ODBC Database Connectivity
9

11. Once the connection has been completed you can test the connection by selecting the
test data source button.
Once the connection has been made the table will be shown as a linked table in the Microsoft
database that you have created. For information on the Sample Database refer to the section
Example Application on Page 13.
10 AN-016 Protégé Server ODBC Database Connectivity

EXTERNAL USER TABLE
Introduction
The external user table is used by the remote application to write, modify and read the current
users. This table is used by the protégé application to activate internal triggers to update the
appropriate user within the protégé system.
This method protects the system from vulnerability by only allowing access to the database for
the specific purpose that is required. This is further enhanced with a password and login name
to be entered to gain access.
The login and password default to the login id "ProtegeEx" and the password "ProtegeEx".
The defaults are stored in the protégé administration settings and it is recommended that these
be changed before any connections are made to ensure a high level of security.
External User Table Structure
The following shows the external user table structure. The structure below is also available in
the attachment with this document "exusers.sql", this SQL table details the exact statements
used for creation of the table and should provide enough information for the programmer or
database administrator. The individual table elements and how they relate to the internal users
and local users within the protégé system are detailed in the following section.
TABLE Protege.dbo.ExGlobalUsers
(
[ExGlobalUsersID] [int] IDENTITY(0,1),
[SiteID] int NOT NULL DEFAULT 1,
[GlobalUserID] [int] NOT NULL DEFAULT 0,
[FirstName] nvarchar(128) DEFAULT '',
[LastName] nvarchar(128) DEFAULT '',
[DisplayName] nvarchar(128) NOT NULL DEFAULT '',
[PinNumber] nvarchar(8) NOT NULL DEFAULT '',
[FamilyNumber] int NOT NULL DEFAULT 0,
[CardNumber] int NOT NULL DEFAULT 0,
[GlobalAccessLevel] int NOT NULL DEFAULT 16777215,
[GlobalArea] int NOT NULL DEFAULT 16777215,
[ExpiryDate] datetime NOT NULL DEFAULT GETDATE(),
[ExpiryTime] datetime NOT NULL DEFAULT GETDATE(),
[ShowAGreetingMessageToUser] bit NOT NULL DEFAULT 1,
[GoDirectlyToTheMenuOnLoginNoAreaControl] bit NOT NULL DEFAULT 0,
[UserCanAcknowledgeAlarmMemory] bit NOT NULL DEFAULT 1,
[ShowAlarmMemoryOnLogin] bit NOT NULL DEFAULT 0,
[TurnOffThePrimaryAreaIfUserHasAccessOnLogin] bit NOT NULL DEFAULT 1,
[TurnOffTheUserAreaOnLoginIfUserHasAccess] bit NOT NULL DEFAULT 1,
[AcknowledgeTroubles] bit NOT NULL DEFAULT 0,
[AcknowledgeSystemTroubles] bit NOT NULL DEFAULT 0,
[UserIsADualCodeMaster] bit NOT NULL DEFAULT 0,
[UserIsADualCodeProvider] bit NOT NULL DEFAULT 0,
[UserHasSuperRightsAndCanOverrideAntipassback] bit NOT NULL DEFAULT 0,
[UserCanModifyTheirOwnCode] bit NOT NULL DEFAULT 0,
[UserCanModifyAnyCodeWithTheirAccessLevel] bit NOT NULL DEFAULT 0,
AN-015 Protégé Server ODBC Database Connectivity
11

)
[UserLoiterExpiryCountEnabled] bit NOT NULL DEFAULT 0,
[UserCanLogInRemotely] bit NOT NULL DEFAULT 0,
[UserIsADuressUser] bit NOT NULL DEFAULT 0,
[CardMode] int NOT NULL DEFAULT 0,
[DownloadType] int NOT NULL DEFAULT 0,
[CreatedTime] datetime NOT NULL DEFAULT GETDATE(),
[LastModifiedTime] datetime NOT NULL DEFAULT GETDATE()
This structure is automatically provided to the connecting database or application when the
ODBC link is made. The above and following information is provided for a reference only to the
settings and default values.
12 AN-016 Protégé Server ODBC Database Connectivity

EXAMPLE APPLICATION
Introduction
The example application shows the ease at which the external user table can be connected and
presented using the Microsoft Access Database. This application was chosen due to the
simplicity and wide availability of the application. The example can easily be adapted to ANY
database or application.
The default login "ProtegeEx" and password "ProtegeEx" have been used for this
example and in the files that are supplied. This must be changed when used with a
live system and data.
Connecting With ODBC
Before the example database will operate you must create your own linked table to the Protégé
SQL Server that is installed on your machine. To complete the connection follow the details in
the Section Making the Connection on Page 6.
Example MS Access Form
The following figure shows the sample Microsoft Access Form that is provided in the sample
database. The customisation of the form is very flexible and as can be seen easily extended to
other applications as required.
Figure 3 – Example MS Access Form
AN-015 Protégé Server ODBC Database Connectivity
13

INFORMATION
Introduction
Application notes are provided as is without any implied warranty or intended use and are
written by Integrated Control Technology as an aid in programming and connecting devices to
the Protégé System.
Contact
Integrated Control Technology welcomes all feedback. Please visit our website or use the
information below.
Integrated Control Technology
P.O. Box 302-340 Unit C,
North Harbour Post Centre
6 Ascension Place
Auckland
Mairangi Bay
New Zealand
Auckland
New Zealand
Phone: +64-9-476-7124
Fax: +64-9-476-7128
www.integratedcontroltchnology.com
14 AN-016 Protégé Server ODBC Database Connectivity

Unit C, 6 Ascension Place, Mairangi Bay, P.O. Box 302-340
North Harbour, Auckland, New Zealand.
Phone: +64 (9) 476 7124 • Fax: +64 (9) 476 7128
www.integratedcontroltechnology.com