The CARS+ Report Driver logic is used to run CARS+ reports from the Unix scheduler (cron) and be able to pass specific parameters to the report program such as start/end dates, location(s), and what should be done with the output (send to printer, to file, to email, etc.).

Note: This documentation is provided for stand-alone clients. CARS+Internet clients should contact Thermeon Customer Support to request that programs be set up to run automatically via the report driver.

Program Compatibility

Not all CARS+ reports are able to be run via the report driver. The list of compatible programs is maintained in the manual chapter Print Auto Create Reports. Alternatively, compatibility may be determined by doing a "what" on the program file. In order to be compatible, the program file must contain the following copy files:

For example, in order to determine the compatibility of the Drawer Balance Report, the commands would be:

what DRWBAL.obj | grep DRIVER2.CWS
what DRWBAK.obj | grep RETRIEVE.CPL

CARS+ Setup

The Configuration File

The report driver uses a configuration file to store the parameters by which the report should be run. The configuration consists file of the following items, and should be entered in the order shown:

  1. LOCATION location_code

    This will set the default location. The location setting will remain effective until changed.

  2. Numbered lines which will set the value for the associated field on the screen. Only those field which need to be changed from the default setting need be specified. These fields will be reset after each program is run (see "RUN" below).

    For RealWorld programs, the default setting is the value that displays when F1 is pressed. For example, if when running the program interactively, the program says "Press F1 for "All" or "Press F1 for "First", then that will be the setting of that field if it is not specified in the config file.

  3. For reports that require selection of the Options to be reported (currently that is the Revenue Analysis, Extra Revenue Report, Extra Rev2 and Employee Performance report) the following unique instructions apply:

    1. Create a separate line in the configuration file for each option to be reported. These lines must have a field number, even though there is no field number on the screen.

    2. The field number for the first option should be one higher than the highest field number on the screen. For example, the last numbered field on the Extra Revenue Report is field 10, therefore the four options would appear in the config file as "fields" 11, 12, 13 and 14 (one Option Code or Literal per number).

    3. For the selections which group several options together, such as "All L Types", enter that literal text into the configuration file exactly as seen on the screen, including the use of upper and lower case.

    4. If less than the maximum number of selections are to be reported, it is not necessary to place "blank" fields in the configuration file. The report driver logic will first erase all of the default selections and then apply only those found in the configuration file.

    See example configuration file for the Extra Revenue 2 Report under "Running the Program" below.

  4. PRINTER printer_name

    This specifies what is to be done with the output from the program. It can be a pipe to any valid device name, print queue, or other Unix command or shell script. It can also direct the output to a file (pipe not needed in this case).

  5. RUN program_name

    Name of the program to be run. Note that this is the name of the cobol program, not the menu synonym.

When running RealWorld A/R programs, note that:

Example: To run the A/R Detail Aging Report, the "RUN" line will be: RUN AROBJ/AGESCN

NOTE: Beginning with release 12.9-1204xx, the maximum length of the configuration file name has been expanded to 60 characters (previously it was 30 characters).

Running the Program

The CARSRPTCFG environment variable must be set before calling the report driver. This environment variable specifies where to find the configuration file.

The report driver program is run using the "-u employee_code" option of the carsgo startup script. The "employee_code" must math the employee used for the User Access record set up for the report driver. The User Access record and the corresponding Terminal Record will supply the report driver with the company number to use as well as default settings for location, drawer and printer. Settings for location and printer can be overridden the the configuration file. An example startup command might be:

CARSRPTCFG=/usr/carsplus/drwbal.cfg
export CARSRPTCFG
carsgo -iD /usr/carsplus -u REPORT


Typically a shell script is used to create the configuration file and run the program. One of the advantages to using a shell script is that the shell script can had additional related tasks such as:

A sample script which runs the Vehicle Status Report and places the output in a directory for later printing using the Print Auto Create Reports program is shown below:

#! /bin/bash

# set -x

RUN_DATE=`date +%m%d`

CLIENT=demo
LOC=TUS

# Make directory for reports

mkdir /var/c+i/cust/$CLIENT/rpt/$LOC

# Set up to run the Vehicle Status Report

CARSRPTCFG=/home/$CLIENT/bin/vst-rpt.cfg
export CARSRPTCFG

echo "LOCATION $LOC" >> $CARSRPTCFG
echo "4 ALL" >> $CARSRPTCFG
echo "PRINTER rpt/$LOC/VEHSTAT-RPT.$RUN_DATE" >> $CARSRPTCFG
echo "RUN VEHSTA" >> $CARSRPTCFG 
carsgo -iD/var/c+i/cust/$CLIENT -uREPORT
rm $CARSRPTCFG

Example configuration for running the Extra Revenue 2 Report showing how to select option to be reported. Note that for this program, up to six options may be selected and the highest numbered field on the report screen is field 15. This means the the first "option field" in the configuration file is field 16.

echo "LOCATION $LOC" >> $CARSRPTCFG
echo "1 $START_DATE" >> $CARSRPTCFG
echo "2 $END_DATE" >> $CARSRPTCFG
echo "3 ALL" >> $CARSRPTCFG
echo "4 C" >> $CARSRPTCFG
echo "5 N" >> $CARSRPTCFG
echo "16 Prepaid Fuel" >> $CARSRPTCFG
echo "17 All Cvgs" >> $CARSRPTCFG
echo "18 AGE24" >> $CARSRPTCFG
echo "19 BABY" >> $CARSRPTCFG
echo "20 DRIVR" >> $CARSRPTCFG
echo "21 UP" >> $CARSRPTCFG
echo "PRINTER rpt/$LOC/EXTRA-REV2.$RPT_DATE" >> $CARSRPTCFG
echo "RUN PRFRM1" >> $CARSRPTCFG
carsgo -iD/var/c+i/cust/$CLIENT -uREPORT
rm $CARSRPTCFG

Getting Dates

One of the more complex tasks when using the report driver can be getting the desired start and end dates for running the report. Typical scenarios can be:

Key to making this work properly is understanding how to use the Unix "date" command in the shell script. On Linux systems, the date command accepts the "-d" option which then allows a text string such as "yesterday" or "5 days ago" to be specified. As an example, to run a report every Monday for the previous week (the preceding Monday through Sunday), the shell script would use the date command as shown below to set the appropriate dates into environment variables which would then be used in the configuration file, as shown below:

START_DATE=`date -d '8 days ago' +%m%d%y`
END_DATE=`date -d 'yesterday' +%m%d%y`

CARSRPTCFG=/home/$CLIENT/bin/xyz-rpt.cfg
export CARSRPTCFG

echo "1 $START_DATE" >> $CARSRPTCFG
echo "2 $END_DATE" >> $CARSRPTCFG

Note that the above example uses the American date format (mm-dd-yy). The date will need to be formatted as appropriate for the specific CARS+ installation.

On some systems the "-d" option to the "date" command may not be available. If this is the case, Thermeon Customer Support can provide a shell script called "getdate.sh" which can, for the most part, do the same thing.

One thing that the "-d" option to the "date" command cannot easily do is get the start and end dates for "last month". Thermeon Customer Support can provide a shell script called "lastmonth.sh" which will do this. This script properly accounts for they varying number of days in each month as well as for leap years.

Emailing the Output

In it's simplest form, the report output can be emailed as the "body" of an email. This would be specified in the configuration file as:

PRINTER -P mail -s "Some Report" john@xyz.com

Note that "-P" in the example above is equivalent to a "pipe" ( | ).

Generally, when a CARS+ report is sent as the body of an email, formatting becomes an issue. For this reason, it is generally advisable to send it as an attachment to an email. This is done by sending the output to a file -- which can either be temporary or left in place for later printing -- and then emailing the file as an attachment. This can be done in the shell script after the the report has been run using the following command:

mutt -a filename -s subject recipient@xyz.com

Note that the above example presumes that the "mutt" program is installed. If it is not available, Thermeon Customer Support can provide a template for using the shell script to create a properly formatted multi-part MIME mail message with attachment(s).

Printing the Output Using Print Auto Create Reports

The Print Auto Create Reports program was designed to print reports generated by program run from the report driver. For example, it may be critical to run a report at a specific time of day which may be after hours. By using the report driver, the data can be collected and the report generated and waiting to be printed at someone's convenience the next business day.

For this purpose, the reports should be placed in a location-specific directory under a directory named "rpt" which is located in the base directory of the CARS+ installation. The Print Auto Create Reports program will display a list of files located in a directory under $base_dir/rpt whose name matches the user's default (pass) location. For example, assume the following:

The Print Auto Create Reports program will display a list of files in the directory

/usr/carsplus/rpt/TUS

and allow the user to select a file and print it. Therefore, the "PRINTER" statement in the report driver configuration file should direct the program output to this directory. Often these reports are run once per day. If the file name does not vary each time the report is run, then the file will be overwritten on each run with the current data. If it is desirable to preserve some history (for example, if no one will be printing the reports over the weekend), then the file name should vary with each run. A common way to do this is to incorporate the run date into the file name. For example, the PRINTER statement might read as follows:

PRINTER /usr/carsplus/rpt/TUS/MY-REPORT-`date +%y%m%d`.TXT

User tip: The Print Auto Create Reports program does not provide a means to delete files once they are printed. The program also has a limit of 240 files which it can display. Once the number is exceed, the user will receive a message "Too Many Files to Display". Therefore, it is advisable to create a cron job which purges this directory after the files are no longer needed. For example, to purge all files older than 30 days, the command would be:

find /usr/carsplus/rpt -depth -mtime +30 -print | xargs rm -f

Note that the command in the form shown above will act on all subdirectories under the specified directory (/usr/carsplus/rpt).

Notes:

  1. The output can be piped to carsplus-printer commands just as would be set up in the carsconfig or lclconfig file. For example:
    PRINTER -P carsplus-printer -no-use-rano -no-print -ps-header=plain_header.ps
     -landscape -to-email=$RECIPIENTS -subject='Owned Fleet Utilization Report' >> $CARSRPTCFG
  2. There is a limit on the number of characters (approx. 200) which can be used in the PRINTER statement. It can be easy to exceed this when piping outout to carsplus-printer. If it is necessary to exceed the limit, then the carsplus-printer commands should be placed in a shell script and the report driver output piped to the shell script. The shell script can be used to handle other tasks in addition to or in place of the carsplus-printer commands.
  3. A program can be run via the report drive in a semi-interactive manner. For example, data for all locations may be needed from a program which can be run only for one location (or location group) at a time. A shell script can be set up which will read in a user-supplied list of locations and then run multiple iterations of the program for each location. The shell script can be called from a CARS+ Menu.
  4. The shell script which creates the configuration file and runs the report driver can also be used to process the output. For example, a report can be written to a file and then the file can be filtered for just the summary line(s). Then this filtered data can be parsed into segments which can then be turned into a set of comma separated values for easy import into a spreadsheet. An example of this is shown below, where $TMPFILE is the file the output was directed to:
    RAS=`grep ^LOC $TMPFILE | cut -c 17-20`
    DAYS=`grep ^LOC $TMPFILE | cut -c 97-101`
    OPREV=`grep ^LOC $TMPFILE | cut -c 113-121`
    GROSS=`grep ^LOC $TMPFILE | cut -c 123-132`
    echo "$RAS,$DAYS,$OPREV,$GROSS" >> $CSVFILE
    echo "Attached plese find the Optional Revenue Report" | mutt -a $CSVFILE\
     -s "Optional Revenue Report" $RECIPIENTS &