ADB -- Parms, DOS Env. Var.s, Return codes, Files

8. Parms, DOS Environmental Variables, Return Codes, and Files.

This section describes ADB's command-line parameters, DOS environmental variables, files and file naming conventions, return codes, and the other miscellaneous information that one might expect to see in a Unix-style man entry.

All of this information has already been presented in other parts of the documentation, and virtually all of it is listed in ADB's on-line cheat sheet.

Feel free to mail your comments to me at: rog@NOSPAM_rs-freeware.org.

Return to the global table of contents
Frames mode, or No frames

1: DOS Environmental Variables

2: Command-line parms (arguments) that are associated with files

3: Command-line parms (arguments) that are NOT associated with files

4: Relationship between data files in the definitions, and those on the command line

5: The special "-OUTDFLT" parm

6: ADB system files

7: ADB return codes and warnings

8: Redundant note on control panel settings

1: DOS Environmental Variables

Only ADBPROJ is required; the rest are optional.)

ADBPROJ

This is your project file suffix. It must be exactly 2 characters in length. The first character must be a letter (an underscore counts as a letter). The second must be a letter, digit, or underscore.

ADBAWKLIB

This is your Awk library file. This is the only file name that doesn't have to end in your project file suffix, although the file name portion (after any path) may not begin with "ADB".

ADBJOBNAME

This is the name of the "job" (i.e. the batch process). This is always echoed into the log file, so it can provide you with valuable debugging assistance. It has no other purpose.

You may also wish to do the following:


SET ADBJOBNAME=%0

This sets the name of the job to the DOS batch file name.

ADBSTEPNAME

This is the name of the step. What you consider to be a "step" is up to you, but as a general rule, this should be set to some value that will clue you into which ADB invocation (execution) is running at a given time.

If a process fails, you'll then know immediately which one it was, just from looking at ADB's log file.

IMPORTANT:

(I already mentioned this in the install section, but I want to make sure it doesn't slip by; errors associated with blowing the DOS environmental size are tricky to spot.)

Always make sure that the following line appears in the C:\Config.Sys file for the computer that's running ADB:


SHELL = C:\COMMAND.COM C:\ /e:4096 /p

(For NT, you need to put this line in ...\SYSTEM32\CONFIG.NT:)


SHELL=%SYSTEMROOT%\SYSTEM32\COMMAND.COM /E:4096

This will ensure that your DOS environment size is large enough to handle not only ADB's variables, but anything else that you want to put there (e.g. globals that you want to pass to your Awk scripts.)

Also, make sure that the following line is in your C:\AutoExec.Bat file:


Set COPYCMD=/Y

This will ensure that DOS doesn't prompt you every time a file is replaced with a newer version.

Return to local table of contents
Return to global table of contents
Frames mode, or No frames

2: Command-line parms (arguments) that are associated with files

Most of ADB's command line parameters are associated with files.

All ADB's parameter names are processed case-INsensitively.

Don't use excess spaces (Unix users beware)

You must follow the parm name immediately with the file name.

E.g., this is wrong:


-MAST mastfile

But this is right:


-MASTmastfile

Data files

Each of the up-to-two input files and up-to-three output files has a command line paramter that's identical to the ADB statement (but which begins with a dash):


Statement:  Parameter:   Meaning:
----------  ----------   --------
MAST        -MAST        Input "master" file
TRANS       -TRANS       Input "transaction" file
M-T         -M-T         Unmatched master records
T-M         -T-M         Unmatched transaction records
M&T         -M&T         "Joined" master/trans records

Awk files associated with your data files

All associated Awk files are named the same as the data files except with an "A" on the end.

For example, if you have a project file suffix of "xx" and a file named "mast.xx" then the corresponding Awk file would be "mast.xxa".

Global Definitions file

Your global definitions file is always called "ADB.xx" (where "xx" is your project file suffix.

The global definitions file must always exist.

Step Definitions file

You may optionally code a step definitions file.

In fact, this is normally done to specify ADB's input and output file statments for this step.

E.g.:


-STEPstepdef

Typically this file is built with DOS batch file Echo statements just prior to the step (as in the examples).

If you add a few helpful remarks with the DOS REM command, the reader of your code will have little difficulty understanding the nature and purpose of the I/O files that you've selected.

Project File Suffix (extension)

All file names on the command line must either not have an extension (the part after the dot) . . . or the extension must be identical to your project file suffix.

However, the ADBAWKLIB environmental variable, may be assigned to any file name that doesn't begin with "ADB".

The "DOS Compatible" requirement

All file names must be DOS-compatible (including any path information). That means that you can't code:


-MASTC:\Microsoft World Control Files\mastfile

Basically what "DOS compatible" means is that you can have 8 characters (for best results, stick with letters, digits, dashes, and underscores) followed by a an optional dot and up to 3 characters after the dot.

For example:


-MAST\myfolder.dta\whatever

(In other words, the directory, AKA folder, names can have an extension. The base file name, however, has to end in the project file suffix, or not have an extension at all.)

No file name can begin with "ADB"

No (base) file name can begin with "ADB".

It's okay if a path name begins with "ADB".

Return to local table of contents
Return to global table of contents
Frames mode, or No frames

3: Command-line parms (arguments) that are NOT associated with files

There are only three of these.

Code "-P" on the command line if you want to "pretty print" the field layouts to the log file.

Code "-Q" on the command line if you want to eliminate the "echoing" of all log file info. to standard error. This is useful for batch files that will be run by "end-users." That way, their attention span is used sparingly, and they'll be more likely to notice your error messages.

Code "-LAXPRE" if you want "basic" preprocessing (in which fields are aligned and any DOS Control-Z is stripped) to also pad "short" records in input files with spaces.

You do need to make absolutely sure that you have the correct input file names; ADB has no way of knowing that a file has precisely the layout that you've designated (other than by validating record lengths.)

ADB always issues a warning message whenever -LAXPRE is coded. That means that the return code is always 1.

As with the other command line arguments, the names of these arguments are processed case-INsensitively.

Return to local table of contents
Return to global table of contents
Frames mode, or No frames

4: Relationship between data files in the definitions, and those on the command line

Each input or output data file has an "intuitively obvious" relationship to the specifications in the definitions files.

If you code the -M-T parm, the master input file must also be specified on the command line. It's okay if there's no trans file.

If you code the -T-M parm, the master input file must also be specified on the command line. &nbps;It's okay if there's no master file.

If you code -M&T, then both the master and trans file must be specified on the command line.

It's illegal to code either -MAST or -TRANS on the command line without at least one output data file parm (-M-T, -T-M, or -M&T).

If a particular data file is coded on the command line, the specification for it must exist in the layout files.

However the reverse isn't true: you're merely warned if an input or output data file is described in layout files, but not specified on the command line.

It's legal to have no data files specified on the command line; this is useful for printing the file layouts with the -P parm, or simply for validating them to ensure that you have the proper syntax.

In fact, you can run ADB with no command line parms whatsoever if you just want to do a "syntax check" on the file layouts in the global definitions file. Careful programmers may wish to include such a step at the beginning of every ADB job.

Return to local table of contents
Return to global table of contents
Frames mode, or No frames

5: The special "-OUTDFLT" parm

The -OUTDFLT parm can save you a lot of coding.

If a field in the output file is not in the master file or the transaction file, then this field will be filled with the default. If the field is a character or special field, it'll be initialized to spaces. If it's a numeric field, it'll be set to zero.

If a field appears in the master file, but not the transaction file, it will be initialized with the master file value ... for the M-T or M&T output files.

If the field appears in the transaction file, but not the master file, it will be initialized with the transaction file value ... for the T-M or M&T output files.

If a field appears in both files, it will be initialized with the master file value, for the M&T output file.

The effect of the -OUTDFLT parm can be overridden (on a per-field basis) in your I/O layouts: it's just available to you, in the event that you wish to make your code shorter.

Return to local table of contents
Return to global table of contents
Frames mode, or No frames

6: ADB system files

These are the files that are automatically created and/or maintained by ADB.

Temporary Data Files

ADB's temporary data files all have names of the form: $ADB_*.xx (where "xx" is the project file suffix).

If a run is successful, ADB will erase all temporary files created during that run at the end of that run.

"Successful" runs also include those in which ADB issued warnings.

If a catastrophic error is encountered, all temporary files which were required at that point in the processing will remain.

Temporary Awk Files

ADB's temporary Awk files all have names of the form: $ADBA*.xx.

Log File

The log file is called ADBLog.xx.

It's never automatically erased.

Main Error File

ADB's main error file is called ADBErr.xx. If that file exists, ADB will not run. This prevents a DOS batch file from "racing headlong" forward (and possibly overwriting production data).

However, it's always a good idea to code something like this:


If ErrorLevel . . . Goto FAIL

after calling ADB--just in case you have other job steps that could clobber files irreversibly.

Note that whether you test for ErrorLevel 2 (catastrophic errors) or ErrorLevel 1 (warnings) will depend on whether you expect warnings. (See the next subsection for ADB's return codes).

Subsidiary Executables Error File

If any of ADB's three subsidiary executables bombs out, the error message from those executables will be in ADBErr_E.xx.

Since ADB will also write a message to ADBErr.xx when this occurs, it will not check for the existence of ADBErr_E.xx when it begins to execute. However, the last line in both the log and (main) error files will refer to ADBErr_E.xx.

Note that when a subsidiary executable bombs out, ADB will not erase any temporary files, and it will print the execution line into the log file. This allows you to run the operation in isolation.

In fact, the principal method for debugging Awk scripts is to deliberately introduce a syntax error.

ADB's three subsidiary executables are:


GAwk.Exe   -- GNU Awk
RPSort.Com -- Robert Pirko's sort
DBCvt.Exe  -- My commas-n-quotes <--> fixed length converter

Awk Script Error Signal File

If your Awk script calls the special function ADB_ErrorFnc("Error Message"), the "Error Message" string will be written to ADBErr_A.xx.

This file is erased before every Awk script is called, and if it exists after the script has been run, ADB will treat this condition as a true "job bombing" error (i.e. the run will be aborted.)

ADB will also write a special message into its log and error files . . . this message will tell the reader to look at ADBErr_A.xx. for a more precise description of the error.

Awk Script Debugging File

If your Awk script calls the special function ADB_DebugFnc("Debug Message"), the "Debug Message" string will be written to ADBDbg_A.xx.

This file is erased before every ADB run. Note that there may be as many as 5 Awk scripts executed during an ADB run, so your "debugging" messages can reflect more than one such script.

Zipping Up all Files

To zip up all files associated with an ADB run into Error.Zip, use these two lines:


If Exist Error.Zip Del Error.Zip
PkZip -aex Error.Zip *.%ADBPROJ%* %ADBAWKLIB% %0

Note that this will include all Awk and data files (including temporary files) as well as all ADB's system files and the executing DOS batch file.

You can then instruct the user to send you Error.Zip as an e-mail attachment.

This eliminates the need for a $100 PC-Anywhere site license on every machine requiring remote debugging.

Return to local table of contents
Return to global table of contents
Frames mode, or No frames

7: ADB return codes and warnings

ADB returns 0 for a successful execution, 1 if there are warnings, or 2 for catastrophic errors (i.e. the job "bombed").

ADB issues warnings only in three cases:

1. An input field is being moved into a shorter output field.

2. You've coded "-LAXPRE" and/or short records have actually been padded with spaces.

3. An output file exists already, and is being overwritten.

In certain rare situations, warnings of the first and second type are "normal." There's currently no way to suppress them, however.

There's no reason why you should get a warning of the third variety, if you're using the utility FileStat.

When ADB bombs the job on a catastrophic error, it doesn't "clean up" any temporary files which are currently in use.

This allows you to inspect the files' contents in order to track down the source of error messages. You can also use this facility to test your Awk scripts (by deliberately introducing a syntax error).

If ADB ends with a catastrophic error, it will print the error message on the screen and into both the log and error files.

Normally catastrophic errors are described in the log file as:


USER ERROR

If you see this, the next few lines will explain why ADB felt that the error wasn't its fault.

If you get an error that ADB describes as:


INTERNAL ERROR

in the log file, then then please write to me at:
rog@NOSPAM_rs-freeware.org.

(Internal errors indicate that there's a bug in the code, and/or in the way in which errors are being detected and/or processed.)

Return to local table of contents
Return to global table of contents
Frames mode, or No frames

8: Redundant note on control panel settings

(I already explained this in the install, but I want to make sure it's not neglected.)

For Windows 9x, 2000, and NT PCs, go to the system icon in your control panel, and click on the performance tab.

Click on advanced settings, and then the troubleshooting tab.

Check on the box that says "disable write-behind caching for all drives".

(Note: I'm not 100% sure that this step is necessary, but I've seen DOS batch applications behave oddly without this setting on some versions of 95.)

Return to local table of contents
Return to global table of contents
Frames mode, or No frames

Next documentation section