Tailoring reports

Prior to tailoring any reports, please note the following:

This means that any changes to the shipped parameter file, including changes to a parameter (for example, pagelength) will demand a local version.

Setting up a local MIS area

The best practice is to mimic the MIS directory structure below a directory of your choice. Local versions of MIS would have a natural home under users/report in a new directory called mis. Using this example, below /users/report/mis would be a directory called param and a further sub-directory for each script which requires local tailoring.

The following instructions describe how to set-up a local MIS area for a local format.pl for Overdue Letters (i.e. the script loa_odue_letter).

To set up a local MIS area

  1. Log on as the user report.

  2. Change directory:

    cd /users/report

  3. Create a directory called mis. This is a once-only operation when first setting up your permanent local MIS area:

    mkdir mis

  4. Change directory to /users/report/mis

    cd mis

  5. Create a directory called param. This is a once-only operation the first time the local area is created.

    mkdir param

  6. In the directory /users/report/mis create a directory for the script in question, for example:

    mkdir loa_odue_letter

  7. Change directory to /users/report/mis/param:

    cd param

  8. Copy the master parameter file to your local area. For example:

    cp $TALIS_HOME/mis/param/loa_odue_letter .

    Note that the final full stop is part of the command. It stipulates that the target files should be copied to the current directory with the same names.

  9. Change directory to the loa_odue_letter directory:

    cd /users/report/mis/loa_odue_letter

  10. Copy the source code files that require local amendment. For example:

    cp $TALIS_HOME/mis/loa_odue_letter/*.pl .

  11. Amend the parameter file so that it picks up the local version(s) of the source code. For example:

    vi /users/report/mis/param/loa_odue_letter

    In particular, set the new location of your local files. For example:

    format = /users/report/mis/loa_odue_letter/format.pl

    Repeat this for all files (i.e. preselect.pl, main.pl, retrieve.pl and select.pl).

  12. Set the environment variable $LOCAL_MIS_HOME to point at the local area. For example:

    LOCAL_MIS_HOME=/users/report/mis; export LOCAL_MIS_HOME

    If this is a permanent area designated for local MIS then the above two commands are best added to the .profiles for the talis and report users.

  13. Amend your format.pl to cater for local requirements. For example:

    cd /users/report/mis/loa_odue_letter
    vi format.pl
     

Documenting and maintaining local amendments

Before making any amendments it is important to consider how you will document and maintain your local versions. When Capita ships amended software for existing reports (for example fixes to known problems) any local amendments will, in most instances, have to be re-introduced to new copies of the shipped.pls.

The best method of documentation is to add lines of comments in the top of the file after the existing comments:

 

# Local changes are as follows:
--------------------------------------------------------------------------------
# Local changes are as follows:
#
#   Amended text in the footer and removed the fourth line of
#   borrower's address
#   Pete Smith  12/09/03
#
#   Commented out borrower's address and replaced with Dept.
#    Jane Smith   12/05/04
 

For changes to retrieve.pl (and similar files containing source code) you are advised to comment in the header as described and to comment in the body of the file too. For example:

# Get the borrower's department.   Local change  added 10/10/03
# KDG.
($Department) = &sql($d,"
select DEPARTMENT_ID                                                   
from BORROWER                                                          
where BORROWER_ID = $borrowerID                                        
");