Update Do-Not-Send File

DNSUPD [[-]key] [ndxfile.ndx]
DNSUPD LST=textfile [ndxfile.ndx]
DNSUPD logfile.dbf [logfile.dbf ...] [ndxfile.ndx]
DNSUPD ujppath.ujp [ujppath.ujp ...] [ndxfile.ndx]
DNSUPD ?

The first two forms of the command line above are used to add or delete keys from the standard do-not-send (opt-out) index files in the FAXFACTS\LOG folder.  They provide a simple subset of the features of the PIN program.  Use a ? parameter to display usage information.

If an ndxfile parameter is not supplied, the DNS.NDX file is used for phone number keys and the DNS_MAIL.NDX file for keys which contain @ or alphabetic characters.  When you supply an override NDX filename, its type is not checked against the type of the key.  The key may be preceded by a '-' character to delete it from the file.

The LST= option allows a simple list of keys to be added to or deleted from the index, each key optionally preceded by a '-' to indicate deletions.  Any following text on a list line is ignored if preceded by a semi-colon.

When run as a command-line application, an exit code is returned as follows:

0Successful update
1Failed to add or delete the key
2Update not necessary (addition already present in the file, or deletion not present)

Logging and Journaling

All update actions are logged in DNSUPD.LOG in the FAXFACTS\LOG folder.  You should archive and clear this from time to time.  For larger sites where more than one person may be using DNSUPD concurrently, set a system environment variable DNSUPD_LOG to the full pathname of an alternate log file for each user.  If you set this variable to a value of 'none', then no log will be written. The log data will instead be written to FFTRACE if the 'start/stop trace' checkbox is set for DNSUPD.

Principally for use when DNSUPD is called from a COPIAFACTS run box, you can use two additional command-line options:

"JNL=textstring"After each index update, adds a line to a file ndxfile.JNL which contains the key and, following a semi-colon, a date/time stamp and the textstring value.
"DUP=textstring"After each index match (addition already present, deletion already absent), adds a line to a file ndxfile.DUP which contains the key and, following a semi-colon, a date/time stamp and the textstring value.

The purpose of the journal file is to provide a backup of all additions to the NDX file in a format which can be re-applied directly using the LST= syntax.  It also records any data you need about the source of the update.  For example, in an automated IVR application such as OPTOUT, you would record the date, time, and originating number of the caller by using a $run comand such as:

$run """@PFC\DNSUPD.exe"" @BLOCKNUMBER @DNSFILE ""JNL=@ANI""" 

If the number 630-741-6000 in @BLOCKNUMBER is successfully added to the file DNS.NDX which is specified in @DNSFILE, then the following line might be added to DNS.JNL:

6307416000 ; 2012.10.26 10:08:30 6303886900

In the above example, the last number on the journal line is the ANI (calling number) from which the opt-out call was placed.

The purpose of the duplicates file is to record calls and actions where the number was already present in the NDX file.  You may wish to contact the caller in these cases, or to investigate why it appears that repeated attempts are needed to add the number to the opt-out list.  The format of the added line is the same as for the journal file, and you can also combine both functions on the same command:

$run """@PFC\DNSUPD.exe"" @BLOCKNUMBER @DNSFILE ""JNL=@ANI"" ""DUP=@ANI"""

In both files, enrtries are also made for deletions, with a '-' sign at the start of the key value.  The duplicates file records attempts to delete an entry which was not present in the NDX file.

The JNL= and DUP= syntax can be used on any of the DNSUPD command-line formats.  Double-quotes are only needed if the textstring may contain blank space: in the case of ANI this is unlikely, so the command could be written:

$run """@PFC\DNSUPD.exe"" @BLOCKNUMBER @DNSFILE JNL=@ANI DUP=@ANI" 

Interactive Use

Without a key specified on the command-line, the program displays a dialog:

You can enter a single value at a time which is to be added to the file, or deleted from it when the value is preceded by a '-' sign.  If you have entered an NDX filename on the command-line, it is retained in the field so that you can enter multiple keys and press enter after each one.

In the North America Numbering Plan (NANP) areas (as determined from $country_code), an NDX file which is created from DNSUPD will be marked and maintained with no ten-digit numbers: all ten-digit numbers will have a leading 1 added.  NDX files created before CopiaFacts release 8.2 and not subsequently re-indexed using PIN may contain either 10- or 11-digit NANP numbers, but look-up operations other than in PIN and DNSUPD will find matches in either format.  For more information, see the Telephone Number Formats topic.

In the North America Numbering Plan (NANP) areas (as determined from $country_code), DNSUPD will check your main DNS.NDX file, if present, and offer to convert it to contain only 11-digit NANP numbers, if this has not already been done.  This is done by running the PIN utility for you: PIN.exe must be present in Program Files [(x86)]\Copia.

The status line will report the number that has actually been added or deleted whether or not it was entered with a leading '1'.

Scanning DBF Logfiles

When a CopiaFacts daily logfile (for example 20121225.DBF) is named as the first parameter on the command line, it is scanned as described below, and for do-not-send files the fax phone (or e-mail address) is added to the specified DNS file, unless the same destination has also been reached successfully in the same set of log files. The following conditions are applied to this operation:

Multiple FilesProvided a filename with a .DBF extension is first in the parameter list, you can include multiple DBF file specifications in the command-line parameters.  These specifications may include wildcard characters * and ?, but must not include a pathname.  The files can only be picked up from your FAXFACTS\LOG folder.
KeywordsOne of the following keywords can appear on the command line. If none of them appear, the default is fax.
faxdata is extracted from successful and failed outbound fax items. Failures are ignored if a successful transmission is found in the same scan.
emaildata is extracted from successful and failed outbound e-mail items.  Failures are ignored if a successful transmission is found in the same scan.
voicedata is extracted from successful and failed outbound voice items.  Failures are ignored if a successful transmission is found in the same scan.
baud, allbauddata is extracted from successful outbound fax items. It records the highest baud rate at which a successful delivery was made, and is then actioned as follows:
above 14400the entry is deleted from the index, if present, and if the keyword is allbaud.
12000 or 14400an entry is added with value 201 to select a variable group which restricts speed to 14400
9600an entry is added with value 202 to select a variable group which restricts speed to 9600
7200an entry is added with value 203 to select a variable group which restricts speed to 7200
4800an entry is added with value 204 to select a variable group which restricts speed to 4800
NDX fileIf no NDX file is specified, DNS.NDX is used for fax and voice transactions, DNS_MAIL.NDX for email, and BAUD_ACTION.NDX for baud.  If an NDX file is specified, its type is not checked against the type of the key.
Address lengthSince the log field is only 25 characters wide, e-mail addresses longer than 24 bytes (longer may be truncated addresses) are ignored.
Status selectBy default, all failures are selected.  To select specific failures only, place a quoted string of one or more blank separated outcome codes on the command line.  You may also include single outcome class letters in this string.

Examples:

To add all 'no answer'  and 'fax failure' fax items failed in April 2012, you could use the following commands:

DNSUPD 201204??.DBF DNS.NDX fax "A F"

To update an action list for baud-rate vargroups:

DNSUPD 2012*.DBF BAUD_ACTION.NDX baud

Scanning Completed Jobs

When a CopiaFacts Job Administration UJP file (for example @FFJOBS\JOB12345.DBF) is named as the first parameter on the command line, and is a completed job, its FS files are scanned as described above and below. for failed transmissions, and for do-not-send files the fax phone (or e-mail address) is added to the specified DNS file, unless the same destination has also been reached successfully in the same set of log files.  The following conditions are applied to this operation:

Multiple FilesProvided a filename with a .UJP extension is first in the parameter list, you can include multiple UJP file specifications in the command-line parameters.  If you include SYSTEM.UJP or an OWNER.UJP or JOBTYPE.UJP file, all completed jobs below that level will be included.  Full pathnames must be supplied, but can include @FFJOBS. Wildcards can not be used.
Address LengthThe full e-mail address is available in the FS file, so any length of the extracted effective address is used.
KeywordsIf the keyword dialed is used, the destination phone or fax number is taken from the DIALED_DIGITS variable, not from the FS file $fax_phone or $voice_phone command.

The other conditions described for log files above also apply to scanning completed jobs.  You can scan either logfiles or jobs, not both at the same time.

Interactive Scanning

The "Scan..." buttons on the dialog give access to the same ability to scan DBF logfiles or completed jobs while using the program interactively.  In this case multiple files can be selected from a treeview.  The advantage of using the program interactively is that you can review and edit the list of items to be added, or you can re-scan if your selection of status values was incorrect.

We recommend that you experiment with interactive scanning to find the most appropriate combinations, then add a regular scanning operation specifying the same parameters on the command line.

The fields on the scanning dialog correspond to those described above.  First, pick the log items you need:

Or, if you are scanning for completed jobs, pick the ones you want to scan:

When you click the large button to perform the scan, the results will be shown in the right-hand window:

Note that the error shown in the right-hand window will be the first error encountered for the number in the scan.  The text following the semi-colon is a comment only, and is not used to update the file.

You can edit the list before updating the NDX file.  Alternatively you can select specific failure outcomes only, and re-scan the list.  To filter the failures, enter the outcome classes and or outcome codes, space-separated, in the box.  Clicking the icon at the right-hand end of the box allows you to select previously used filter sets.

The above example selects only outcome class A (no answer) and F (fax failure) to be included in the extracted items:

When using the Baud operation, the right-hand panel shows either that the fax was sent at less than maximum speed.  The code number to the right of the phone number is the variable group selector:

When you have a set of filters and options which extract the files you want, you can right-click the 'Scan' button to copy the corresponding command-line to the clipboard.  From there you can build it into a regular batch file or a command for $end_job_tasks:

Using the Results of a Baud Rate Scan

The purpose of collecting the baud rates of successful faxes is to reduce the time taken to negotiate down from higher speeds on lines which are not capable of handling the traffic, and to reduce the number of failures on bad lines.  CopiaFacts allows you to set variable groups including MAX_BAUD variables, which can be brought into scope after looking up the phone number in an $action_phone list.  The same variable groups can also be enabled on retry: this catches transmission routes which are good enough to negotiate a high baud rate but which then cannot support transmission at that rate.  By collecting the fasted achieved transmission rate, you can improve throughput rates for subsequent calls.

To use the collected rates on subsequent calls, you need to first add a command to specify the file in FAXFACTS.CFG:

$action_phone @FFLOG\BAUD_ACTION.NDX fax 

Then in the USR file(s) used for outbound calls, you need to define the variable groups.  These can also be defined in SYSTEM.UJP for Job Administration users.  The numbers assigned action code 201 in the look-up will bring variable group 1 into scope, 202 group 2, and so on:

; define the default variables: these are not 'grouped' variables:

$var_def MAX_BAUD 33600      ; no limit

$var_def BM_DISABLE_V34 ""   ; affects Brooktrout TR1034 only

$var_def DIVA_DISABLE_ECM "" ; affects Diva only

; define the first group overrides, selected by code 201

$var_def 1/MAX_BAUD 14400      

$var_def 1/BM_DISABLE_V34 1   ; affects Brooktrout TR1034 only

$var_def 1/DIVA_DISABLE_ECM 1 ; affects Diva only

; define the second group overrides, selected by code 202

$var_def 2/MAX_BAUD 9600       

$var_def 2/BM_DISABLE_V34 1   ; affects Brooktrout TR1034 only

$var_def 2/DIVA_DISABLE_ECM 1 ; affects Diva only

; define the third group overrides, selected by code 203

$var_def 3/MAX_BAUD 7200       

$var_def 3/BM_DISABLE_V34 1   ; affects Brooktrout TR1034 only

$var_def 3/DIVA_DISABLE_ECM 1 ; affects Diva only

; define the third group overrides, selected by code 203

$var_def 4/MAX_BAUD 4800       

$var_def 4/BM_DISABLE_V34 1   ; affects Brooktrout TR1034 only

$var_def 4/DIVA_DISABLE_ECM 1 ; affects Diva only

Finally, in order to retry failed faxes at slower and slower speeds, you can specify the action groups on a $retry_delays command for fax failures:

$retry_delays F "G1/3 G2/3 G3/3 G4/3"  ; 3-min intervals, decreasing baud

Subsequent runs of DNSUPD will update the look-up file to record the speed attained.  Because lines vary, and old fax machines get replaced, it is recommended that at intervals, you should run your CopiaFacts system for a few days with the $action_phone command commented out.  Then, in case some faxes go through at higher rates, you should run DNSUPD using the 'All baud rates' checkbox (or the commandline 'allbaud' keyword):

With this setting, the baud rates for all successful faxes are extracted, and any that go through at above 14400 are then deleted from the look-up file:

You can use an action value of 200 (effective only in DNSUPD) to delete an item from the list.  If you need to edit the BAUD_ACTION.NDX file manually, you can use PIN for individual items, or you can dump it to a text file with the PIN 'm' command and then reload it.