Configuring the SqlBe.ini Query Initialization File for Agentry Applications

After configuring the SQL database backend connections in Management Cockpit, you may need to make modifications to the SqlBe.ini configuration file. The SqlBe.ini is the default query initialization file that is provided by the server installer. You can modify the file for a single application, or use it as a template to create other query initialization files for applications that have multiple SQL database system connection types.

Application-Specific Changes

Query initialization files are generally set up initially by application developers, or as the result of development efforts and standard application needs. Before making any changes to the settings, you should have a full understanding of how your changes might impact application behavior. SAP recommends that, rather than changing the Query initialization file, you instead make your changes to the scripts it references.

Any changes you make, either to the settings in this file or to those scripts it references, are generally 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 subdirectories of the Agentry Server within the SAP Mobile Platform installation location (for example, SMP_HOME\Server\Configuration\com.sap.mobile.platform.server.agentry.application\):

sql
sql\custom

These two separate folders allow for both standard and customized processing. For an application implementation, the sql folder contains the standard scripts that are provided with the application installer. Make a copy of each script before you make any changes to it, and then save the new version in the sql\custom folder.

When processing scripts listed in the SqlBe.ini file, SAP Mobile Platform Server looks first in the sql\custom folder. If a script is not found in the \custom folder, SAP Mobile Platform Server then looks for the same file in the sql folder.

To return to default processing, simply move or rename the script file. The next time SAP Mobile Platform Server looks for the script, it finds the default version, and executes it.

Sections Listing

The following is a list of the sections within this file and the events to which they relate:

[Misc] – do not modify this section; it contains two queries, used for internal purposes, that are executed by SAP Mobile Platform Server.
[DbConnect] – a list of SQL scripts to be run when SAP Mobile Platform Server connects to the database. The connection is made when SAP Mobile Platform Server is started, and also when SAP Mobile Platform Server reconnects to the database based on the Disconnect from Database setting in Management Cockpit.
[DbDisconnect] – a list of SQL scripts to be run when SAP Mobile Platform Server disconnects from the database. This occurs as a part of the SAP Mobile Platform Server shutdown process, and also when SAP Mobile Platform Server disconnects from the database based on the Disconnect from Database setting in Management Cockpit.
[DbConnectionInit] – a list of SQL scripts that are run when SAP Mobile Platform Server creates a connection to the database. This differs from the DbConnect section, in that DbConnectionInit scripts are run whenever SAP Mobile Platform Server creates a new connection to the database, not just during start-up and reconnect. New connections may be made whenever a user synchronizes the Agentry client, or when SAP Mobile Platform Server adds a connection to the shared connections pool.
[ValidateUser] – a list of SQL scripts that validate a user against the database during client-server synchronization. These are the primary processing steps 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 is logged out of SAP Mobile Platform Server, and no application data is synchronized.
[ValidatePreviousUser] – a list of SQL scripts that 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 security validation values, the previous user’s data (pending transactions on the Agentry client) is not synchronized. A user change cannot be completed until the previous user’s data has been successfully synchronized.
[LoggedIn] – a list of SQL scripts to be run after a validated the user has logged in successfully.
[LoggedOut] – 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] – a list of SQL scripts to be run after those listed in the [LoggedIn] section, and before the step definitions for the application are processed. These scripts are expected to return values, including SQL step definitions within the application, that are then accessible to all other SQL scripts run against the system connection for a user. The values are available via the Syclo Data Markup Language using the data tag <<user.info.valueName>>.
[ApplicationGlobals] – a list of SQL scripts that retrieve override values for global definitions within the application. These values are for the application in general; that is, not user-specific.
[UserGlobals] – a list of SQL scripts that 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] – a list of SQL scripts to be run when scripts in [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] – a list of SQL scripts to be run when a user fails validation because he or she has been blocked. 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] – a list of SQL scripts that process a password change by the user. The scripts, which perform the necessary processing to change a user's password, are run after a user receives notification of an expired password, or when a password is about to expire. The scripts are expected to return a value indicating success or failure in processing the password change.
[ChangePasswordFailed] – a list of SQL scripts to run when a user password change fails. The scripts should provide the user with information about why the new password was rejected.
[EnablePush] – a list of SQL scripts to run when a user performs a transmit and stays logged in for push processing. Specifically, these scripts run when both of the following conditions are met:
- The Agentry client remains connected after synchronization, as the transmit configuration definition is defined to enable push functionality, and
- A push definition exists within the application.
[DisablePush] – a list of SQL scripts to run when a client previously connected to SAP Mobile Platform Server to receive push data is about to disconnect. These scripts are run prior to those listed in the [LoggedOut] section.
[TimeZone] – a list of SQL scripts that determine the time zone of the database. The time zone returned by these scripts is be used when the application converts date and time values from one time zone to another, based on different settings for database and Agentry client time zones.