The configuration file SqlBE.ini for
the Agentry
Server contains
several sections. This file is referred to generically as the “query
initialization file.” Each section corresponds to an event related
to the Server’s communications and synchronization with a SQL database.
The settings for each of the sections consists of one or more SQL
scripts to be processed by the Server when the event that corresponds
to the section occurs.
The SqlBe.ini is the default query initialization
file provided by the Server installer. It can be modified for an
application, or it can be used as a template to create other query
initialization files for applications with multiple SQL Database
system connection types. Within the [SQL-n] section
of the Agentry.ini configuration file, the option queryInitFile contains
the name of the query initialization file to be used by the system
connection.
File Format
The sections within the query
initialization file list one or more SQL scripts to be run. These
scripts are listed as key and value pairs, just as with any other
configuration options in Agentry.
However, the key portion of these options are unnamed keys. This
means the Server is not looking for a specific configuration option
name. Rather, all of the scripts within a section are processed
in the order listed when that section’s event occurs. The key may
be any value desired. The common practice is to use key values of q01, q02, q03,
etc. The numeric portion of these keys has no impact on the behavior
of the Server, but is useful for those reviewing or modifying the
query initialization file.
As an example, the
[LoggedIn] section
may appear as follows for an application:
[LoggedIn]
q01=InsertUserAudit.sql
q02=UpdateUserLastLoginTimestamp.sql
Application-Specific Changes
The query
initialization files are normally configured initially by application
developers or as the result of development efforts and standard
application needs. Therefore, changes to these settings should only
be made with a full understanding of how such changes will impact
the overall behavior of the application. It is often the case that
changes are made not to this file, but rather to the scripts it
references.
Specific changes to either the settings in this
file or to those scripts it references are made as the result of
specific implementation requirements. Items such as user validation
or auditing requirements can dictate when and what modifications
may be necessary.
SQL Script Locations
The scripts referenced
in the SqlBe.ini file must be located in one of
two directories, both of which are sub-directories of the Agentry
Server within
the SMP installation location (e.g. C:\SAP\MobilePlatform\Servers\AgentryServer\).
The
following two sub-directories are where the SQL scripts are located:
sql
sql\custom
The purpose behind having two separate folders
for script files is to provide for standard and customized processing.
For an application implementation, the sql folder
will contain the standard scripts provided with the application
installer. Changes to these scripts should be made to copies. These
new versions should then be saved in the sql\custom folder.
The
behavior of the Agentry
Server when
processing scripts listed in the SqlBe.ini file
is to first look for the script file in the sql\custom folder.
If found, the script will be processed and executed. If it is not found
in the custom folder, the Agentry
Server will
then look for the same file in the sql folder.
This
behavior allows for a script to be overridden while at the same
time leaving the original version easily accessible. If it is desired
to return to the default processing, the script file in the custom
folder can simply be moved or renamed. The next time the Agentry
Server executes
the script, the default version will then be run.
Sections Listing
The following is a list
of the sections within this file and the events to which they relate:
- [Misc] - This section should not be modified.
This section contains two queries to be run by the Agentry
Server,
which are used for internal purposes.
- [DbConnect] - This section can contain a listing
of SQL scripts to be run when the Agentry
Server connects
to the database. This connection is made when the Agentry
Server is
started, and also when the Agentry
Server reconnects
to the database based on the disconnectFromDB setting
in the [SQL-n] section for the system connection.
- [DbDisconnect] - This section can contain a
list of SQL scripts to be run when the Agentry
Server disconnects
from the database. This occurs as a part of the Server’s shutdown
processing, and also when the Agentry
Server disconnects
from the database based on the disconnectFromDB setting
in the [SQL-n] section for the system connection.
- [DbConnectionInit] - SQL scripts listed in
this section are run when the Agentry
Server creates
a connection to the database. This differs from the DbConnect section
in that DbConnectionInit scripts are run whenever
the Agentry
Server creates
a new connection to the database, not just during startup and reconnect.
New connections may be made whenever a user synchronizes the Agentry
Client,
or when the Agentry
Server adds
a connection to the shared connections pool.
- [ValidateUser] - This section can contain a
list of SQL scripts to be run to validate a user against the database
during client-server synchronization. These steps are the primary processing
for user authentication with a SQL Database system connection. These
scripts are run after those listed in [DbConnectionInit] and
before any step definitions for the application are processed. If
the scripts listed here return one of the failed validation values
the user will be logged out of the Agentry
Server.
No application data will be synchronized in this situation.
- [ValidatePreviousUser] - This section can contain
a list of SQL scripts to be run to validate a previous user against
the database during client-server synchronization when a user change has
occurred on the Agentry
Client.
These scripts are run after those listed in [DbConnectionInit] and
before those listed in [ValidateUser]. If the scripts
listed here return one of the failed validation values (discussed
in the section on security) the previous user’s data (pending transactions
on the Agentry
Client)
will not be synchronized. In this situation, a user change cannot
be completed until the previous user’s data has been successfully
synchronized.
- [LoggedIn] - This section can contain a list
of SQL scripts to be run after a user has been logged in successfully;
that is, the scripts listed in the [ValidateUser] section
have successfully validated to the user.
- [LoggedOut] - This section can contain a list
of SQL scripts to be run just prior to a user logging out of the
server, when client-server synchronization has completed.
- [UserInfo] - This section can contain a list
of SQL scripts to be run after those listed in the [LoggedIn] section
have been run, and before the step definitions for the application
are processed. These scripts are expected to return values that
are then accessible to all other SQL scripts run against the system
connection for a user. This includes SQL step definitions within
the application itself. The values are available via the Syclo Data
Markup Language using the data tag <<user.info.valueName>>.
- [ApplicationGlobals] - This section can contain
a list of SQL scripts to be run to retrieve override values for
global definitions within the application. These values are for
the application in general and not considered to be user-specific.
- [UserGlobals] - This section can contain a
list of SQL scripts to be run to retrieve override values for global
definitions within the application. These values are for a specific
user or user group and allow for overrides on a per-user basis.
- [LoginFailed] - This section can contain a
list of SQL scripts to be run when a user fails validation, i.e.,
when scripts in the [ValidateUser] or [ValidatePreviousUser] indicate the
user has failed validation. This section is processed when validation
fails for any reason, including the user being blocked.
- [LoginBlocked] - This section can contain a
list of SQL scripts to be run when a user fails validation because
they have been blocked from having access. The scripts in [ValidateUser] or [ValidatePreviousUser] must
explicitly indicate the user has been blocked. In this case, these
scripts are run after those in [LoginFailed].
- [ChangePassword] - This section can contain
a list of SQL scripts to run to process a password change by the
user. These will be run after a user receives notification of an
expired password or when a password is about to expire. These scripts
should then perform the necessary processing to change the user’s
password. The scripts are expected to return a value indicating
success or failure in processing the password change.
- [ChangePasswordFailed] - This section can contain
a list of SQL scripts to run when a user password change fails.
These scripts can return messaging to be displayed on the Client
providing the user with information on the reason the new password
was rejected.
- [EnablePush] - This section can contain a list
of SQL scripts to run when a user performs a transmit and stays
logged in for push processing. Specifically, these scripts are run
when all of the following conditions are met:
- The Agentry
Client remains
connected after synchronization as the transmit configuration definition
is defined to enable push functionality.
- A Push definition exists within the application.
- [DisablePush] - This section can contain a
list of SQL scripts to run when a client previously connected to
the Agentry
Server to
receive push data is about to disconnect. These scripts are run
prior to those listed in the [LoggedOut] section.
- [TimeZone] - This section can contain a list
of SQL scripts to run to determine the time zone of the database.
The time zone returned by these scripts will be used when converting
date and time values from one time zone to another, based on the
database and Agentry
Client time
zones.