List files are specified using the $listfile command in job properties. As a minimum, each line or row must contain the destination number or address, but usually a list will contain other columns to identify the item or to customize the broadcast for individual recipients. Data extracted from a list is identified using either a numbered variable with the column number (BCF1, BCF2, etc) or a name variable using the name in a column header row (BCX_FAX, BCX_name, etc.). These variables can be used for any purpose, including selecting a different document for each recipient.
 | The syntax is now deprecated where list fields can be referenced as ? (for the first field) or ?2 for the second field on certain commands. It is recommended to use @BCFn instead, or `BCFn on e-mail commands. |
The following list formats are supported:
| CSV | The separator character can either be a TAB character (recommended) or the defined Windows list separator for the locale. The file extension determines the separator (.TSL, .TAB, .TXT are assumed TAB separator files, and .CSV uses the defined delimiter) but this can be overridden using the FORCE_TAB and FORCE_CSV variables. A simple text file of destinations is treated as a single-column tab-separated-value list with no TAB characters. |
| DBF | This standard database format can be created from many systems. The index is not used for the broadcast list. |
| XLS(X) | Excel lists with or without a header row are fully supported. |
| HTML | The multi-document output from a report generator can be used directly as a list, where each document in the file contains a comment line with destination and other variables. The documents themselves are converted to TIF for faxing. See below. |
| Custom | A user-written DLL can be specified to return list lines for use in a job launch. The DLL will produce a tab-separated-value line for each job item. See below. |
By default, XLS and XLSX files are read directly using a library implemented in CF9EXCEL.DLL, and Excel is not required to be installed. However the following important considerations apply to these files:
•XLS files produced from Excel 95 or earlier are not supported by the internal XLS reader and require Excel. The USE_EXCEL control variable must be set to a non-empty value.
•XLS and XLSX files with very complex formulas may require Excel, in which case the USE_EXCEL control variable must be set to a non-empty value.
•When USE_EXCEL is specified, XLS and XLSX files require Excel 2007/2010/2013/2016 to be installed.
Any broadcast job can use multiple lists provided that the columns required for the broadcast are in the same positions in each list. You can specify whether or not lists have header rows.
The data from the first item in the first list will be used when a 'proof' or 'preview' of the broadcast is requested as described further below. An override number or e-mail address can also be supplied so that the proof fax or e-mail is not actually sent to the destination specified in this item.
Correcting Broadcast List Destinations
In some cases a fax broadcasting bureau may be responsible for fixing 'errors' in each list supplied by a client. The variable FIX_LIST is available to specify the pathname of a list of old and new destinations. The destination is then 'fixed' if it is found in the first column (BCF1) of the list. Each line of the 'fix list' must contain an old and a new destination, separated by white space. In an FEB1 broadcast you can change a destination between fax and e-mail.
For example:
16417416000 16307788848
16417416013 steve@copia.com
...
When white space follows the new destination, any white space and following comments are ignored. Any changes are made before do-not-send and whitelist processing, and in a combined fax/email broadcast (FEB1) the type of the destination may be changed.
When an entry in BCF1 has been corrected using the FIX_LIST, the original destination can optionally be saved in a new (or existing) BCF variable. The BCF number to use for this purpose must be specified in job variable FIXED_LIST_BCF. When specified as a number greater than 1, the number of fields on the list row is extended if necessary and the original content of BCF1 is saved, as if it had been found on the row, in the new variable. You should normally select a field number which is one greater than the number of fields on each row. For example in a list with four fields, a value of 5 in FIXED_DEST_BCF will save the original destination from BCF1 into BCF5 when BCF1 is matched in the list of changes, and no BCF5 variable will be added or modified for the list row otherwise.
A DLL interface is available which allows you to provide a user-written DLL to supply list data. The CUSTOM_LIST_DLL variable is used to specify the path to the DLL. Contact Copia support for details of the interface if you feel you may have a use for this feature.
In addition, to interface with your applications which generate HTML reports, you can supply a broadcast list ($listfile) as an HTML file which contains one or more separate HTML documents. 'List fields' must be supplied in an HTML comment line at the top of each document, and must include the destination fax number to be used. Each field must be surrounded by double-quotes (without embedded double-quote characters) and there must be a single space character between the fields. For example:
<!DOCTYPE html PUBLIC "--//W3C .... >
<!--CopiaFacts "16307788848" "" "Steve Hersee" -->
becomes in an FS file:
$var_def BCF1 "16307788848"
$var_def BCF2 "@FFJOBS\owner\jobtype\temp\job12345678_0001.html"
$var_def BCF3 "Steve Hersee"
...
Before launch the whole file is read and split into separate HTML files. The variables from the comment line appear in BCFn values, with the path name of the converted file inserted as the reserved variable BCF2. If you launch a job from JOBADMIN, the pre-launch operations will be recorded as '1 of 0, 2 of 0, ...' (because the total is not known until the whole file has been processed). After this, the launch count will be shown as usual with the total visible as the FS files are created. The HTML images are saved in a TEMP folder in the same folder as the job instance UJP file. Any referenced images are best placed in an IMAGE subfolder of this folder. An option controlled by a non-empty CONVERT_HTML_LIST variable will pre-convert all HTML documents to TIF and save them in the same folder. In both cases they will be converted using the built-in HTML converter and html must not be included in $convert_types.
You may also optionally use the EXPAND_BI_HTML to expand variables in the HTML document as it is converted. This is not supported in conjunction with CONVERT_HTML_LIST.
Because this feature needs to render large HTML pages the COPIAFACTS program can suffer from memory fragmentation. We recommend that job sizes are limited no more than a few thousand items before closing and restarting the program.
Please contact Copia Support for further details of the interface if you feel you may have a use for this feature.
