| Oracle® Retail Predictive Application Server Administration Guide for the Classic Client Release 14.1 E59120-01 |
|
 Previous |
| Oracle® Retail Predictive Application Server Administration Guide for the Classic Client Release 14.1 E59120-01 |
|
Previous |
RPAS includes a number of environment variables that are set at the system level in UNIX. At the system level, the variables are applicable to all RPAS Servers (DomainDaemons) that are run on the system.
The common syntax for setting these variables is as follows:
export ENVIRONMENT_VARIABLE=XXXXXX
ENVIRONMENT_VARIABLE is a defined variable that is recognized by RPAS. XXXXXX is an appropriate value for the variable, which could be a string, Boolean value, numeric value, or date and time. If the value represents time, this number normally represents time in milliseconds.
|
Note: The DomainDaemon must be restarted after setting any environment variables. An example of how this process is completed is as follows:DomainDaemon -port 55123 -start -debug & |
This appendix describes the following environment variables used for RPAS:
The following environment variables are required.
RPAS_HOME
RIDE_HOME
RIDE_OPTIONS
JAVA_HOME
RPAS_JAVA_CLASSPATH
PATH
Since these environment variables are required at the time of installation, and since they vary according to the operating system that RPAS is running on, these environment variables are described in the "Installing on UNIX and Linux Environments" chapter of the Oracle Retail Predictive Application Server Installation Guide. See that chapter for detailed instructions for those environment variables.
These variables are used for RPAS B-tree storage performance.
RPAS BTree arrays contain a field named array tag. Whenever a BTree array is written, the value of the RPAS_ARRAY_TAG environment property, if it is set, is written as the value of the array tag field. By using this property, users can set a record in an array to provide information about the last time the array was modified.
RPAS_CACHE determines the number of pages of a BTree array file that are contain in memory. This variable can be set to have values between 16 and 512 (including 16 and 512). The larger you set the cache value, the more memory usage and less disk access you have.
If you set the cache size from 4 to 64, the performance of the BTree arrays should level out around 16 pages. In tests, more pages did not provide better performance. However, for other access patterns, more cache pages may improve performance. Therefore, a larger cache and page size may increase performance due to less disk access. However, having a larger cache and page size increases the memory image of an open BTree file. It is likely that if the number of cache elements is 512 and the page size is 256K, then each open BTree file could use up to 131,072K of memory.
export RPAS_CACHE=16
Values: 4, 8, 16, 32, 64, 128, 256, 512
RPAS_PAGE_SIZE determines the size of a single BTree array page if the logical size of the BTree array is greater than 200,000 cells. A BTree array is compose of a number of pages and page types. Each page of a BTree array file is the same size. In the trunk, there are five pages types: header, branch, leaf, data, and free. A larger page size implies more memory usage, less fragmentation, and less disk access.
The page size also affects the disk overhead that each BTree file requires. A large page size may provide better disk usage if the array is densely pack. However, large page size with a loosely pack array uses more disk space. For example, consider the effect of having 1,000,000 cells with only one cell populated on a 256K page versus one cell populated on a 16K page. The first case requires 256,000,000K of disk space, while the second requires 16,000,000K of disk space.
Therefore, RPAS_PAGE_SIZE and RPAS_CACHE both affect performance based on the access pattern. RPAS_PAGE_SIZE affects disk space and memory usage, and RPAS_CACHE affects the memory usage.
export RPAS_PAGE_SIZE=32K
Values: 4K, 8K, 16K, 32K, 64K, 128K, 256K
This variable sets the page split percentage. The page split percentage determines the percentage of low order keys to keep in the low order page of the B-Tree when a full page is being split to accommodate data for a new key. It is expressed as a number between 1 and 100. RPAS stores non-NA values only. If an operation (load or calculation) causes a value to be non-NA, RPAS tries to store it on a page and, if the page is full, it causes it to split. Page splitting is an expensive operation; that is, it takes a significant amount of processing time and if it happens too often, it can significantly slow down the load or calculation process causing the splits. For efficient storage and to prevent pages from being split very often, it is recommended that the value be kept between 50 and 90. If this environment variable is not set, RPAS uses a page split percentage of 90.
This environment variable sets the maximum number of milliseconds to wait for a database lock. The default value, 60,000, forces a database lock to wait for a maximum of one minute before throwing a database lock exception.
export RPAS_LOCK_TIMEOUT=60000
Values: 60000, 90000, 120000, and so on
When performing certain operations, it is possible for two or more users to be contending for access to the same database, which happens most commonly when two users attempt to simultaneously commit and save the same data back to the domain. This can also occur when running RPAS utilities in parallel to prevent database locking during batch operations. By default, RPAS is set up to wait one minute before returning a lock contention error when this situation occurs.
If desired, an administrator can override this default value by setting the RPAS_LOCK_TIMEOUT environment variable. This variable is set to the number of milliseconds to wait for a file lock before returning a lock contention error. As with any environment variable, the variable must be set prior to starting the process that uses that variable. The variable was introduced for use with the RPAS database server, which means that the variable is set for the DomainDaemon.
For example, the line below indicates how an administrator would tell RPAS to wait two minutes before returning a lock contention error with the RpasDbServer after launching the client and logging in. Any client that connects to that domain daemon would see lock contention after a two minute delay:
Export RPAS_LOCK_TIMEOUT=120000
On the client side, the exception sent from the server appears as a warning dialog box only after some new action is initiated. With the client, additional warning dialog boxes are displayed to the user.
The RPAS_REQUEST_TIMEOUT environment variable is also used to handle issues with firewalls and the RpasDbServer. The RpasDbServer checks RPAS_REQUEST_TIMEOUT to determine what should happen when it has been idle for a period of time. Like any environment variable that RpasDbServer uses, this environment variable must be set prior to starting the DomainDaemon.
The environment variable RPAS_REQUEST_TIMEOUT should be set to a value that is the number of seconds of idle time that should pass before the RpasDbServer sends a ”Server has timeout waiting for a request” exception to the client and exits. In this case, idle time is the time waiting for a request. If this variable is not present or is set to zero, then the RpasDbServer will never time out.
export RPAS_REQUEST_TIMEOUT=600
Values: 600, 900, 1200, and so on
This environment variable determines how the DbCloser class behaves. It controls whether the DbCloser aggressively closes databases. The ”single” value puts the DbCloser is single user mode. This is useful for running batch processes when no users are logged in, because in such a situation there is no need to rapidly close databases.
export RPAS_USER_MODE="single"
Value: single
The following environment variables can be used for Java special expression settings.
When using the Java Special Expression functionality, the RPAS_JAVA_CLASSPATH environment property contains the location of the Java expressions. The value of RPAS_JAVA_CLASSPATH should be a set of paths to the jar files that contain the compiled Java expressions. The list of paths must also contain the path to the jar file oracleRpasUtils.jar located within the lib subdirectory of RPAS_HOME.
The RPAS_JAVA_DEBUG_PORT environment variable can be used to specify to RPAS what port the JVM, created to execute a Java Special Expression, should listen to in order for a debugger to attach to the JVM. It can be used to debug Java Special Expressions during their development. The value of the RPAS_JAVA_DEBUG_PORT property should be an integer within the range of available port addresses.
The RPAS_JAVA_MAXHEAPSIZE environment property can be used to specify to RPAS that the JVM, created to execute a Java Special Expression, should request more memory from the OS than the default. The value of RPAS_JAVA_MAXHEAPSIZE should be the number of megabytes of memory to request followed by the letter 'm' (for example, 1024m).
The following environment variables can be used for log settings.
The RPAS loadmeasure application uses these environmental variables. The RPAS_DISABLE_LM_DIRECT environmental variable may be "yes" or "1" to force the loadmeasure application to run in legacy mode which disables the use of the RPAS_CACHE_LM_MULTIPILER variable.
The RPAS_CACHE_LM_MULTIPILER variable must be between 2 and 10 and is used to compute the amount of data the loadmeasure application will cache base on its value and the value of the RPAS_CACHE variable.
These environmental variables determine the amount of time a TCP/IP read or write call waits for data to be processed. If no data has been processed in the amount of time provided, RPAS throws an exception.
These environmental variables determine the number of failed or success entries that are kept in the success or failed directories for commit ASAP.
This environment parameter, if set, applies only to the RPAS Java Special Expression functionality, and is passed along as the -Xmx argument to the Java JVM instance.
This environment property gives a directory path to which detailed file lock history data will be written, in binary form, using one log file per RPAS process. The lock detail files, which will not be human readable, are constructed to be extremely compact so that a large amount of file history can be written efficiently. These details consist only of the file's inode (internal operating system identifier for the file), the operation (open for read, open for write, close), and a date/time code. The utilities for analyzing this information are not currently a part of the official RPAS release, so the data would need to be sent to the RPAS Development staff for analysis. Because of this, the environment variable should only be set when requested by RPAS Development or Support in cases of an ongoing support need related to file lock contention.
This environment property causes RPAS binaries to log details about the locking and unlocking of files. The value for RPAS_LOCK_LOGGING should be set to the logger level (error, warning, debug, profile, information) at which the file lock details will be output. So, for instance, with RPAS_LOCK_LOGGING=debug, if you run an RPAS binary with -loglevel debug, then you will see the file lock details, but if you run the binary with -loglevel warning, you will not see them.
This environment property gives a file path to which details of file locks will be written, in human-readable text form. The details match those which are output to the screen when RPAS_LOCK_LOGGING is set to an appropriate level.
This environmental variable will filter the logged file lock information in order to limit it to one or more databases of interest. It should be set to a comma-separated list of database names, for example "admin,measdata". This would cause lock information to be logged only for files in the admin.db and measdata.db databases.
This setting works in conjunction with these other environment variable settings:
RPAS_LOCK_LOGGING
RPAS_LOCK_ACCESS_LIMIT
RPAS_LOCK_LOG_PATH
RPAS_LOCK_TRACK_PATH
Set this environmental variable to the maximum number of seconds a lock file can be locked before the name of the lock file is logged. The logging occurs at the level provided by the environmental variable RPAS_LOCK_LOGGING. This allows you to filter out brief lock times from the log, showing only those files which are locked for a longer time.
The RPAS_LOG_BACKUPS environment variable sets the maximum number of log files to keep.
export RPAS_LOG_BACKUPS=20
Values: 2, 3, 4, 10, 20, 30, and so on
The RPAS_LOG_BACKUPS environment variables allow an administrator to define the number of log file backups to retain for a given user. A log file is created each time for each session that a user has with the RPAS Client.
The environment variable is set by executing the following command:
Export RPAS_LOG_BACKUPS=X
X is an integer value that represents the number of backup log files to keep for each user.
This environment property causes RPAS binaries to log the opening and closing of all file handles. The value for RPAS_LOG_FD should be set to the logger level (error, warning, debug, profile, information) at which the file open/close details will be output. So, for instance, with RPAS_LOG_FD=debug, if you run an RPAS binary with -loglevel debug, then you will see the file lock details, but if you run the binary with -loglevel warning, you will not see them.
Setting this environmental variable to anything other than empty or the string "false" (case-insensitive) causes the RPAS logger to flush the output after each line of output. This may cause a tiny performance impact, but ensures that all logger output has been sent before any error or crash condition. It should generally only be needed in cases of debugging.
The RPAS_LOG_LEVEL environment variable sets the default logging level to use when an application starts.
export RPAS_LOG_LEVEL="debug"
Values: all, profile, debug, audit, information, warning, error, none
The RPAS_LOG_PATH environment variable contains the path of a directory where RPAS daemon applications creates log files. The default is the current working directory where the application was started from.
export RPAS_LOG_PATH=" C:/RPAS/Domains/Temp"
Value: The absolute path to the directory where RPAS daemon applications creates log files
This environmental variable specifies an amount of time (in seconds) that a TCP/IP read or write call will wait for data. This functions similarly to the RPAS_SERVER_TIMEOUT environment setting, however, this variable only applies to the RpasDbServer application. The intent of this environmental variable is to handle the issue of fire walls. A firewall may be setup to kill any TCP/IP connection that is idle for 60 minutes. If someone using the client has connected to an RpasDbServer behind a fire wall with this setup, they could run into this issue. If the RPAS Client user is connected, but leaves the connection idle for 60 minutes (for example, over lunch hour), the fire wall would then kill the connection. The Client appears connected, but will not be functional. If the user attempts to reconnect to the server, the RPAS DomainDaemon will not allow the connection since the earlier RpasDbServer process is still running. Setting the RPAS_REQUEST_TIMEOUT to 30 minutes (or 1800 seconds) using the export command before starting the DomainDaemon:
export RPAS_REQUEST_TIMEOUT=1800
Now the RpasDbServer will timeout after 30 minutes of idle TCP/IP time. The Client user will then be able to reconnect to the server since the previous session will have properly disconnected.
This environment setting applies only to running the RPAS Server on Windows in the Cygwin environment, and is needed only if your Cygwin installation is in a non-standard directory location. RPAS Server code will expect to find the Cygwin BASH shell executable at the path C:/cygwin/bin/bash.exe. If your Cygwin BASH shell is located at a different path, set the RPAS_SHELL environment variable to the correct location.
This environment parameter optionally adjusts the size (in megabytes) of the file buffer used in the internal measureFileSplitter utility. If needed, it should be set to a positive integer value; if not present, the default of 8 is used.
This environmental variable is used to determine where to write the stats information gathered during a workbook build.
The RPAS Client/Server communications use a TCP/IP interface. Built in to most TCP/IP implementations is an efficiency improvement known as Nagle's Algorithm. A complete discussion is beyond the scope of this document (see http://en.wikipedia.org/wiki/Nagle's_algorithm), but it relates to added efficiency when sending many small packets of data by grouping them. However, this can cause delays in certain communication patterns, an issue that some customers detect when using RPAS. To disable Nagle's Algorithm, you may set environment variable RPAS_TCPNODELAY to "on". Conversely, to enable Nagle's Algorithm, the value of RPAS_TCPNODELAY may be set to "off". If the environment variable is unset, or set to anything besides on or off, the TCP/IP communication behavior is determined by your operating system settings.
This environmental variable is used to create a log file of the SSL handshake. This variable must be set to two values with a comma separator. The first value must be one of these strings: "fatal", "error", "warn", "user", "debug", "ssl", or "memory". The second value can be either an RPAS loglevel string such as "basic", "none", "error", "warning", "information", "audit", "profile", "debug", or "all"; or an absolute path to a log file.
To set the ssl trace to "user" level and log to the file "/home/larry/ssltrace.log" use:
Export RPAS_TRACE_SSL=user,/home/larry/sslTrace.log
To set the ssl trace to "debug" and log the output to the RPAS logging level "debug" use:
Export RPAS_TRACE_SSL=debug,debug
The RPAS Server sometimes needs to create temporary files. By default, these are placed into the /tmp directory. If the RPAS administrator wishes to set a different location for temporary files, the TMPDIR environment variable should be set to the full path to this directory.
See RPAS_TODAY in the Date and Time Setting section.
The following environment variables can be used for parallelization settings.
The RPAS command-line utility "exportMeasure" runs sub-processes in order to support greater efficiency by parallel processing. A positive integer value assigned to RPAS_EXPORT_MEASURES_MAX sets an upper limit on the number of measures to be handled by each invocation of the sub-process. If the environment variable is not set, the default value of 100 is used.
The RPAS command-line utility "loadmeasure" runs sub-processes in order to support greater efficiency by parallel processing. A positive integer value assigned to RPAS_MIN_MEAS_PER_PROC sets a lower limit on the number of measures being loaded in each sub-process. If the environment variable is not set, the default value of 100 is used.
This variable is used when performing batch measure registration. It sets the maximum number of processes used to stage data. The default is 1, which causes all processes to be run serially.
If a user specifies a value less than 1, it will override to 1. If a user specifies a value greater than the number of subdomains, it will be override to the number of subdomains in the global domain. If this variable is set to a number greater than 1 when doing a measure registration in a global domain, RPAS spawns that number of parallel processes to register or unregister measures in each local domain.
export RPAS_PROCESSES=4
Values: 1, 2, 3, 4, and so on
The following two environment variables may be set up to control profiling logging:
The RPAS_PROFILING_ENABLE environment variable, when set to true, allows profiling data to be written to the profiling log file. This flag does not affect writing to a general RPAS log file, which is controlled solely by loglevel.
The RPAS_PROFILING_PATH environment variable defaults to rpasProfile.log if not present. This variable specifies the profiling log file name. It can be overridden programmatically in the constructor of the profiling timer.
The following environment variables can be used to set the date and time.
RPAS_TODAY tells RPAS what day that it should think today is.
RPAS_TODAY=20090530
Note: TODAY_RETEK is an older, deprecated synonym. It is allowed for historical reasons, but RPAS_TODAY is preferred.
The RPAS_TODAY_STATIC environment variable affects how date and time and the RPAS_TODAY environment variable are handled. The setting of RPAS_TODAY_STATIC affects the date and time that is returned by the DateTime::now() function.
If RPAS_TODAY_STATIC is set to true, all calls to DateTime::now() return the same date and time as the first call made to the DateTime::now() function. The same date and time is returned no matter how many times the DateTime::now() function is called.
For example, RPAS_TODAY_STATIC is set to true and RPAS_TODAY=20090530. If a call is made to DateTime::now() at 10:30 pm, it returns a date and time of 5/30/2009 10:30:00 pm. If another call is made 10 minutes later to DateTime::now(), a date and time of 5/30/2009 10:30:00 pm is also returned.
Set the HHMMSS portion of RPAS_TODAY (YYYYMMDDHHMMSS) when setting the RPAS_TODAY_STATIC to TRUE. The function DateTime::now() or keyword 'now' also include the time of the day in its value. If RPAS_TODAY_STATIC is set to TRUE and if YYYYMMDDHHMMSS format is not used but YYYYMMDD format is used while setting RPAS_TODAY, then the day portion of 'now' will remain the same but the HHMMSS portion of 'now' changes.
If RPAS_TODAY_STATIC is set to false, a call to DateTime::now() returns the current date and time.
For example, RPAS_TODAY_STATIC is set to false and RPAS_TODAY=20090530. If a call is made to DateTime::now() at 10:30 pm, it returns a date and time of 5/30/2009 10:30:00 pm. If another call is made 10 minutes later to DateTime::now(), a date and time of 5/30/2009 10:40:00 pm is returned.
User level environment variable TZ (time zone) needs to be set for the user who starts the RPAS server processes (DomainDaemon, RPAS ODBC Server) or runs RPAS utilities (like printMeasure). A missing TZ causes the system to misinterpret the date value stored in RPAS. For example, on a Linux system, the default DATE type measure NA value of 0001/01/01 would be interpreted as 7295/12/31 23:00:00.000 if TZ were not set.
If the user is in time zone EST5EDT, use the command export TZ=EST5EDT to set TZ. It is suggested that the command be added to user's login script (for example, .profile).
Two variables affect the level of numeric precision that is displayed in the RPAS clients:
RPAS_INCAGGPRC: An environment variable.
epsilon: The smallest difference that is allowed between any two numbers.
Use the RPAS_INCAGGPRC environment variable to set how a number's precision is displayed. Set this variable to the precision level you want displayed. The default value of this variable is 1e-06. Unless this variable is altered, very small values, such as 0.00000001, are displayed as 0.
Following is an example of setting this variable to a value smaller than the default:
export RPAS_INCAGGPRC=0.0000000001
The epsilon variable also affects the level of precision that is displayed. This variable is returned as a value by a public static function in the MathUtilities.h file. It is hardcoded to 0.0000000001 (1e-09).
RPAS uses the epsilon value to consider any two numbers as different if the difference is greater than or equal to epsilon. If the difference between any two numbers is less than epsilon, then those numbers are considered as equal. Indirectly, the epsilon value affects the display as it sets a limit to the number precision.
|
Note: Reducing the epsilon value may impact performance. |
This variable may be used as an alternative to the -wallet argument to DomainDaemon. If the RPAS_SSL_WALLET environment variable is defined, its value can be used by DomainDaemon in place of specifying the information as a parameter to the -wallet argument.
Please refer to the "DomainDaemon" section of the guide for more information on the use of the -wallet argument.
This environment setting performs two functions:
It creates a special named zone in the memory to load shared libraries for RPAS processes to avoid version conflict.
By default, AIX loads shared libraries in a single global zone. This could potentially cause conflict between the libraries on the system and RPAS versions. For example, RPAS has its own version of libz. If a non-RPAS program has loaded a different version of libz from the system into the global zone, RPAS will use that one instead of loading its own.
It may also reduce the memory footprint for shared libraries in the private memory of RPAS processes.
The global zone can be filled up if the system is very busy. In that case, the shared libraries are loaded into private space of RPAS processes, which would reduce the amount of memory available for RPAS data. A named zone is difficult to fill up since it is used only by RPAS processes.
export LDR_CNTRL=NAMEDSHLIB=RPASZONE
Nagle's algorithm is used to improve the efficiency of TCP/IP networks. The algorithm combines a group of small outgoing messages and sends them all at once. This reduces the number of packets that are sent over the network.
Two settings are used for Nagle's algorithm, RPAS_TCPNODELAY for the Server and FC_TCPNODELAY for the Fusion Client.
Server
Setting RPAS_TCPNODELAY to on disables Nagle's algorithm on the server side when it sends the data back to the client. This setting is useful for improving the performance of the Fusion Client in some cases.
Setting RPAS_TCPNODELAY to off or not setting it enables Nagle's algorithm.
Fusion Client
Setting FC_TCPNODELAY to true disables Nagle's algorithm on the Fusion Client side when it sends the data from the client to the server. This setting is useful in improving the performance of the Fusion Client in some cases.
Setting FC_TCPNODELAY to false or not setting it enables Nagle's algorithm.
