SqlBE.ini Query Initialization File

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.
Parent topic: Configuring SQL Database System Connections