©1995–2012, Fairlight Consulting
PayPal: View Cart PayPal: Add Fairlight fpgsr to cart
fpgsr Documentation

Current Version: v01.01.00

Released: 09/25/12


Program Summary


The Fairlight fpgsr utility is a global search-and-replace tool meant to work specifically with filePro processing tables.  Have you ever needed or wanted to replace a string in every processing table at once?  Do you have dozens, or even hundreds of processing tables to potentially apply changes to?  Have you ever undertaken such a task before and forgotten a table here, a table there, or missed a critical line in one or five tables?


No more pain!  This utility will do a global search and replace on the original string, replacing it with the substitution string.  What’s more, it will make backups of every table it alters, log every change it makes to a single logfile, skip altering binary (encoded/encrypted) processing tables on its own, and make sure the file ownerships are preserved.


PLEASE NOTE:  If your processing tables are not saved with ABE=ASCII in your environment (read: if your processing tables are saved in the encrypted format), this program will not work for you.  It is impossible to decrypt the table format externally from outside filePro.  This utility skips tables which are saved in binary, and reports which tables were skipped for that reason.  It will only perform substitutions on tables which are saved in ASCII format.


System Requirements


Fairlight fpgsr requires Perl 5.6 or higher be installed on your system for *nix variants.  For Windows, the program is a self-contained executable, so there are no requirements.


Supported Platforms


Currently supported platforms are:



Installation


Unix/Linux:  Unpack the compressed tar archive into any directory you choose. A program named fpgsr will be created.  Copy uniclient to somewhere sensible in your path, if you did not extract it to the desired location.  You may need to alter the first line of the program to reflect the location of your perl binary.  Make sure the program is set to mode 0755.


Windows: Use the installer executable.


Usage


fpgsr -f /path/to/filepro -o string -s string [options]


After invoking the program, you will see output that denotes what progress is being made, unless you use the --quiet option.  The progress indicators are single characters as noted below:



Behind the scenes, as each processing table is handled, a backup copy is made within a directory heirarchy in a backup directory within the working directory.  The default directory is /appl/fpgsr_backups, but if /appl does not exist you will need to use the --working-directory option to specify a directory into which the backup directories are placed.  Backup directories take the filename format:  fpgsr_backup_2012_09_25_16:29_761, where the date and time are obvious, and the last number is the process ID of the program when run.  If the --dry-run option is in use, the string _DRYRUN will be appended to the directory name.


The program makes no assumption about the directory to process.  Rather than rely on environment variables (which might be set incorrectly, or which may be set to something you’ve forgotten about) and risk mistaken operations, you need to specify a base directory for your filePro processing tables, using the --fpdir option.  This directory must end in /filepro.


You may instruct the program to exclude specific filePro files (directories).  See the documentation for the --exclude option below.


By default, patterns fed to --origpat and --subpat are interpreted as literal strings unless the option --regex is used.  If that option is not in use, no regular expression syntax is honoured as such.  In fact, regular expressions are specifically denied by default, as it was felt that users would trigger regular expression issues with commonly used characters, such as ‘?’, ‘*’, ‘(‘, “)’, ‘\’, etc.  Whatever you give as patterns are taken literally without the use of --regex.  However, if you do choose to use the --regex option, you have access to full Perl Compatible Regular Expressions (PCREs) for your pattern matching.  This gives you a lot more power if you know how to use regular expressions.  This also introduces an element of risk that you’ll have written your pattern incorrectly.  It is suggested that you use the --dry-run option to test with prior to a full run, if you’re using regular expressions.  Actually, that might be a wise practise even if you aren’t using them.


When the program has finished, you will find a file named LOGFILE.txt within the backup directory for that particular run of the program.  This file notes the patterns provided, every change that was made to every table, which tables were skipped because they were binary encoded, and a concise list of modified tables, as well as some other miscellaneous useful summary information.


NOTE:  While the utility does make its own backup files for processing tables it modifies, you may feel more comfortable making an extra backup of your entire filePro database directory before using the program.  This is technically not necessary, but it is a prudent course of action before running something that may change hundreds of files.  Fairlight Consulting will not be liable for loss of data, or undesirable results.  You assume full responsibility for ensuring you have adequate backups of your files.


Options



This option dictates what directory will be used to store the backup directories containing original processing tables within a replica of the directory heirarchy.  The default is /appl/fpgsr_backups.



This option dictates the pattern to search for and replace.



This option dictates the pattern to substitute in place of the original pattern.



This option dictates which directory contains the filePro file directories ($FPDIR equivalent).  This path must end in “/filepro”.



This option denotes a directory name to skip during processing.  No processing tables within a directory of this name will be modified.  You may specify more than one exclusion by repeating the option/argument pair, changing the argument for each iteration on the command line.



This option enables the use of Perl Compatible Regular Expressions (PCREs) for pattern matching.  Note that only the pattern segment is specified with the --inpat option.  You can use the usual amount of line noise (er...I mean power!) within your patterns.  However, please also note that modifiers are hardwired into the program.  All pattern matching is done case-insensitively, and globally within each line.



This option tells the program to skip the pattern check and confirmation phase when the --regex option is used.  This should only be used by people very familiar with Perl Compatible Regular Expressions (PCREs), and even then it might be wise to skip this option and double-check your work.  Use this option at your own risk.



This option specifies that the program should analyse all files and log what would happen when run normally, but that it should not perform any directory or file modifications.  Only the backup directory and logfile are created when this option is in use.



This option specifies quiet mode.  If just -q is supplied, the progress characters are not generated as the program runs, but the program still notes when it has completed, and shows the path of the logfile.  If -q2 is specified, no output is sent to standard output.



This option designates which user to check against to see if chown operations should be performed.  The user filepro is assumed.  This option is only meant to be use in a test/development environment, as the program is intended to be run either as filepro or root.



This option returns the program version information.



This option returns the program changelog information.



This option returns the program help (a briefer summary of the options) in a self-paging fashion.


Changelog


v01.00.00 - 09/25/12


Original Release.


V01.01.00 - 09/25/12


Added --regex, --expert, and --dry-run options.  Made --fpdir option mandatory.

Copyright, License, Warranty, and Payment


This software remains the property of Fairlight Consulting, and license to use the program is sold to users. Fairlight fpgsr is licensed at a cost of $99.00 USD per server on which it is installed. Each license fee entitles you to use Fairlight fpgsr on one server, in any role you require.


Upon receipt of payment for a license, program will be delivered to the licensee via email at the email address associated with the PayPal payment.


Upgrades for the product are currently free when moving to new minor and major versions. Fairlight Consulting reserves the right to change this policy in the future, with no prior warning.


There is no warranty for this software. This software is offered "AS-IS" and without warranties as to performance or merchantability or any other warranties, whether expressed or implied.


Good computing practice dictates that any program should be thoroughly tested with non-critical data before deploying it for production. The user assumes the entire risk of using the program. In no event shall Fairlight Consulting be held liable for loss of data, failure of performance, or any other damages, be they real or perceived.