For Windows clients and applications that use the C API, such as the BMC Remedy Email Engine, and so on, you can enable the ARAPILOGGING environment variable to capture all client API calls along with detailed server responses. This log contains different information than the client-side logs that you configure in the user preferences.
ARAPILOGGING can help in troubleshooting situations where you need to determine what client action is generating an error or a delayed response. BMC Software technical support might request a copy of this log when working on an issue. ARAPILOGGING works for all windows clients, the ODBC driver, and API programs that use the arapinn.dll.
When this is enabled, the client logs each API call along with the server response to the file clientInstallDir\arapires.log. If bit 16 is not set, client calls are recorded separately in clientInstallDir\arapicmd.log.
A new log is created each time you restart the client. Previous logs are saved with a sequential number appended to the name, for example, arapires_1.log, arapires_2.log, and so on. (For more information, see the Maximum Backups definition at Setting log files options.)
To avoid consuming disk space unnecessarily, do not leave ARAPILOGGING turned on indefinitely. If you do, the client will continue to log every action while saving old copies of the log files. One way to avoid this is to use the command prompt method to set the variable and start the client as described in this section.
Setting the ARAPILOGGING environment variable
You can set the value of the ARAPILOGGING environment variable to control how the information is logged. This option uses a bit mask to control the log output. You can combine the values to get combined results in the log. The following table describes the effect of each bit mask value.
ARAPILOGGING bit mask values
No logging – Setting ARAPILOGGING to 0 or not setting it at all turns ARAPILOGGING off.
Logging on – ARAPILOGGING is on and minimum output is recorded in the arapicmd.log and arapires.log files. If other options are included, this option does not have to be included in the bit mask.
Record sleep time in seconds – The sleep time in seconds is recorded in the command file.
Record sleep time in milliseconds – The sleep time in milliseconds is recorded in the command file. If both the options (seconds and milliseconds, value = 6) are selected, the sleep time output will be in seconds.
Record start, finish, and elapsed time – The start, finish, and elapsed times are recorded in the result file. The elapsed time includes the time needed for the API to write information to the log file.
Combine the command and result files into the result file – In this case, client commands and server replies are all recorded in the arapires.log, and the arapicmd.log is not created. This output is easiest to use because the client commands and server responses are collated. Do not use this option if you are building a command file to be played back in driver.
Do not record result data output – This option suppresses the output of the result data, limiting the result output to status information only. This option is useful when the quantity of result data is very large and the output can impact performance. This option is also useful to reduce the amount of logging information when the details of the returned data are not important.
Buffer the file output – Utilizes file system buffering to write log output. It can be used to reduce the time required to output the logging information. However, you might lose information if the client you are collecting logging information for crashes before all information has been written to the log.
Setting ARAPILOGGING=24 (8 +16) adds start, finish, and elapsed time to the log (8) and combines the commands and results in the arapires.log (16). In addition, setting the value to 24 now adds the user name, server name, and port number to the output described in this section. This is helpful when you need to use ARAPILOGGING in a multi-user or multi-server environment. BMC recommends setting ARAPILOGGING to 24.
To enable ARAPILOGGING using the Windows System Properties dialog box
- Open the Windows System Properties dialog box as appropriate for your operating system. For example, right-click My Computer, and then select Properties.
- Click the Advanced tab, and then click Environment Variables.
- In the System Variables area, click New, and then enter the following values:
- Variable name: ARAPILOGGING
- Variable value: value
- Click OK to save the variable and exit Windows System properties.
In the browser, perform the actions that you want to capture in the log.
When you have completed capturing information to the log, turn off ARAPILOGGING by repeating steps 1 through 4 and setting the value of ARAPILOGGING to 0.