 |
Formula language, LotusScript, and Lotus Domino Connector variables
Updated: 10/01/2001
Related link:
More Professor INI |  |
We've received many questions about NOTES.INI variables that relate to programming in Notes/Domino applications. Perhaps they are best summed up by the following question.
Q: I’m a Notes/Domino applications developer, and I program in LotusScript and the formula language. I’m just starting to use Java as well. Are there any NOTES.INI variables that I can use that will help me with my programming?
This month, we'll address NOTES.INI variables that relate to the formula language, LotusScript, and the Lotus Domino Connectors. Next month, we'll tackle those related to Java. But first, some basic information.
The Domino Designer Integrated Development Environment (IDE) is comprised of the LotusScript, JavaScript, and formula languages. Java access to Domino objects (through CORBA), although not actually part of the Domino Designer IDE, relies on Designer for compilation and a Domino server at runtime (for applications).
JavaScript and the formula language do not need any NOTES.INI variables to operate properly (with the minor exception noted below). LotusScript, including LotusScript Domino Objects and Lotus Domino Connectors, and the Java/CORBA package, have several.
Note: NOTES.INI variables related to debugging are not addressed in this article. For more information concerning NOTES.INI debug variables, see the Ask Professor INI column, Using debugging variables.
Most of the variables discussed in this article are Notes and Domino R5 NOTES.INI variables. We’ve included some Rnext-only variables (these are so noted), but please keep in mind that Rnext-only variables are works in progress and, therefore, are subject to change before Rnext is released.
Much of the information contained in this article can be found in Domino R5 Designer Help. However, additional details were gleaned through discussions with the developers and are not documented.
Some of the variables mentioned here are set through the Notes or Administrator client's user interface, but many are set by modifying the NOTES.INI file directly (for example, by using a text editor). In general, we discourage editing the NOTES.INI file directly because of the damage that can be done by modifying it incorrectly. If you find you need to edit the NOTES.INI file directly, do so with caution and great care.
That said, let’s take a look at some NOTES.INI variables and their effect on programmability in Notes and Domino.
Variables and the formula language
The Formula language itself has no NOTES.INI variables it depends on in order to function correctly. However, there is one variable you need to know about because it can interfere with several formula functions:
NoExternalApps=1
If the NOTES.INI file includes this statement, then any formula involving any of the following features is disabled:
- @Command
- @DbCommand, @DbColumn, @DbLookup (only if they refer to a non-Notes database)
- @MailSend
- @PostedCommand
- Dynamic Data Exchange (DDE) including all @DDE functions
- Object Linking and Embedding (OLE)
- Launching attached files
The formula won’t execute, but users won’t see a message to let them know the application is not proceeding normally. If this variable is set to 0, or more likely, simply is not present in the file, then there is no effect on the above features.
Environment variables
In addition, the formula language has the following NOTES.INI variable-related functionality:
- The function @Environment lets you set or get an environment variable stored in the user’s NOTES.INI file.
- The function @SetEnvironment lets you set an environment variable when nested inside another function, such as @If or @Do.
- The formula language also contains a keyword, ENVIRONMENT, which works in the same way as @Environment.
Variables and LotusScript
The NOTES.INI variables that LotusScript relies on concern themselves with functionality such as specifying server options, determining international settings, and setting environment variables for use with the new LotusScript feature, JavaConnect, which is available in Rnext.
DominoAsynchronizeAgents
If your environment needs to support multithreading, you can enable this feature by setting this variable to 1:
DominoAsynchronizeAgents=1
The default is 0, which disables multithreading. You set this variable in the Domino server NOTES.INI file.
JavaUserClasses
JavaConnect uses this variable when working with Notes agents. If you don’t have your Java classes in a script library attached to your LotusScript agent (which is the preferred approach), and you are calling JavaConnect directly from a Notes agent, you must include this variable in your client's NOTES.INI file so that the client knows where the Java classes are.
The variable's syntax is:
JavaUserClasses=<directory1>;<directory2>;…
Set this particular variable in both the Notes client and Designer NOTES.INI files.
Note that you should not enter more than one JavaUserClasses entry in a NOTES.INI file. Although you can have as many as you like, only the first occurrence will be used; all others will be ignored. If you have multiple uses for JavaUserClasses, enter all the parameters on the same line. For example:
JavaUserClasses=<directory1>;<directory2\jarfile>;<zipfile1>;…
Keep in mind that there's a 256-byte limit for NOTES.INI entries. Use JavaUserClasses sparingly.
ScriptLanguageID
This variable determines some of the resources concerning internationalization. Its syntax is:
ScriptLanguageID=<language code>
where <language code> is a 2-letter language code, as defined in ISO 639. This code determines:
- Which LotusScript resource DLL is used (that is, which strings are displayed for day and month names, date formats, and so on).
- Which IDE resource DLL is used (that is, which strings appear in the IDE UI).
For more information on the codes, see the ISO 639 Joint Advisory Committee page. Note that some international versions of Notes simply retain the English names for the resource DLLs. Also, LotusScript reverts to using the English resources if it cannot find the specified resources.
This is a local variable and should be set in the client’s NOTES.INI file.
You can get the value of this variable in LotusScript by using the function GetThreadInfo(LSI_THREAD_LANGUAGE). You must include lsconst.lss to use the LSI_THREAD_xxx constants.
ScriptCountryID
This variable, also for internationalization, is used only for IME (Input Method Editor) related functions, such as IMESetMode. Its syntax is:
ScriptCountryID=<country code>
where <country code> is a valid country code as defined in the ISO 3166 standard. For more about these codes, see the National Information Standards Organization About 3166 Country Codes page.
This is a local variable and should be set in the client’s NOTES.INI file.
You can get the value of this variable in LotusScript by using the function GetThreadInfo(LSI_THREAD_COUNTRY). You must include lsconst.lss to use the LSI_THREAD_xxx constants.
ServerTasks
In general, this variable must be set for anything to run on the server. JavaConnect requires that the HTTP server task be running. Its syntax is:
ServerTasks=<any other tasks>, http
where <any other tasks> are any other needed server tasks. This variable is set in the server NOTES.INI file.
Environment variables
In addition, LotusScript classes include the following NOTES.INI variable-related functionality:
- The GetEnvironmentString (for strings) and GetEnvironmentValue (for numeric values) methods of the NotesSession class retrieve the value of an environment variable from the current user’s NOTES.INI file.
- The SetEnvironmentVar method of the NotesSession class sets the value of a string or numeric environment variable.
- LotusScript also contains the function Environ, which returns information about environment variables.
Variables and Lotus Domino Connectors
Lotus Domino Connectors provide native access to a variety of products and systems, including DBMS products, ODBC, the platform file system, enterprise resource planning (ERP) systems, and transaction processing systems. LotusScript extension (LSX) libraries, similar to VBXs for Visual Basic, provide functionality and class extensions to LotusScript.
ConnectionPooling
This variable determines whether or not to allow a connection to an ODBC data source to be reused. The variable contains a list of comma-delimited Lotus Domino Connector names, the pool size, and an optional data source maximum. Its syntax is:
ConnectionPooling=<Lotus Domino Connector name1, pool size1, (optional data source maximum1)>, <Lotus Domino Connector name2, pool size2, (optional data source maximum2)>,…
This variable is set in the NOTES.INI file of the computer that is executing the code—that is, the client, the server, or both.
Domino Enterprise Connection Services variables
The next three variables are used to control certain aspects concerning Domino Enterprise Connection Services (DECS). All three variables are set in the NOTES.INI file on the Domino server running DECS.
Note: In Rnext, as a result of aligning the Lotus Connector LSX and the Lotus Enterprise Integrator LSX, the following NOTES.INI variables will become EITRanslation, EICenturyBoundary, and EINativeText, respectively.
DECSTranslation
This variable controls text translation. It provides for increased performance, albeit at the cost of making certain assumptions about the data being accessed. It syntax is:
DECSTranslation=<value>
The variable can be set to:
- 0 – Do not translate character sets.
- 1 – Translate only between LMBCS or Unicode and other character sets.
- 2 – Translate between all different character sets. This is the default.
DECSCenturyBoundary
This variable, which addresses the Y2K issues surrounding years represented by two digits, controls the interpretation of how the year in a text string is converted when the year contains only two digits. Its syntax is:
DECSCenturyBoundary=<value>
There are three cases that define a specific century:
- If the variable is set to 0, the date is always converted to 1900.
- If the variable is set to 100, the date is always converted to 2000.
- If the variable is set to 101, use the current century.
In all other cases, the variable is set to a value representing the last two digits of the "boundary" year, which determines which century the date falls in, either the 2000s or 1900s. If the two-digit year in the text string is less than this value, the date is converted to fall in the 2000s; and if it is more than this value, the date is converted to fall in the 1900s.
For example, the default value for this variable is 50. If the text string contains a year from 01 to 49, the date is converted to a date in the 2000s. If the text string contains a year from 50 to 99, the date is convert to a date in the 1900s.
DECSNativeText
This variable setting allows the local machine’s native character set to be overridden. Its syntax is:
DECSNativeText=<value>
Its value is a string indicating the character set to use and is based on a specific set of string constants that are listed in the “List of Supported Character Sets” topic under Lotus Connectors in Domino R5 Designer Help. For example, IBMCP932 is the string for code page 932, and UTF8 is the string for Unicode Transformation 8.
DominoAsynchronizeAgents
LotusScript Data Objects (LS:DO) is a LotusScript extension library for working with Open Database Connectivity (ODBC). This library depends on your setting the DominoAsychronizeAgents variable to enable multithreading. Its syntax is:
DominoAsynchronizeAgents=1
The default is 0, which disables multithreading. This variable is set in the Domino server NOTES.INI file.
ODBCThreadSafeDrivers
LS:DO relies on the settings of this variable to determine which ODBC drivers are thread-safe. LotusScript uses the appropriate type of threading for each driver based on this statement. Its syntax is:
ODBCThreadSafeDrivers=<driver-name1>, <driver-name2>,…
If all the ODBC drivers you are using are thread-safe, you can specify:
ODBCThreadSafeDrivers=ALL
If none of the ODBC drivers you are using are thread-safe, you can specify:
ODBCThreadSafeDrivers=NONE
If you have a combination of thread-safe and non–thread-safe drivers, you can specify:
ODBCThreadSafeDrivers=driver-name [, driver-name]
ODBCNonThreadSafeDrivers=driver-name [, driver-name]
This sets up a multithreaded environment by identifying which drivers are thread-safe and which are not.
Coming up
This concludes the first part of our exploration of NOTES.INI variables and programmability. In future columns, we will present NOTES.INI variables that relate to Java and to the Notes and Domino programming toolkits.
Do you have a NOTES.INI question? Send it in to Professor INI. We'll answer as many questions as we can in future "Ask Professor INI" columns. Keep in mind, however, that we may not be able to answer every question, nor can we quickly respond to requests that require immediate attention. If you need an immediate response to a question, we recommend you post it in the Iris Cafe Notes/Domino Gold Release Forum where someone from the general Notes community might be able to help, or contact Lotus Customer Support. |