Referring to options in database applications
Most ODABA applications are referring to a configuration or ini-file in order to load assigned option values. Besides, ODABA provides a standard option dialog, which allows storing user specific options in the application database. Finally, options might be set in the system environment or within the application while running the program.
Options are considered as thread global variables, i.e. each thread running in an application has got its own set of options. This allows changing option values in one thread without affecting other threads. When running in a client/server environment, each client may set options on the server side. Server options are also thread global and are stored separately for each client.
Options are supported in many places in the database system in order to increase flexibility of applications and programs. Thus, one may refer to options in
- file paths
- OSI expressions
- application programs
and in many other places. You may create your own options in your application or refer to options defined in ODABA.
Option values are searched in the following hierarchical order.
- First the options set internally or loaded from application configuration are checked.
- When not being found, the option is searched in the configuration or ini-file associated with the application. When being found, the option is copied to internal options. In order to automatically load options from configuration or ini-files, an appropriate file name has to be passed when initializing an application Application::initializeApplication::initialize() or Application::initializeOptions()).
- When still not being found, the option is searched for in the set of system environment variables. When being found, the option is moved to the set of internal options.
Option values not yet defined are created automatically and set to "". Thus, each option does exist by definition and returns a value, which might be empty.
Application options defined in the application database (e.g. by means of the options dialog) can be loaded into internal options by calling the Database::initializeOptions() function or when running a GUI application by calling the ProjectContext::initializeOptions() function. In a GUI application, user options are read from the database by default using the user's login name as configuration name.
Database paths but also most file path to external files opened in an ODABA application (e.g. locations for import or export) may contain option references (%option_name%). Those references are resolved before opening the file. A file path may contain any number of option references.
When the file is opened on the server, options must have been defined on the server side.
// the ini-file defines PROJECT_ROOT, e.g.as
// PROJECT_ROOT=C:/odaba/my_projects
// now, tha database path can be referred to as:
%PROJECT_ROOT%/database.dat
Slashes in the path are not provided automatically and must be set explicitly in the path. It is suggested not to rely on terminating slashes to be defined as part of the option value, but define slashes explicitly in the path.
A database path refers to the location of the root base for the database. Paths can be defined as absolute or relative paths, or as reference path containing symbolic references enclosed in %...% (%option_name%).
Symbolic path references are resolved by replacing corresponding option values defined in the application or main option section in a configuration or ini-file. When running local or file server applications, symbolic names in the path must be defined on the local machine. When running a client/server application, the database file path is passed to the server and symbolic variables are resolved (and must be set properly) on the server side.
OSI functions may refer to option variables. Within an OSI function, one may refer to options as option variables, except, using the option path enclosed in %...%, or by using odaba::Option functions. Referring to undefined option variables always returns an empty string.
Options in OSI functions are typically used in order to implement generic functions, which depend from several options defined in a configuration, an ini-file or set at run-time. In general, however, parameters should be used for program control rather than options.
void main () { // referring to options via %...% option names
%PROJECT_ROOT% = 'c:/odaba/my_projects'; // set option
Message('Value for PROJECT_ROOT is: ' + %PROJECT_ROOT%);
}
void main () { // referring to options via Option functions
Option("PROJECT_ROOT") = 'c:/odaba/my_projects';
Message('Value for PROJECT_ROOT is: ' + Option("PROJECT_ROOT").toString() );
}
In an application, one may retrieve option values by calling option(). In order to set or change an option value, Option::assign() or the assignment operator (=) might be called.
Option option("PROJECT_ROOT")
option = "c:/odaba/my_project";
printf( option.toString() );