Chapter 2: Metering Administration Tasks

This chapter explains the tasks required for setting up and maintaining the metering process.

2.1 Overview of Tasks

Your tasks as Administrator are:

Enabling and disabling usage counters and distributing them to the appropriate users.
Creating metering control files with the appropriate security.
Maintaining the metering control file.
Safeguarding the usage counters since they have a direct monetary value.
Monitoring the metering activity, such as the credit levels on usage counters and the transaction logs.

The Metering Administration program enables you to do most of these tasks. You can restrict access to this program by setting a password for it. Use Options on the View menu and go to the Password tab. On Windows NT, Windows 2000, and Windows XP Professional you need to log in with administrator privileges to see the Password tab.

Details of exactly how to do these tasks and which buttons to click are in the Help. You can usually click or in the top right corner of the window and click the item you want help on.

2.2 Enabling, Disabling and Distributing Usage Counters

As Administrator, your tasks are to:

Enable the usage counters. Only you, as Administrator, can do this. You can enable multiple usage counters at the same time by connecting them and plugging them into the back of your PC.
Distribute the enabled usage counters to the authorized users so that they can meter code against the usage counters.
Do not give usage counters to all the users. They do not need a usage counter to process code that has already been metered.
When the necessary code has been metered for the time being, collect the usage counters.

Use Usage Counters to display the information on the usage counters currently attached to your PC. You can then select the ones you want and click Enable or Disable as appropriate. Figure 2-1 shows a sample Usage Counter Status window.

Figure 2-1: Usage Counter Status Window

The sample Usage Counter Status window shows:

Four usage counters attached.
The first counter has used up all of its 25,000 lines of credit, and is exhausted.
The second counter has never been used, as can be seen by all of its one million lines of credit still being available. New usage counters are supplied disabled and you need to enable them before you can meter code with them.
The third counter is enabled and has used up some of its two and a half million lines of credit.
The fourth counter is enabled but has less than 5% of its one million lines of credit left and so is nearly exhausted.

Note: If you or the users have problems with a usage counter not being recognized, look up usage counter in the index of the help for suggestions on how to solve this.

2.3 Setting Up and Protecting the Metering Control File

You can use the Metering Administration software without attaching a usage counter, but several features, such as creating new metering control files, will be disabled.

A metering control file records the number of lines metered for each program. You can have as many metering control files as you want, but note that this can lead to problems, as already discussed in the chapter Responsibilities and Decisions. As Administrator, your tasks are to:

Create the metering control file. Use New to do this. You must attach a usage counter to enable this functionality.
Make the metering control file available with read access to any users who need to process metered code. The users need to know where the metering control file is located, so that they can point to it on the network or copy it to an individual PC.
Protect the metering control file so that write access to it is limited and users cannot inadvertently update the file and meter code that might already be metered in another file. You must attach a usage counter to enable this functionality.

Use Security controls to limit write access to the metering control file. Figure 2-2 shows an example of default security controls.

Figure 2-2: Metering Security Controls Window

The example security controls mean:

The metering control file must be held on the computer LJP for it to be writable.
Only a user logged in with the username LJP has write access to this metering control file. Since the file is on a local drive E, LJP is the local username.
The PC requiring write access to this metering control file must map the drive letter E to the path containing the file.
The metering control file must be on the path \tps\samples for the user to have write access to it.

For full details on the security controls, click in the top right corner of the window and click the setting you want help on.

2.4 Maintaining the Metering Control File

As Administrator, you are responsible for maintaining any metering control files you have decided to use, and for ensuring their integrity and validity.

Your tasks are to:

Tell the authorized users which metering control file to use for metering which code, and make sure they understand the importance of using the right file. If they do not, they might inadvertently meter code that has already been metered in another file.
Monitor the progress of metering using Open to view each metering control file in turn.
Merge in any metering control files that you no longer need to keep separate. Use Merge to do this. You must attach a usage counter to enable this functionality. If you no longer want to use a particular metering control file, but want to keep the files for archival purposes, we recommend you disable all write-access to the file in order to prevent accidental metering of new code to this old file.
Restore the metering control file from a backup, if it gets corrupted somehow, such as from a system crash. When you try to open a corrupt metering control file, Metering Administration invites you to restore it and offers you the backup files to choose from. In the meantime, you may not be able to access some of the metered code.
The metering control file is automatically backed up whenever the file changes. There are up to nine backup files, called factory.bd1 through factory.bd9. Since the backup files are held in the same directory as the metering control file that they back up, this backup mechanism is not a substitute for a good backup strategy. Be sure to make regular backups of your metering control files.

You can view the available backup files using Backups on the View menu.

Figure 2-3 shows a sample metering control file. Some summary information on the file is shown at the top of the window, such as the name and location of the file, and the security controls on it, which in the case below show that the file is only readable and not updatable. The text explaining the security status of the metering control file varies according to the settings you apply, as explained above in Setting Up and Protecting the Metering Control File.

The list at the bottom of the window shows information on each metered file, including when each file was last metered and the serial number of the usage counter that was last used.

Figure 2-3: Metering Control File Window

2.5 Safeguarding the Usage Counters

As Administrator, you are responsible for the security of the usage counters.

Your tasks are to:

Limit the number of usage counters you distribute. Don't give them to all the users, as users don't need one to process code that has already been metered.
Make sure that anyone who is responsible for a usage counter is aware of its value, and knows your organization's security arrangements for it.
Ask users to disconnect and secure the usage counters when they have finished metering for the time being.
Lock away usage counters when they are not in use.
If you do not expect to use the usage counters for some time, collect them from the users.

The metering control file cannot be updated without an enabled usage counter, so disconnecting or disabling all usage counters also protects the file.

2.6 Monitoring and Reporting on the Metering Activity

As Administrator, you are responsible for monitoring the metering activity. You can display the metering transaction log and view the state of the usage counters. In addition, you can view the metering control files and produce reports on them in several formats.

2.6.1 Displaying the Transaction Log

Use Transaction log to display the metering transaction log.

The Transaction log is usually called factory.aud and its default directory is the same as the metering control file's directory. It contains a history of metering transactions. Whenever someone meters some code, a record is made of the number of lines of code in each file that were metered, when they were metered, and against which usage counter.

The transaction log can cover any range of activity you require, such as one transaction log for each metering control file, or one for each user.

The format of the transaction log is:

Metered file
Lines in file
Product
File type
Transaction Date (YYYYMMDD HH:MM:SS)
Project
User
New lines
Usage counter

For example:

ORDER.CBL,509,TPS,COBOL,20020204
11:43:17,ORDER.PRJ,LJP,509,56

2.6.2 Displaying the Usage Counter Window

Use Usage Counters to display the Usage Counter Window.

This displays information on all usage counters currently attached to your PC. From here you can monitor the status and the credit levels on the usage counters. Look up status in the index of the help for the meaning of each usage counter status.

2.6.3 Displaying the Metering Control File

You can direct Metering Administration to open and display the most recently used metering control file on startup by clicking on Open the most recent file when starting the software which is in the Options dialog on the View menu. Without this option, no metering information is displayed on startup and you have to open the metering control file for yourself. The metering control file is called factory.bdb.

The metering control file keeps a record of the total lines metered for each program file. Note that the lines metered might exceed the lines charged to the usage counter, since you can charge some lines to one counter and some to another.

2.6.4 Reporting on the Metering Control File

Use Report to produce a metering report from the currently open metering control file.

The metering report can be produced in several formats. By default it is called Factory.xxx where the file extension .xxx depends on the file type of the report you produce, and it is usually held in the same directory as the metering control file.

There are several report file types to choose from, depending on how you want to process the report:

HTML with tables
Use this to view the report with a Web browser that supports tables. One table per HTML page will be displayed, with summary information included.
Multi-page HTML with tables
As above and if your metering control file contains records for more than 5000 metered files, the tables will automatically be split after each increment of 5000 files, and an index page will be generated.

We recommend this format for very large (over 15,000 files metered) metering control files.
Preformatted HTML
Use this to view the report with a web browser that does not support tables.
Multi-page preformatted HTML
As above and if your metering control file contains records for more than 5000 metered files, the page will automatically be split after each increment of 5000 files, and an index page will be generated.
Variable-width text
Use this option for printers and text editors such as Notepad.
Multi-file variable-width text
As above and if your metering control file contains records for more than 5000 metered files, the file will automatically be split after each increment of 5000 files, and an index file will be generated.
80-column text
Use this option for 80 column printers and text editors such as Notepad. The format of this information is the same as that for Text, except that First metered and Last lines metered are omitted, and other columns may be truncated to make the information fit on the page.
Comma-separated values
Use this if you want to import the report into your preferred reporting tool, such as Excel or Access. You can optionally launch the target application if you check Open report after saving in the reports dialog.

The format of the metering report file is:

Filename
Total lines metered
Product
File type
First metered (YYYY/MM/DD HH:MM:SS)
Last metered (YYYY/MM/DD HH:MM:SS)
Last project
Last user
Last lines metered
Last usage counter

For example:
```
ORDER.CBL,509,TPS,COBOL,2002/02/04
11:43:17,2002/02/01 11:43:17,ORDER.PRJ,LJP,509,56
```
Multi-file comma-separated values
As above and if your metering control file contains records for more than 5000 metered files, the file will automatically be split after each increment of 5000 files, and an index file will be generated.
XML document
Use this if you want to import the report into an application that can read XML documents. You can also view the XML document in a Web Browser. If your Web Browser also supports XSL, then you can use XSL to format the XML document. An example XSL file is supplied with Metering Administration.

You can choose the report type by keying the filename and extension directly, by selecting the appropriate extension or by choosing the report format. You sort the report by selecting an option from the Sort field drop-down list, and choosing either the Ascending or Descending radio button.