Generating Software Usage Report Entries

Software usage monitoring report entries can be generated using the following methods:

• A command line interface

• Shell scripts

• An embedded application

  Each method uses the same basic software usage components; however, the methods access the components differently. The following sections describe each method and the procedures used to implement each method.

Using a Command-Line Interface

The command-line interface method is probably the simplest method of implementing software usage monitoring; however, it can also be the most taxing method as it requires you to manually type in each command each time you run software usage monitoring with an application.

How to Monitor Software Usage Using a Command-Line Interface

At the shell prompt, generate a usage report using one of the following swu_rpt command lines.

To create a software usage report entry specifying that the associated program has been installed, use the -i option.

$ swu_rpt -p product-name [-I identifier] [-s server] [-a attr1=val1, attr2=val2,...] \
-i

To create a software usage report entry specifying that the associated program has started, use the -b option.

$ swu_rpt -p product-name [-I identifier] [-s server] [-a attr1=val1, attr2=val2,...]\
 -b

To create a software usage report entry specifying that the associated program has ended, use the -e option.

$ swu_rpt -p product-name [-I identifier] [-s server] [-a attr1=val1, attr2=val2,...] -e

To create software usage report entries specifying a begin and an end entry for the associated program, use the -c option.

$ swu_rpt -p product-name [-I identifier] [-s server] [-a attr1=val1, attr2=val2,...]\ 
-c command

In these commands,

Example of Monitoring Software Usage Using a Command-Line Interface

The following example shows the software usage monitoring command as used from a command line, which starts the FrameMaker program using the command maker, and logs the application using the software usage monitoring swu_rpt command.

$ swu_rpt -p FrameMaker -I 29581 -s sherlock -c maker

In this example, two software usage report entries are created because the -c option was used (the -c option creates a begin and an end entry). The entries look like the following.

Using Shell Scripts

Another method of monitoring software usage is to create a shell script that initiates a program. This method enables you to create a log entry each time a user executes the shell script. A shell script can be modified using one of two methods: you can create a shell script wrapper, or you can modify the script of an existing shell script program. Either method creates a begin and end software usage monitoring log entry.

• Using the shell script wrapper method, you would enter a software usage monitoring command line before and after the program executable command line. For example, you may have a script called "maker" that starts the FrameMaker^TM program. Within this "maker" script, you could add software usage monitoring commands that would "wrap" around the executable portion of the script. By doing this, the software usage monitoring commands are executed when the script is initiated and also when the script ends.

  ---

  Note -

  Using the shell script wrapper method may not be the best option if your command runs in the background. An end record is generated immediately after the command is executed and the time used is not accurate.

  ---

• Using the method of modifying the shell script executable command line, a single command line in the script starts the specified program, and also creates a begin and end software usage monitoring log entry.

  The following procedures describe how to implement each software usage monitoring shell script method.

How to Monitor Software Usage Using a Shell Script Wrapper

1. Using the editor of your choice, open the shell script to which you wish to add the software usage monitoring commands.

2. Before the program executable command line in the script, add the following swu_rpt command line.

   swu_rpt -p product name [-I identifier] [-s server] [-a attr1=val1, attr2=val2,...] -b

   In this command,

   -p product-name	Indicates the name of the product that software usage is being recorded for; this option must always be included.
   -I identifier	Specifies a unique, alpha numeric identifier for usage records; swu_rpt will provide its own identifier if one is not specified.
   -s server	Specifies the server to which the usage records are to be sent. The default is the host aliased to swusage_host.
   -a attr1=val1, attr2=val2,...	Allows the user to give the software usage entry unique or more descriptive information.
   -b	Indicates that a begin entry should be recorded.

3. After the program executable in the script, add the following swu_rpt command.

   swu_rpt -p product-name [-I identifier] [-s server] [-a attr1=val1, attr2=val2,...] -e

   In this command,

   -p product-name	Indicates the name of the product that software usage is being recorded for; this option must always be included.
   -I identifier	Specifies a unique, numerical identifier for usage records; swu_rpt will provide its own identifier if one is not specified.
   -s server	Specifies the server to which the usage records are to be sent. The default is the host aliased to swusage_host.
   -a attr1=val1, attr2=val2,...	Allows the user to give the software usage entry unique or more descriptive information.
   -e	Indicates that an end entry should be recorded.

4. Exit the script, saving your changes. Verify that the script is executable.

Example of Monitoring Software Usage Using a Shell Script Wrapper

The following example shows the software usage monitoring commands added to a shell script called dir_script that lists the directory in which it was called, the files in the directory, and the current date and time.

swu_rpt -p dir_script -I 295833 -s sherlock -a \
"Command1=pwd,Command2=ls,Options=-la,Command3=date" -b
pwd
ls -la
date
swu_rpt -p dir_script -I 295833 -s sherlock -a \
"Command1=pwd,Command2=ls,Command3=date" -e 

In this example, two software usage report entries are created and look like the following.

How to Add Software Usage Monitoring to a Shell Script Program Executable Command Line

1. Using the editor of your choice, open the shell script to which you wish to add the software usage monitoring commands.

2. Locate the command line in the script that calls the program.

3. Add the following arguments to the program executable command line.

   swu_rpt -p product-name [-I identifier] [-s server] [-a attr1=val1, attr2=val2,...] -ccommand

   In this command,

   -p product-name	Indicates the name of the product that software usage is being recorded for; this option must always be included.
   -I identifier	Specifies a unique, numerical identifier for usage records; swu_rpt will provide its own identifier if one is not specified.
   -s server	Specifies the server to which the usage records are to be sent. The default is the host aliased to swusage_host.
   -a attr1=val1, attr2=val2,...	Allows the user to give the software usage entry unique or more descriptive information.
   -c command	Specifies the program executable command.

4. Exit the script, saving your changes. Verify that it is executable.

Example of Adding Software Usage Monitoring to a Shell Script Program Executable Command Line

The following example shows the software usage monitoring command added to a program executable command line that executes FrameMaker.

swu_rpt -p Frame -I 295836 -s sherlock -a "Command=maker,Version=4.0" -c maker

In this example, the software usage report entry looks like this:

Using an Embedded Application

Software usage monitoring can be implemented by embedding calls to the swu_rpt() function into an application. This method works well for monitoring applications that you or others on your computer network have created.

For example, you may have created an online timecard to keep track of time spent on projects; however, you are not sure that it is being used by everyone. Within the online timecard application, you can embed calls to the swu_rpt() function, which then generates usage reports every time the application is executed.

The following procedure provides information about how to embed the software usage monitoring report function within an application.

How to Embed Software Usage Monitoring into Applications

1. Open the application source code file that will contain the software usage monitoring commands.

2. Add the following header file to the application source code.

   #include <swusage.h>

3. Add a swu_rpt() function specifying the begin of the application.

   swu_rpt ("Server_name", "Identifier", SWU_BEGIN, "Product name", avl)

4. Add a swu_rpt() function specifying the end of the application.

   swu_rpt ("Server_name", "Identifier", SWU_END, "Product name", avl)

5. Compile the application source code with one of the following arguments.

   For static linking of the libraries:

   $ ... -I/opt/SUNWswusg/include -L/opt/SUNWswusg/lib -Bstatic -lswusage -lnsl ...

   For dynamic linking of the libraries:

   $ ... -I/opt/SUNWswusg/include -R/opt/SUNWswusg/lib -L/opt/SUNWswusg/lib -lswusage -lnsl ...

Example of Embedding Software Usage Monitoring into Applications

The following example shows an application that includes the software usage monitoring function.

#include <stdio.h>	/* definition of NULL */
#include <swusage.h>	/* swu_rpt() prototype, swusage_alist definition */
#define 	ATTRIBUTE_COUNT 3
 
main()
{
	struct swusage_alist avl[ATTRIBUTE_COUNT];
 
	/*
	 * Define some product specific attribute-value pairs that will
	 * be included in the software usage report records.
	 */
	avl[0].u_attr = "ATTR_1";
	avl[0].u_value = "val_1";
	avl[1].u_attr = "ATTR_2";
	avl[1].u_value = "val_2";
 
	/*
	 * Terminate the attribute list
	 */
	avl[2].u_attr = NULL;
	avl[2].u_value = NULL;
 
	/*
	 * Create a begin record for the application
	 */
	swu_rpt("Server_name", "Identifier", SWU_BEGIN, "My product name", avl);
 
	/*
	 * The application code would go here.
	 */
 
	/*
	 * Create an end record for the application
	 */
	swu_rpt("Server_name", "Identifier",SWU_END, "My product name", avl);
}

In this example, the software usage report entry looks like this: