TOOLBOX
Administrator and User Guide

1. INTRODUCTION

1.1 Overview

• Find files.
• Find text.
• Check links (hyperlinks) in files.
• Show files in hex form.
• Edit files.
• 'Obfuscate' files.
• Rename directories and files.
• Delete files.
• Tidy directories.

1.2 Contents

    1. INTRODUCTION
       1.1 Overview
       1.2 Contents
       1.3 Document References
       1.4 Document Control
       1.5 Terms and Terminology
       1.6 Copyright
    2. TOOLBOX: INTRODUCTION AND OVERVIEW
    3. TOOLBOX: USER GUIDE
       3.1 Introduction
       3.2 Invocation and Arguments
       3.3 Action: Find files
       3.4 Action: Find text
       3.5 Action: Check links (hyperlinks) in files
       3.6 Action: Show file in hex form
       3.7 Action: Edit files
       3.8 Action: 'Obfuscate' files
       3.9 Action: Rename directories and files
       3.10 Action: Delete files
       3.11 Action: Tidy directories
    4. TOOLBOX: ADMINISTRATOR GUIDE
       4.1 Introduction
       4.2 Product Distribution & Contents
       4.3 Installing and Configuring Toolbox
       4.4 The Perl Script
       4.5 Restrictions and Deficiencies
       4.6 Test Status
       4.7 Errors and Diagnostics

1.3 Document References

  [1] Learning Perl (2nd Edition), Schwartz & Christiansen, O'Reilly & Associates, Inc.
  [2] Perl Cookbook, Christiansen & Torkington, O'Reilly & Associates, Inc.

1.4 Document Control

• Version 1.0. First formal release.
• Version 0.1. Draft versions.

1.5 Terms and Terminology

1.6 Copyright

The script may or may not be provided in source code form. This source code is the intellectual property of Beaumont Systems Ltd., and, as such, is subject to copyright and legal protection. It may not be copied or redistributed, in whole or in part, without the express permission of Beaumont Systems Ltd.

2. TOOLBOX: INTRODUCTION AND OVERVIEW

3. TOOLBOX: USER GUIDE

3.1 Introduction

3.1.1 Primary Functions

In essence, Toolbox is a set of tools that the author has developed for his own use, and across a range of operating systems. Toolbox simplifies and automates the tasks, and provides a portable solution.
It should be noted that some functions can be performed via other means, that is, by use of native tools. However, not all tasks can be performed via native tools, some tasks may involve the use of more than one tool (and the use of pipes), and some tasks may require use of non-intuitive arguments.

3.1.2 General Properties

• (Code) Written in Perl 5.
• (Code) Makes use of existing public modules, where appropriate.
• (Code) Assumes default parameters, where appropriate.
• (Code) Takes command-line arguments, allowing variation in operation and parameter values.
• Code) Employs techniques and optimisations taken from the books Learning Perl, Perl Cookbook and the Perl newsgroup comp.lang.perl.misc.
• (Code) Structured, and employs nested functions.
• (Code) Records activities and events in log file.
• (Code/Documentation) Code fully commented.
• (Documentation) Fully documented.
• (Testing) Tested using -w and 'use strict'.
• (Testing) Tested under Unix (Solaris 7.x, UnixWare 7.0.x), Windows NT 4, Windows 95 R2, Windows 98.

3.2 Invocation and Arguments

3.2.1 Invocation

• executable (object) form
  This form does not require Perl facilities.
• source form (ie as a Perl script)
  This form requires Perl facilities.

3.2.2 Arguments

The arguments are as follows...

Use Toolbox with no arguments (or -h) to obtain help information.

Upon invocation, Toolbox prompts the user for further parameters, depending on the action selected. See the following subsections for further information.

3.3 Action: Find files

3.3.1 General

There are a number of other arguments that may be used in conjunction with -f. See Table 2-1 for a summary.

3.3.2 Inputs

  Root (directory name) [.] ? :
  Size (bytes) ? :

• Some arguments may be provided via the command line, in which case the relevant prompts are skipped.
• Size: The size may be specified with no suffix, or a suffix of K (for kilobytes) or M (for megabytes). For example, 2048, 2K, 3M.

3.3.3 Outputs

• Results of operation.
  Directed to: 'standard output' (STDOUT)

  File: file1.html, size: 8192
  File: file2.txt, size: 9600

3.4 Action: Find text

3.4.1 General

There are a number of other arguments that may be used in conjunction with -g. See Table 2-1 for a summary.

3.4.2 Inputs

  Root (directory name) [.] ? :
  String (to be found) ? :

• Some arguments may be provided via the command line, in which case the relevant prompts are skipped.

3.4.3 Outputs

• Results of operation.
  Directed to: 'standard output' (STDOUT)

3.5 Action: Check links (hyperlinks) in files

3.5.1 General

There are a number of other arguments that may be used in conjunction with -l. See Table 2-1 for a summary.
Use -lo to specify/restrict the extent of checking, ie to list links (without verification), check some links only (local files) or check all links.
Use -lg to report good links (as well as bad).
Use -lt ttt to alter the timeout value.
Use -xr to restart the log file.

3.5.2 Inputs

  URL/local directory/local filename ? :

• Some arguments may be provided via the command line, in which case the relevant prompts are skipped.
• The response may take one of two forms:
  • a local directory name (...Toolbox checks all files in/below this directory)
  • a local filename
  (Please note: This program checks links in LOCAL files (web pages) ONLY. It does not check remote web pages. Therefore, although the prompt suggests that a URL may be given in response, such a response is ignored. Use WEBTOOL to check remote web pages).

3.5.3 Outputs

• Results of operation.
  Directed to: 'standard output' (STDOUT) if -v used; log file, tb.log

  --------------------
  TOOLBOX started. Wed Sep 15 23:38:56 1999.
  Filename: /usr/arf/web/html/andyf/aflinks.html, # links: 46
    Link: tagtype=a, name=href, value=http://cm.bell-labs.com/cm/cs/who/dmr/st.html.
    Link: tagtype=a, name=href, value=http://playground.sun.com/pub/ipng/html/INET-IPng-Paper.html.
    Link: tagtype=a, name=href, value=http://www.nexor.co.uk/public/rfc/index/rfc.html.
    Link: tagtype=a, name=href, value=http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html.
    Link: tagtype=a, name=href, value=http://www.hwg.org/resources/html/index.html.
    Link: tagtype=a, name=href, value=http://WWW.Stars.com/Authoring/HTML/. (Full URL: http://www.stars.com/Authoring/HTML/).
    Link: tagtype=a, name=href, value=http://www.gamelan.com/.
    Link: tagtype=a, name=href, value=http://www.cgi-resources.com/.
    Link: tagtype=a, name=href, value=http://www.perl.com/.
    Link: tagtype=a, name=href, value=http://www.iconbazaar.com/.
    Link: tagtype=a, name=href, value=http://www.clipart.co.uk/.
    Link: tagtype=a, name=href, value=http://www.econ.cbs.dk/~gemal/urlheaven/index.html.
    Link: tagtype=a, name=href, value=http://www.data.com/.
    Link: tagtype=a, name=href, value=http://www.byte.com/.

  --------------------
  TOOLBOX started. Thu Sep 16 11:11:57 1999.
  Filename: /usr/arf/web/html/beausys.html, # links: 9
    Link: tagtype=a, name=href, value=http://members.netscapeonline.co.uk/beaumontsystems/products/uwipnifss.html.
      ERROR: Problem accessing http://members.netscapeonline.co.uk/beaumontsystems/products/uwipnifss.html, response code=404, message=Not Found
    Link: tagtype=a, name=href, value=http://members.netscapeonline.co.uk/beaumontsystems/products/netdbov.html.
      ERROR: Problem accessing http://members.netscapeonline.co.uk/beaumontsystems/products/netdbov.html, response code=404, message=Not Found

3.5.4 Notes

If you anticipate a large number of links, you may prefer to run Toolbox during a less busy period (perhaps overnight).

3.6 Action: Show file in hex form

3.6.1 General

There are a number of other arguments that may be used in conjunction with -s. See Table 2-1 for a summary.
Use -so xxx to select an initial offset. (Default=0, the start of the file).
Use -sh to display the current offset in hex. (Default=decimal).
Use -sw xxx to select the width (block size per line), in octets. (Default=16).
Use -sr to select 'raw' mode (show hex only, no offset and no ASCII).
Use -xf to specify the filename. If not, Toolbox will prompt you for it.
Use -xr to restart the log file.

3.6.2 Inputs

  Filename ? :
  Filename (output) ? :

3.6.3 Outputs

• File in hex form.
  Directed to: output file, if output filename specified; 'standard output' (STDOUT), if output filename not specified

  00000: 6d792024 61203d20 2731273b 0d0a0d0a    my $a = '1';....
  00016: 7072696e 74202224 615c6e22 3b0d0a24    print "$a\n";..$
  00032: 61202e3d 20273227 3b0d0a70 72696e74    a .= '2';..print
  00048: 20222461 5c6e223b 0d0a2461 202e3d20     "$a\n";..$a .= 
  00064: 2733273b 0d0a7072 696e7420 2224615c    '3';..print "$a\
  00080: 6e223b0d 0a246120 2e3d2027 2034273b    n";..$a .= ' 4';
  00096: 0d0a7072 696e7420 2224615c 6e223b0d    ..print "$a\n";.
  00112: 0a                                     .

• The left-hand column shows the offset of the first octet (of the current block) within the file.
  The offset may be in decimal (default) or hexadecimal.
• The middle columns show the current block in hex form, with a space after each group of 4 octets (8 quartets).
• The right-hand column shows the current block in ASCII form, with non-printable characters being represented as a '.'.

3.7 Action: Edit files

3.7.1 General

There are a number of other arguments that may be used in conjunction with -e. See Table 2-1 for a summary.

This function is particularily useful for maintaining links in a collection of web pages (HTML documents).

3.6.2 Inputs

  Root (directory name) [.] ? :
  String (to be found/replaced) ? :
  String (new) ? :

3.7.3 Outputs

• Results of operation.
  Directed to: 'standard output' (STDOUT) if -v used; log file, tb.log

3.8 Action: 'Obfuscate' files

3.8.1 General

There are a number of other arguments that may be used in conjunction with -o. See Table 2-1 for a summary.
Use -xf to specify the filename. If not, Toolbox will prompt you for it.

3.8.2 Inputs

  Filename ? :
  Filename (output) ? :

3.8.3 Outputs

• File in 'obfuscated' form.
  Directed to: output file

3.9 Action: Rename directories and files

3.9.1 General

There are a number of other arguments that may be used in conjunction with -r. See Table 2-1 for a summary.

3.9.2 Inputs

  Root (directory name) [.] ? :

3.9.3 Outputs

• Results of operation.
  Directed to: 'standard output' (STDOUT) if -v used; log file, tb.log

  Directory /usr/AndyF: renaming as /usr/andyf
  File /usr/john/SUMMARY.TXT: renaming as /usr/john/summary.txt

3.10 Action: Delete files

3.10.1 General

There are a number of other arguments that may be used in conjunction with -d. See Table 2-1 for a summary.
Use -xf to specify the filename. If not, Toolbox will prompt you for it.

3.10.2 Inputs

  Root (directory name) [.] ? :
  Filename ? :

3.10.3 Outputs

3.11 Action: Tidy directories

3.11.1 General

There are a number of other arguments that may be used in conjunction with -t. See Table 2-1 for a summary.
Use -xd xxx to specify the name of the directory to be tidied.
Use -xf xxx to provide parameters in an input file (rather than interactively).

3.11.2 Inputs

  Directory name ? :
  Match expression ? :

3.11.3 Outputs

• Results of operation.
  Directed to: 'standard output' (STDOUT) if -v used; log file, tb.log

--------------------
TOOLBOX started. Sat Dec 11 13:26:56 1999.
Action: 8. (Simulated)
Input file: test.dat.
Tidying directory: C:/Windows/Recent. Expression: *.htm.lnk
  Deleting object (file): C:/Windows/Recent/apolog.txt.lnk
  Deleting object (file): C:/Windows/Recent/index.html.lnk
  Deleting object (file): C:/Windows/Recent/tbov.html.lnk
  Deleting object (file): C:/Windows/Recent/tb.html.lnk
  Deleting object (file): C:/Windows/Recent/afcv4p.html.lnk
  Deleting object (file): C:/Windows/Recent/wtb.html.lnk
  Deleting object (file): C:/Windows/Recent/beausys.htm.lnk
  Deleting object (file): C:/Windows/Recent/wtbov.html.lnk
  Deleting object (file): C:/Windows/Recent/Test.dat.lnk
  Deleting object (file): C:/Windows/Recent/tb.log.lnk
Tidying directory: C:/Windows/Temporary Internet Files/Content.IE5. Expression: *
  Deleting object (file): C:/Windows/Temporary Internet Files/Content.IE5/index.dat
  Deleting object (file): C:/Windows/Temporary Internet Files/Content.IE5/desktop.ini
  Deleting object (directory): C:/Windows/Temporary Internet Files/Content.IE5/MRTZG5LA
  Deleting object (directory): C:/Windows/Temporary Internet Files/Content.IE5/X9371GUP
  Deleting object (directory): C:/Windows/Temporary Internet Files/Content.IE5/ID688HK0
  Deleting object (directory): C:/Windows/Temporary Internet Files/Content.IE5/4B8RAJMZ
  Deleting object (file): C:/Windows/Temporary Internet Files/Content.IE5/tb.log

3.11.4 Notes

• Invoke Toolbox without -xd or -xf and provide the parameters interactively.
• Use -xd to provide the directory name via an argument and provide the match expression interactively.
• Use -xf to provide both parameters in an input file.

• Comment lines (beginning with a #) are allowed and ignored.
• Blank lines are allowed and ignored.
• Parameter lines takes the form:

      directory_name;match_expression_1;match_expression_2
      

4. TOOLBOX: ADMINISTRATOR GUIDE

4.1 Introduction

4.2 Product Distribution & Contents

4.2.1 Distribution Form

• tb.zip - suitable for Win32 platforms (Win95/98/NT)
• tb.tar - suitable for Unix platforms

4.2.2 Distribution Contents

• Code
  (Executable Perl script)
• Documentation file
  (Administrator and User Guide [this document])

4.2.3 File List

4.3 Installing and Configuring Toolbox

4.3.1 Prerequisites

• System with networking facilities (...required for some functions)
• System with Perl facilities (Perl 5)
• The following Perl packages/libraries/modules: HTML, LWP ("Library for WWW access in Perl")

• First, check the operating system installation CD(s). Some operating systems come with a Perl package on the installation CD, and this generally has to be installed explicitly. (This is particularily true for Unix).
• Next, check if the company that produces the operating system provides any add-on packages upon request, whether these include a Perl package and how they make this available (on CD and by post ? downloadeable from a website ?)
• Next, check the Internet for other possible sources of Perl package for your system. Perl packages are available for a wide variety of platforms, and for free, on the Internet.
  (This includes the excellent ActivePerl Perl for Win32 from ActiveState Tool Corp).
• Finally, if all else fails, you can obtain the Perl source code from an Internet site (eg CPAN) and compile and build it for your particular system.
  (Note: there are numerous Perl ports available, so it is unlikely that you will need to resort to this).

4.4 The Perl Script

4.4.1 Organisation

• Header comments
• 'use' statements
• Data object definitions
  • Constants
  • Variables
• Main routine
• Subroutines

4.4.2 Perl Features

• eval
• Single and double quoted strings.
• Arrays.
• Private (lexical) variables.
• Subroutines (functions), with arguments and return values.
• String manipulation (regular expressions, pattern matching, substitution and substring manipulation).
• Filehandles.
• File input/output.
• Checking of return values from system calls.

• Document reference [1]
• Document reference [2]
• The Perl Usenet newsgroup, comp.lang.perl.misc

4.5 Restrictions and Deficiencies

1. Perl version: Toolbox was written using Perl 5 (Perl Release 5, 5.000 onwards).
   It has not been tested on earlier (ie pre- Release 5) Perl systems, and so may or may not work on such systems.

4.6 Test Status

Toolbox has been tested on the following platforms:

• (SCO) UnixWare 7.0.1 + Perl (Perl version 5.004_04)
• (SCO) UnixWare 2.1.3 + Perl (Perl version 5.004_04)
• Windows 95 (R2) + ActiveState's ActivePerl Perl for Win32 (Build 522, Nov 1999, Perl version 5.005_03)
• (Sun Microsystems) Solaris 7 + Perl (Perl version 5.005_02)

4.7 Errors and Diagnostics

• Problem: cannot execute script
  • Check where the Perl interpreter resides on your system, and that the first line in the Toolbox script (...which takes the form #!/usr/bin/perl...) contains the correct path.
    (Note: that this may vary from machine to machine).
  • Check that the Toolbox script can be executed, ie has execute permissions.
    (Note: Under UNIX, you may need to do chmod +x tb.pl).
• Problem: Toolbox does not generate a log file (when using -l)
  • Check that Toolbox can write to the directory for the log file and the log file itself, ie that these have appropriate write permissions.