Server SDK

Version 8.3
Reference Guide

Captaris, Inc., 301 116th Ave SE, Suite 400 Bellevue, Washington 98004-6446
Phone +1 425.455.6000, www.captaris.com
Alchemy is a registered trademark of Captaris, Inc. All rights reserved. All other trademarks or registered trademarks are the property of their
respective companies. Other products and company names mentioned herein may be the trademarks of their respective owners.

© 1992-2008, Captaris, Inc. All rights reserved

CONTENTS

ALCHEMY SERVER SDK TOOLKIT ...............................................................................1-1

1

1.1 INTRODUCTION ............................................................................................................ 1-1

1.2 ALCHEMY SERVER API .DLL FILE .................................................................................1-1
1.3 ALCHEMY SERVER SDK EXAMPLES ............................................................................. 1-2
1.4 APPLICATION OBJECT .................................................................................................. 1-8
1.4.1 PROPERTIES AND METHODS................................................................................ 1-8
1.5 SERVERNAME PROPERTY ............................................................................................1-9
1.6 PORTNUMBER PROPERTY ..........................................................................................1-10
1.7 CONNECTIONCOUNT PROPERTY.................................................................................1-10
1.8 CONNECTIONLIST PROPERTY .....................................................................................1-10
1.9 CONNECTIONNAME PROPERTY ..................................................................................1-11
1.10 CANCONNECT PROPERTY ........................................................................................1-11
1.11 DATABASECOUNT PROPERTY...................................................................................1-12
1.12 DATABASELIST PROPERTY .......................................................................................1-12
1.13 DATABASENAME PROPERTY ....................................................................................1-13
1.14 GETSERVERTIMES METHOD ....................................................................................1-13
1.15 GETSERVERSTATS METHOD ....................................................................................1-14
1.16 DISCONNECT METHOD .............................................................................................1-15
1.17 DISCONNECTALL METHOD .......................................................................................1-15
1.18 DISABLENEWCONNECTIONS METHOD .......................................................................1-16
1.19 ENABLENEWCONNECTIONS METHOD ........................................................................1-16
1.20 GETCONNECTIONTIMES METHOD .............................................................................1-17
1.21 GETCONNECTIONSTATS METHOD ............................................................................1-17
1.22 GETDATABASESTATUS METHOD ..............................................................................1-18
1.23 ADDDATABASE METHOD ..........................................................................................1-19
1.24 REMOVEDATABASE METHOD ....................................................................................1-20
1.25 DISABLEDATABASE METHOD ....................................................................................1-20
1.26 ENABLEDATABASE METHOD .....................................................................................1-21
1.27 UNLOCKDATABASE METHOD ....................................................................................1-21
1.28 DISABLEALLDATABASES METHOD ............................................................................1-22
1.29 ENABLEALLDATABASES METHOD .............................................................................1-22
1.30 GETDATABASETIMES METHOD .................................................................................1-23
1.31 GETDATABASESTATS METHOD ................................................................................1-23
1.32 CONNECT METHOD ..................................................................................................1-24

1
Contents

2
ALCHEMY SERVER SDK TOOLKIT

1.1 INTRODUCTION

The Alchemy Server SDK Toolkit is a set of COM (Component Object Model) specification
compliant tools that provide system administrator with a simple and efficient interface for monitoring
and managing Alchemy databases and users. Using the Alchemy Server SDK Toolkit, developers
can:
• Control/simplify/customize the Alchemy Server interface.
• Extend or limit Alchemy's current functionality or permissions.
• Integrate Alchemy into existing workflow or enterprise systems.
• Automate Alchemy Server functions.

OVERVIEW
The Alchemy Server SDK allows you to write your own interface to get statistical data from the
server, control the databases and connection status as seen in the Alchemy Server MMC Snap In.
Additionally, the SDK can be installed and run remotely.
Whether you design a simple UI or chose to use a command line with the Server SDK, Alchemy
gives you the versatility of automate the Server for unattended operation. Users creating new
databases, adding data and building database through an automated process can use the SDK to add
the database to the server on the fly. Alchemy Server opens databases exclusively, and users who
back up their databases can disconnect all the users from the database and suspend the database
during the backup process. Then, once the backup is complete, users can reinstate/resume the
database on the server.

1.2 ALCHEMY SERVER API .DLL FILE

The Alchemy Server API interface is only dependent on one .dll file, the AuServerAPI.dll. This file
can be placed on a remote machine and used to access any Alchemy Server on the network.

INSTALLATION INSTRUCTIONS:
To install and register the AuServerAPI on a remote PC:
1. Locate the AuServerAPI.dll file on the server.

1-1
Alchemy Server SDK examples

2. Copy the file to the remote machine.

3. On the remote machine, register the dll.
Regsvr32.exe c:\path to dll\AuServerAPI.dll
4. Reference the Alchemy Server Type Library with the project.
To unregister the AuServerAPI.dll file:
Regsvr32.exe c:\path to dll\AuServerAPI.dll /u

1.3 ALCHEMY SERVER SDK EXAMPLES

This section provides three code examples. Each example focuses on a different portion of the COM
interface; the server, the database, and the connection methods and properties.
The following descriptions of the sample pieces of code are intended to give the developer a brief
introduction to some of the methods and properties described in the documentation. Only portions of
the code are described. Between the three samples, all the properties and methods of the Alchemy
Server Application object are used.

SERVER STATISTICS EXAMPLE (PROSERVERBASICS.VBP)

The first sample code uses properties and methods that are related to the server statistics which show
via the Snap-In. This example gets the Server Stats and times. Before running the code, please make
sure the Server is started.

Because this is a very simple example, error handling was built into the code to support a user
stopping the Alchemy Server service via the Snap-In or the Services module.
Dim au As AuServer.Application
Dim StartTime As Long
Dim TotalConn As Long
Dim MaxConn As Long
Dim BytesRead As Double
Dim BytesWritten As Double
Dim ReqCount As Double
Dim TransCount As Double

Private Sub CmdRefresh_Click()

GetServerStats
End Sub

Private Sub Form_Load()

On Error GoTo LoadError
'Creates an Application object.
Set au = New AuServer.Application
'Makes a connection to the Alchemy Server on the
'current machine.
au.Connect
'Makes a connection to a remote Alchemy Server.
'au.Connect ServerName, PortNumber
GetServerStats

1-2
 Alchemy Server SDK examples

1 ALCHEMY SERVER
SDK TOOLKIT
Exit Sub

'Error handling to support failed connections to the server.

LoadError:
'Error thrown when the service is stopped.
If Err.Description = "Permission denied" Then
MsgBox "LoadError: The Alchemy Server Service is not
started.&_
"Please start the service."
Else
'Reports any other errors.
MsgBox "LoadError: Error Number " & Err.Number & ": " & _
Err.Description
End If

'Quits program
Unload Form1

End Sub

Private Sub GetServerStats()

On Error GoTo ServerStatsError

'Gets the server name and Port Number.

TxtServerName = au.ServerName
TxtPortNumber = au.PortNumber

'Gets the Start Time.

au.GetServerTimes StartTime
TxtStartTime = StartTime

'Gets the current Server Stats. The next line is on one line
au.GetServerStats TotalConn, MaxConn, BytesRead, BytesWritten,
ReqCount, TransCount
TxtTotalConn = TotalConn
TxtMaxConn = MaxConn
TxtBytesRead = BytesRead
TxtBytesWritten = BytesWritten
TxtReqCount = ReqCount
TxtTransCount = TransCount
Exit Sub
'Handles any errors that occur when service is stopped.
ServerStatsError:
MsgBox "ServerStatsError: Error number " & Err.Number & _
" occured. "& Err.Description & ". Please make sure " & _
"the Alchemy Server Service is still running."

End Sub

Private Sub Form_Unload(Cancel As Integer)

Set au = Nothing
End Sub

1-3
Alchemy Server SDK examples

CONNECTION EXAMPLE (PROCONNBASICS.VBP)

This example uses properties and methods used in relation to the connections made to the server. It
shows the same data in a grid format that is seen in the Connection portion of the SnapIn. Below only
a portion of the code is shown. The following methods are used in the example program but are left
out of the documented code; CanConnect, EnableNewConnections, DisableNewConnections,
Disconnect, and DisconnectAll.
The portion of the code shown displays an example of how to access the ConnectionList Safe Array
and return or retrieve the values returned by the GetConnectionStats, ConnectionName, and
GetConnectionTimes methods.

To keep this sample code simple, error handling was left out. Users should add error code to handle a
user via the Snap-In or Services module stopping the Alchemy Server service. When the service is
stopped, the socket connection made by the API is lost.
Dim au As AuServer.Application

Dim vConnList As Variant

Dim i As Long
Dim sConnDetails As String

'Parameters of the GetConnectionTimes method

Dim LoginTime As Long
Dim IdleTime As Long
Dim CPUTime As Long

'Parameters for the GetConnectionStats method.

Dim NumofDBs As Long
Dim BytesRead As Double
Dim BytesWritten As Double
Dim RequestCount As Double
Dim TransCount As Double

Private Sub FillGrid()

With GridConnectionData

'For simplicity, removed the code which sets the columns for
'the grid used in the example.

End With

'If any users are connected to the server then get the connection
' data.
If au.ConnectionCount > 0 Then
'Gets the list(safe array) of connected users.
vConnList = au.ConnectionList

'The for loop goes through each the array of connections

'and gets the associated data.
For i = LBound(au.ConnectionList) To
UBound(au.ConnectionList)

'The sConnDetails is string generated to be used to

1-4
 Alchemy Server SDK examples

1 ALCHEMY SERVER
SDK TOOLKIT
'populate the grid.
'The next two lines are one.
sConnDetails = vConnList(i) & vbTab &
au.ConnectionName(vConnList(i)) & vbTab

'Uses the GetConnectionTimes method to get the

'Login Time, Idle Time, and the CPU Time.
'The next two lines are one.
au.GetConnectionTimes vConnList(i), LoginTime,
IdleTime, CPUTime

'The next two lines are one.

sConnDetails = sConnDetails & LoginTime & vbTab &
IdleTime & vbTab & CPUTime & vbTab

'Uses the GetConnectionStats to get the number of

'databases, Bytes Read, Bytes Written, Request Count
'and Transaction Count.
'The next two lines are one.
au.GetConnectionStats lConnList(i), NumofDBs,
BytesRead, BytesWritten, RequestCount,
TransCount

'The next three lines are one.

sConnDetails = sConnDetails & NumofDBs & vbTab &
BytesRead & vbTab & BytesWritten & vbTab &
RequestCount
& vbTab & TransCount

'Places the data into the grid.

GridConnectionData.AddItem sConnDetails
Next
End If

End Sub

DATABASE EXAMPLE (PRODBBASICS.VBP)

This example uses properties and methods used in relation to the databases added to the server. It
shows the same data in a grid format that is seen in the Database portion of the SnapIn. Below only a
portion of the code is shown. The following methods are used in the example program but are left out
of the documented code are CanConnect, EnableNewConnections, DisableNewConnections,
Disconnect, and DisconnectAll.
The portion of the code shown displays an example of how to access the ConnectionList Safe Array
and return or retrieve the values returned by the GetConnectionStats, ConnectionName, and
GetConnectionTimes methods.

To keep this sample code simple, error handling was left out. Users should add error code to handle a
user via the Snap-In or Services module stopping the Alchemy Server service. When the service is
stopped, the socket connection made by the API is lost.
'Parameter to create the object to access the server.

1-5
Alchemy Server SDK examples

Dim au As AuServer.Application
'Paramters associated with the DatabaseList property
Dim lDBList As Variant
Dim i As Long
Dim sDbList As String
Dim lDBID As Long
'Parameters for the GetDatabaseStatus method
Dim DBEnabled As Boolean
Dim DBLockConnID As Long
Dim DBLockTime As Long
'Parameters for the GetDatabaseTimes method.
Dim DBOpenTime As Long
'Parameters for the GetDatabaseStats method.
Dim ConnstoDB As Long
Dim DBBytesRead As Double
Dim DBBytesWritten As Double
Dim DBReqCount As Double
Dim DBTRansCount As Double

Private Sub Form_Load()

'Creates the Application object which provides the
'ability to connect to an Alchemy Server.
Set au = New AuServer.Application
'Connects to the server on the local machine.
au.Connect
'Connects to a server on the network.
'au.Connect ServerName

'Gets data about each database available on the server.

FillGrid
lDBID = 0

End Sub

Private Sub FillGrid()

With GridDbList

'For simplicity, removed the code which sets the columns for
'the grid used in the example.

End With

'Gets a Safe Array containing all the databases

'connected to the server.
lDBList = au.DatabaseList

'Loops through the array to attain the data associated with

'each database on the server.
For i = LBound(au.DatabaseList) To UBound(au.DatabaseList)

'A string containing the database data used to add

'The next two lines are one.

1-6
 Alchemy Server SDK examples

1 ALCHEMY SERVER
SDK TOOLKIT
sDbList = lDBList(i) & vbTab & au.DatabaseName(lDBList(i)) &
vbTab

'Returns whether or not the database is enabled, locked and

'how long it has been locked.
'The next two lines are one.
au.GetDatabaseStatus lDBList(i), DBEnabled, DBLockConnID,
DBLockTime

'The next two lines are one.

sDbList = sDbList & DBEnabled & vbTab & DBLockConnID & vbTab
&
DBLockTime & vbTab

'Returns how long the database has been open.

au.GetDatabaseTimes lDBList(i), DBOpenTime
sDbList = sDbList & DBOpenTime & vbTab

'Returns the connections to the database, bytes read, bytes

'written request count, and transactions.
'The next two lines are one.
au.GetDatabaseStats lDBList(i), ConnstoDB, DBBytesRead,
DBBytesWritten, DBReqCount, DBTRansCount

'The next three lines are one.

sDbList = sDbList & ConnstoDB & vbTab & DBBytesRead & vbTab &
dbbyteswriteen & vbTab & DBReqCount & vbTab &
DBTRansCount

'Adds the data to the grid.

GridDbList.AddItem sDbList
Next

End Sub

CONNECT EXAMPLE
Dim application As AuServer.Application

'Creates an Application object.

Set application = New AuServer.Application

'Makes a connection to the Alchemy Server on the

'current machine.
application.Connect

'or

'Makes a connection to a remote Alchemy Server.

application.Connect "JohnDoe", 5001

'or

1-7
Application object

'Makes a connection to a remote Alchemy Server using an IP address.

application.Connect "192.191.6.180", 5001

1.4 APPLICATION OBJECT

The Application object provides a way to access runtime data about the Alchemy server running as an
NT 4.0 SP4x or 2000 service.

REMARKS:
When the Alchemy Server is not running then the Application object will be unable to connect to the
server and return the expected data.

USAGE:
To declare and create an Application object in Visual Basic:
1. ' Declare and create an Application object
2. Dim Application as AuServer.Application
3. Set Application = New AuServer.Application

PROPERTIES:
ServerNamePortNumberConnectionCountConnectionList
ConnectionNameCanConnectDatabaseCountDatabaseList
DatabaseName

METHODS:
GetServerTimesGetServerStatsDisconnect
DisconnectAllDisableNewConnectionsEnableNewConnections
GetConnectionTimesGetConnectionStatsGetDatabaseStatus
AddDatabaseRemoveDatabaseDisableDatabase
EnableDatabaseUnlockDatabaseDisableAllDatabases
EnableAllDatabasesGetDatabaseTimesGetDatabaseStats
Connect

1.4.1 PROPERTIES AND METHODS

The function or attributes of each Alchemy object are accessed through interfaces known as
properties, methods or events. Each object can have more than one interface.

1-8
 ServerName property

1 ALCHEMY SERVER
SDK TOOLKIT
PROPERTY
Properties describe an object's characteristic attribute(s), such a size, position, or visibility. For
example, the Visible property determines whether the object can be seen when it is run. A property
can also control the behavior of other methods.
The value of the property can be retrieved (read-only) or set to a specific value (write-only) or a
combination of both (read-write). The type or range of the value is determined by the property. Most
properties are read-only.
If the property is read-only, you can retrieve the property's value but you cannot set or alter it to a
specific value. For example, the Application.CanShare property determines whether multiple users
can share the current application. The value of this property can be retrieved from the licensing
scheme but it cannot be altered. If the property is write-only, its value must first be set by the user. It
cannot be retrieved until after its value has been set. For example, the Application.Database.Password
property sets/changes the database password. This value must be set by the user in order to password
protect a database. It cannot be read from the API. If the property is read-write, its value can be
retrieved or modified. For instance, the Database.Title value can be returned or it can be changed by
the user.

METHOD
Methods represent an object's behavior, the things you can tell an object to do, such as save, close,
delete, exit, etc.
Unlike properties, the code for an object's method does not require an equal (=) sign.
A method may or may not have required and/or default arguments. If a method contains no
arguments, or if all the arguments are assigned default values, you just need to type the name of the
method to execute it.
A method may or may not have a return value. The return value is a request made by the method for a
specific data set. A request to display a specific date is an example of a return value. The return value
from a method can be assigned to a local variable or object. In Visual Basic, parentheses must be used
to enclose the arguments of methods that contain return values.

1.5 SERVERNAME PROPERTY

DESCRIPTION:
Returns a string representing the name of the computer where the server is running.

SYNTAX:
C++
Application::get_ServerName(BSTR* pName)
Visual Basic
Application.ServerName

1-9
PortNumber property

DATA TYPE:
String

1.6 PORTNUMBER PROPERTY

DESCRIPTION:
Returns a long representing the port number that the server is listening to.

SYNTAX:
C++
Application::get_PortNumber(long* pPort)
Visual Basic
Application.PortNumber

DATA TYPE:
Long

1.7 CONNECTIONCOUNT PROPERTY

DESCRIPTION:
Returns the number of current connections to the server.

SYNTAX:
C++
Application::get_ConnectionCount(long* pCount)
Visual Basic
Application.ConnectionCount

RETURN TYPE:
Long

1.8 CONNECTIONLIST PROPERTY

DESCRIPTION:
Returns a safe array of connection IDs.

1-10
 ConnectionName property

1 ALCHEMY SERVER
SDK TOOLKIT
SYNTAX:
C++
Application::get_ConnectionList(SAFEARRAY** ppList)
Visual Basic
Application.GetConnectionList

RETURN TYPE:
Safe Array

EXAMPLE:
“Connection example (ProConnBasics.vbp)” on page 1-4

1.9 CONNECTIONNAME PROPERTY

DESCRIPTION:
Returns a string representing the IP address for the given connection.

SYNTAX:
C++
Application::get_ConnectionName(long nConnID,BSTR* pName)
Visual Basic
Application.ConnectionName (nConnID As Long)

PARAMETERS
Parameter Description
nConnID A long representing the ID of an active connection to the server.

DATA TYPE:
String

1.10 CANCONNECT PROPERTY

DESCRIPTION:
Returns a Boolean value that represents whether or not the server can accept new connections.

1-11
DatabaseCount property

SYNTAX:
C++
Application::CanConnect()
Visual Basic
Application.CanConnect

REMARKS:
When this property is set to True then new connections can be made to the server.

RETURN TYPE:
Boolean

1.11 DATABASECOUNT PROPERTY

DESCRIPTION:
Returns a long representing the number of databases currently defined in the server.

SYNTAX:
C++
Application::get_DatabaseCount(long* pCount)
Visual Basic
Application.DatabaseCount

DATA TYPE:
Long

1.12 DATABASELIST PROPERTY

DESCRIPTION:
Returns an array of Database IDs.

SYNTAX:
C++
Application::get_DatabaseList(SAFEARRAY** ppList)
Visual Basic
Application.DatabaseList

1-12
 DatabaseName property

1 ALCHEMY SERVER
SDK TOOLKIT
RETURN TYPE:
Safe Array

EXAMPLE:
“Database example (ProDBBasics.vbp)” on page 1-5

1.13 DATABASENAME PROPERTY

DESCRIPTION:
Returns a string representing the path to the given database.

SYNTAX:
C++
Application::get_DatabaseName(long nDatabaseID,BSTR* pName)
Visual Basic
Application.DatabaseName (nDatabaseID as Long)

PARAMETERS
Parameter Description
nDatabaseID A long representing the ID of a database on the server.

DATA TYPE:
String

1.14 GETSERVERTIMES METHOD

DESCRIPTION:
Retrieves the timing data for the server.

SYNTAX:
C++
Application::GetServerTimes(long* pStartTime)
Visual Basic
Application.GetServerTimes (pStartTime as Long)

1-13
GetServerStats method

PARAMETERS
Parameter Description
pStartTime A long representing the number of seconds the server has been running.

RETURN TYPE:
Long

EXAMPLE:
“Server statistics example (ProServerBasics.vbp)” on page 1-2

1.15 GETSERVERSTATS METHOD

DESCRIPTION:
Retrieves the statistics about the Server.

SYNTAX:
C++
Application::GetServerStats(long* pTotalConnections,long*
pMaxConnections,double* pBytesRead,double* pBytesWritten,double*
pRequestCount,double* pTransactionCount)
Visual Basic
Application.GetDatabaseStats (pTotalConnections as Long,
pMaxConnections as Long, pBytesRead as Double, pBytesWritten as
Double, pRequestTime as Double, pTransactionCount as Double)

PARAMETERS
Parameter Description
pTotalConnections A long returned representing the total number of current connections to the
server.
pMaxConnections Along returned representing the maximum number of connections to the
server.
pBytesRead A double returned representing the number of bytes read by the connection.
pBytesWritten A double returned representing the number of bytes written by the
connection.
pRequestCount A double returned representing the number of requests received.
pTransactionCount A double returned representing the number of write transactions performed.

1-14
 Disconnect method

1 ALCHEMY SERVER
SDK TOOLKIT
RETURN TYPE:
None

EXAMPLE:
“Server statistics example (ProServerBasics.vbp)” on page 1-2

1.16 DISCONNECT METHOD

DESCRIPTION:
Forcibly terminates a specific connection from the server.

SYNTAX:
C++
Application::Disconnect(long nConnID)
Visual Basic
Application.Disconnect(nConnID as Long)

PARAMETERS
Parameter Description
nConnID A long representing a connection that needs to be terminated.

RETURN TYPE:
None

1.17 DISCONNECTALL METHOD

DESCRIPTION:
Forcibly terminates all the connections to the server.

SYNTAX:
C++
Application::DisconnectAll()
Visual Basic
Application.DisconnectAll

1-15
DisableNewConnections method

RETURN TYPE:
None

1.18 DISABLENEWCONNECTIONS METHOD

DESCRIPTION:
Prevents the server from accepting new connections.

SYNTAX:
C++
Application::DisableNewConnections();
Visual Basic
Application.DisableNewConnections

RETURN TYPE:
None

1.19 ENABLENEWCONNECTIONS METHOD

DESCRIPTION:
Allows the server to accept new connections.

SYNTAX:
C++
Application::EnableNewConnections();

VISUAL BASIC
Application.EnableNewConnections

RETURN TYPE:
None

1-16
 GetConnectionTimes method

1 ALCHEMY SERVER
1.20 GETCONNECTIONTIMES METHOD

SDK TOOLKIT
DESCRIPTION:
Retrieves the timing data for a given connection.

SYNTAX:
C++
Application::GetConnectionTimes(long nConnID,long* pLoginTime,long*
pIdleTime,long* pCpuTime)
Visual Basic
Application.GetConnectionTimes (nConnId as Long, pLoginTime as Long,
pIdleTime as Long, pCpuTime as Long)

PARAMETERS
Parameter Description
nConnID A long representing the connection.
pLoginTime Returns a long representing the time in seconds it took to establish a
connection to the database.
pIdleTime Returns a long representing the time in seconds that the connection has been
idle.
pCpuTime Returns a long representing the time in seconds that CPU was active during
the connection.

RETURN TYPE:
None

EXAMPLE:
“Connection example (ProConnBasics.vbp)” on page 1-4

1.21 GETCONNECTIONSTATS METHOD

DESCRIPTION:
Retrieves the statistics about a given IP connection.

SYNTAX:
C++

1-17
GetDatabaseStatus method

Application::GetConnectionStats(long nConnID,long* pDatabases,double*

pBytesRead,double* pBytesWritten,double* pRequestCount,double*
pTransactionCount)
Visual Basic
Application.GetConnectionStats (nConnID as Long, pBytesRead as
Double, pBytesWritten as Double, pRequestTime as Double,
pTransactionCount as Double)

PARAMETERS
Parameter Description
nConnID A long representing the IP address that the return stats represents.
pDatabases A long representing the number of databases the connection is attached to.
pBytesRead A double returned representing the number of bytes read by the connection.
pBytesWritten A double returned representing the number of bytes written by the
connection.
pRequestCount A double returned representing the number of requests received.
pTransactionCount A double returned representing the number of write transactions performed.

RETURN TYPE:
None

EXAMPLE:
“Connection example (ProConnBasics.vbp)” on page 1-4

1.22 GETDATABASESTATUS METHOD

DESCRIPTION:
Returns the status of a specified database.

SYNTAX:
C++
Application::GetDatabaseStatus(long nDatabaseID,VARIANT_BOOL*
pEnabled,long* pLockConnID,long* pLockTime)
Visual Basic
Application.GetDatabaseStatus (nDatabaseID As Long, pEnabled As
Boolean, pLockConnID As Long, pLockTime As Long)

1-18
 AddDatabase method

1 ALCHEMY SERVER
SDK TOOLKIT
PARAMETERS
Parameter Description
nDatabaseID A long representing a database available on the server.
pEnabled Returns a Boolean representing whether or not the database is enabled. A
True value is returned when the database is open.
pLockConnID Returns a long representing the connection that has locked the database, if
any.
pLockTime Returns a long representing the lock time in seconds.

RETURN TYPE:
None

EXAMPLE:
“Server statistics example (ProServerBasics.vbp)” on page 1-2

1.23 ADDDATABASE METHOD

DESCRIPTION:
Dynamically opens a new database on the server.

SYNTAX:
C++
Application::AddDatabase(BSTR bstrPath)
Visual Basic
Application.AddDatabase(szPath as String)

PARAMETERS
Parameter Description
szPath A string value which represents the full path to the database.

RETURN TYPE:
None

EXAMPLE:
“Database example (ProDBBasics.vbp)” on page 1-5

1-19
RemoveDatabase method

1.24 REMOVEDATABASE METHOD

DESCRIPTION:
Forcibly removes the new database from the server.

SYNTAX:
C++
Application::RemoveDatabase(long nDatabaseID)
Visual Basic
Application.RemoveDatabase(nDatabaseID as Long)

PARAMETERS
Parameters Description
nDatabaseID A long value which represents the Database ID.

RETURN TYPE:
None

EXAMPLE:
“Database example (ProDBBasics.vbp)” on page 1-5

1.25 DISABLEDATABASE METHOD

DESCRIPTION:
Temporarily closes the all the files of a particular database on the server.

SYNTAX:
C++
Application::DisableDatabase(long nDatabaseID)
Visual Basic
Application.DisableDatabase(nDatabaseID as Long)

PARAMETERS
Parameter Description
nDatabaseID A long value which represents the database ID.

1-20
 EnableDatabase method

1 ALCHEMY SERVER
SDK TOOLKIT
RETURN TYPE:
None

REMARKS:
The connections to the database will be suspended once the current read/write transaction is complete.
Connections made to the database are suspended not terminated. The server allows new connections
to the database but the users connection is in a suspended state.

1.26 ENABLEDATABASE METHOD

DESCRIPTION:
Reopens a disabled database on the server.

SYNTAX:
C++
Application::EnableDatabase(long nDatabaseID)
Visual Basic
Application.EnableDatabase(nDatabaseID as Long)

PARAMETERS
Parameter Description
nDatabaseID A long value which represents the database ID.

RETURN TYPE:
None

REMARKS:
Suspended connections are resumed.

1.27 UNLOCKDATABASE METHOD

DESCRIPTION:
Forcibly removes a write lock from the database files on the server.

SYNTAX:
C++

1-21
DisableAllDatabases method

Application::UnlockDatabase(long nDatabaseID)
Visual Basic
Application.UnlockDatabase(nDatabaseID as Long)

PARAMETERS
Parameter Description
nDatabaseID A long value which represents the database ID.

RETURN TYPE:
None

1.28 DISABLEALLDATABASES METHOD

DESCRIPTION:
Temporarily closes the all the database files on the server.

SYNTAX:
C++
Application::DisableAllDatabases ( )
Visual Basic
Application.DisableAllDatabases

RETURN TYPE:
None

REMARKS:
The connections to the database will be suspended once the current read/write transaction is complete.
Connections made to the database are suspended not terminated. The server allows new connections
to the database but the users connection is in a suspended state.

1.29 ENABLEALLDATABASES METHOD

DESCRIPTION:
Reopens all the database files on the server.

1-22
 GetDatabaseTimes method

1 ALCHEMY SERVER
SDK TOOLKIT
SYNTAX:
C++
Application.::EnableAllDatabases ( )
Visual Basic
Application.EnableAllDatabases

RETURN TYPE:
None

1.30 GETDATABASETIMES METHOD

DESCRIPTION:
Retrieves the number of seconds a database has been open.

SYNTAX:
C++
Application::GetDatabaseTimes(long nDatabaseID,long* pOpenTime)
Visual Basic
Application.GetDatabaseTimes (nDatabaseID as Long, pOpenTime as Long)

PARAMETERS
Parameter Description
nDatabaseID A long representing the ID of a database on the server.
pOpenTime The long returned representing the number of seconds the database has been
opened.

RETURN TYPE:
None

1.31 GETDATABASESTATS METHOD

DESCRIPTION:
Retrieves the statistics about a given Database.

SYNTAX:
C++

1-23
Connect method

Application::GetDatabaseStats(long nDatabaseID, long* pConnections,

double* pBytesRead,double* pBytesWritten,double*
pRequestCount,double* pTransactionCount)
Visual Basic
Application.GetDatabaseStats (nDatabaseID as Long, pBytesRead as
Long, pBytesWritten as Long, pRequestTime as Long, pTransactionCount
as Long)

PARAMETERS
Parameter Description
nDatabaseID A long representing the ID of a database that the return stats represents.
pConnections A long returned representing the number of the current connections to the
database.
pBytesRead A double returned representing the number of bytes read by all the
connections.
pBytesWritten A double returned representing the number of bytes written by all the
connections.
pRequestCount A double returned representing the number of requests received.
pTransactionCount A double returned representing the number of write transactions performed.

RETURN TYPE:
None

1.32 CONNECT METHOD

DESCRIPTION:
Connects to a specific Alchemy Server.

SYNTAX:
C++
Application::Connect(BSTR ServerName,long nPort)
Visual Basic
Application.Connect (ServerName as String, PortNumber as Long)

PARAMETERS
Parameter Description
ServerName A string representing the server name where the connection will be
established.
PortNumber A long representing the Service Port Number where service is listening.

1-24
 Connect method

1 ALCHEMY SERVER
SDK TOOLKIT
RETURN TYPE:
None

REMARKS:
When connecting to the server local server, the parameters do not need to be set. When connecting
remotely the Server Name and Service Port Number specified are required. See the example below.
When the Alchemy Server service is stopped then an error message of 'permission denied' is thrown.

EXAMPLE:
“Connect example” on page 1-7

1-25
Connect method

1-26