Share This:

Working with Server side logging used to be a tricky business, but there's been an enhancement not so long ago that makes working with them a lot easier.

Couple this with a way to automate and schedule log files, now you make this work for you as opposed to you working to generate them.



Managing AR Server Log Files


To help ensure the filesystem doesn't fill up when setting AR Server side logging, as of 7.6.04 SP2 there's been a new parameter introduced to assist with this.


The parameter is:


Max-Log-History: <value>


Using this in conjunction with the 'Max-Log-File-Size: ' parameter, you can now control how many backups of the log files will be produced and the maximum size of each.


So for example if you have these parameters set like below:


Max-Log-History: 10                                <----- Valid values are 1 to 999

Max-Log-File-Size: 1073741824              <----- This value is in bytes


Based on these values, the AR Server will create 10 log files each at 1 Gb in size.


The backup log file numbering convention is:





& so on.



NOTE: The same rules as before apply when it comes to naming the log files:

  • If each server side log enabled has a different file name, then 10 backups of each file name will be produced and each will have a maximum file size of 1 Gb.
  • If you combine logs (e.g. enable API and SQL logging but have the same file name) then again, only 10 of these will be produced and they will have a maximum file size of  2 Gb.



The above note is an important factor to consider when choosing the number of backups to keep and the maximum file size of the logs, as it affects how much disk space the logs could potentially consume.


In 7.6.04 SP2-SP4, the 'Max-Log-History: ' parameter is only configurable via the ar.cfg/conf file.

In 7.6.04 SP5, 8.0 and 8.1 you can also configure the value via the Server Information form -> Log Files tab -> Maximum Backups field as follows:





Automating & Scheduling Logging


Ever had the need to debug something on the AR Server side during unsocial hours, but didn't want to leave logging on for a long time which could potentially fill up the filesystem?


There are times when this is needed, such as:

- debugging an escalation running at 4am

- checking the SQL log due to possible database disconnections in the middle of the night


Wouldn't it be good if it was possible to automate and schedule server side logging so that when you're active during business hours the logs that capture the problem are ready and waiting for you?


This is a possibility, and the key factor here is leveraging the use of the driver utility.



Automating Logging


The driver utility is installed as part of the AR Server Clients install. Even with 8.x and above codeline, now that the User Tool is no longer offered, driver still exists.


You can find it located here:


Windows     <ARS_HOME>\Arserver\api\driver

UNIX           <ARS_HOME>/ARSystem/api/src/driver


There is a disclosure about the driver utility that must be stated:



It's an unsupported tool, but it is solid and can be used to run or script the execution of API calls.  

We support it up to the point that if there is a problem, we will log a defect. However, it is pretty solid and low-tech so we don't expect problems. Because of this, we are happy to have customers use it.

It was designed to be a tool for use by BMC Support to troubleshoot problems. As such, there is not much documentation for it because it was intended to be used on a case-by-case basis.

We don't provide support for assisting to script it to achieve an individual customer's business need/goal, but we still recommend using it if possible. There is an assumption that you already know what API calls to use.



If you've never seen driver before - this is what it looks like:


driver 7604.pngdriver - a command driven tool



In order to be able to schedule activating & de-activating server side logs, you need to be able to pass a script into the driver utility.


There's two ways in which to accomplish this:


  1. Use KA406566 here to effectively record the manual steps that you would take in the application to complete the task
  2. Use the shortened version as provided below.


Recording the API calls via the application


KA406566 is not only good in explaining how to record the manual steps taken in the application, but it also explains the additional steps needed to prepare the script for use. This is in section B as follows:



B. Edit the arapicmd.log file using an editor that will not add hidden special characters

  1. Delete all lines that start with # and delete only lines that start with #

    example of lines in arapicmd.log file to be deleted


  # ARInitialization



  2. Add the following 11 lines (lines 2,5,6,11 are blank) to the top of the arapicmd.log file as login credentials:




<user login name>
<user login password>

<name of server being logged into>
<TCP port defined for ARServer>




  3. Replace <user login name> string with the login user name.

  4. Replace <user login password> string with the password for that user.

  5. Replace <name of server being logged into> with the name, FQDN, or IP address of the AR Server.

  6. Replace <TCP port defined for ARServer> with the value of 'TCD-Specific-Port: ' in the ar.cfg/conf file; if none, replace with 0.

  7. Save the file as a new filename as the new driver script file.



The takeaway from this section (to use in any script that you generate for use with driver) is the 11 lines listed in B-2.


An example of the arapicmd.log and it's resultant script file is attached to this blog post.



Using the shortened version


If you look at the arapicmd.log or the resultant script file, you can see that it's quite bulky in terms of the amount of API calls it used.


The reason being is because when navigating through the application, the client does a lot of actions (such as opening, setting values in and saving the Admin console). These are only needed in the client, and because the arapicmd.log records the actions from the client - this is why the file is bulky.


All we really need to do is to set a value for the 'Debug-Mode: ' parameter (in the ar.cfg/conf file) as this is what changes when you enable/disable the server side logs on the Server Information form -> Log Files tab.


To do this requires a single SSI (SetServerInformation) API call that consists of:

  • a single operation
  • operation number 8 (deduced from the a.h file in <ARS_HOME>\Arserver\api\include)
  • the value to set the 'Debug-Mode: ' parameter to


When running it manually within driver, it looks like this:


Command: ssi


   Number of server info operations (0): 1

Server info list entry

Operation (1-401) (1): 8

Datatype Null/Key/Int/Real/Char/Diary/Enum/Time/Bitmask/Byte/Decimal/attach/


         coords/view/display (0-14, 30-34, 40-43) (0): 2

Integer Value (0): x



   ARSetServerInfo  results

ReturnCode:  OK

Status List : 0 items



(where x = the value to set the 'Debug-Mode: ' parameter to)


So putting this into a script, it would look like this:




<user login name>
<user login password>

<name of server being logged into>
<TCP port defined for ARServer>




To turn the logging off, simply set the value to 0:




<user login name>
<user login password>

<name of server being logged into>
<TCP port defined for ARServer>




You can find the bit values for server side logging in the documentation:


7.6.04Configuration Guide page 363 - ar.conf (ar.cfg) file optionsDebug-mode




The bit values are:


Server Logging ModeValue
Server Group256
Full Text Indexer512



How to use the script files with the driver tool is also described in KA406566, but for the sake of simplicity I'll include it here too:



Step 2:

Copy the new driver script file to an environment where the driver executable is available

  • Windows:
    • <ARS_HOME>\Arserver\api\driver
  • Unix:
    • <ARS_HOME>/ARSystem/api/src/driver


The physical location of the driver script itself is not critical.


In a Unix AR Server environment, it will be necessary to set the library path to include the <ARS_HOME>/bin directory.


Step 3:

Execute the driver script through the driver program:

  • Windows (from a command window)
    • driver < <full path and filename of the script>
  • Unix (from the <ARS_HOME>/ARSystem/api/src/driver directory)
    • ./driver < <full path and filename of the script>



For example, my scripts 'Logging_On.txt' and 'Logging_Off.txt' are stored in a directory called 'driver_test' on the Desktop of the machine where the driver tool is located.


To run the scripts, these are the commands needed:


<ARS_HOME>\Arserver\api\driver>driver < "C:\Users\Administrator\Desktop\driver_test\Logging_On.txt"

<ARS_HOME>\Arserver\api\driver>driver < "C:\Users\Administrator\Desktop\driver_test\Logging_Off.txt"



Scheduling Logging


Scheduling these to run at unsociable hours requires the use of a scheduler that has a CLI (Command Line Interface).


I'm going to shamelessly plug using Control-M here, not just because I used to support it; but because I believe it's an incredibly good & stable product and it allows for jobs to run based on dependencies.


For example, I would only want to run my 'Logging_Off.txt' script if the 'Logging_On.txt' script was run previously and that sufficient time had passed in order for the logging to capture the problem.


With CONTROL-M this is possible, and I would create 3 jobs:


  1. Turn Logging On
  2. Sleep for a period of time
  3. Turn Logging Off


The Sleep job wouldn't start until the Logging On job has successfully ended, and likewise the Logging Off job wouldn't start until the Sleep job has successfully ended. See below:


Finished 01.png

These are the jobs running in sequential order within CONTROL-M, and using dependencies.



The job chain has now completed; logging was turned on, a period of time passed and then logging was turned off.



You may well be able to replicate this to some extent with the Windows Task Scheduler or with crontab in UNIX.


The features described in this blog post can be used independently or together, it really depends on what you want to achieve.


I would encourage the use of the 'Max-Log-History: ' parameter (Maximum Backups field) wherever possible to contain the amount of logging that gets written.


For additional Pulse blogs, check out the table here.


Please also rate any of the blogs to let us how useful you find the content. This is new functionality indicated by the stars below.