ListsBuilder 2.01
====================
(c) 2002, 2003 Hans Hockx, jcm.hockx@hccnet.nl


INDEX:
1.	Legal stuff
2.	About Listbuilder
3.	Using ListBuilder
4.	ListBuilder limitations
5.	Installing ListBuilder
6.	Command line parameters
9.	Some questions and answers
11.	Contact information
12.	History


1.	Legal stuff:
Has to be here, since people tried to dry their guinee pig in a microwave and sue the microwave's manufacturer for the death of the poor animal.... ListBuilder is freeware, released under the terms of the GNU General Public License, see     <http://www.gnu.org/copyleft/gpl.html>. Use it if you like it, otherwise don't!


2. 	About ListBuilder:
ListBuiler is a utility for those who work with large sets of (structured) data in ASCII (plain text) format. For instance: data exported from a database, spreadsheet, wordprocessor or data that is used on an other platform like Personal Digital Assistants such as Psion or Palm. These are the kind of files that have one record on each line, where each line has several fields (delimited by comma, TAB or with a fixed lengt for each field). With ListBuilder you can:

- substract selected fields (create a new list) from the source file and write this information to a new file;
- create a new list with the same information but with a changed  sequence of information (fields) in each record;
- convert comma delimited files to TAB delimited files
- convert a file that has fixed field length, without delimiters between the fields, to a comma or TAB-delimited file. This will also remove any trailing spaces form each field.
- write a new file with records that are selected on the content of one particular field (operators supported are 'equal' and 'not equal' to a user supplied text.
- Combine data from different sources into a new file (data from the second file will be appended to an existing file if you enter the name of an existing file for the output file. If no such file exits, a new file will be created.
- list definitons can be saved for future use. 

With the available set of features ListBuilder can be used in stead of several dedicated filters written in REXX or any other language. The programs interface was made with good old VisPro Rexx 2.1 that was released by Hockware in the mid 90's of the previous century. I still think it's brilliant!


3. Using ListBuilder:
ListBuilder is not a complicated program. Below I will give you some information about how to use this utility. This should be enough to get started (if not, see Contact Information).
The basic concept of the program is that you first supply a list of the fieldnames in the records in the source file that holds your data.  This file can easily be created using an ASCII-editor (i.e.  OS/2's text editor or enhanced editor). When your datafie uses comma's or TAB's as delimiter between each field, just enter one fieldname, press ENTER to go to the next line, enter the second fieldname, press ENTER again and so on. 

Example 1: fieldnames for comma or TAB delimited files:
=========
first_name
middle_name
family_name
adress
city

PLEASE NOTE: Use only one word for each fieldname. Spaces within a fieldname are not allowed!

When your datafile uses fixed field length it will not have any delimiters between the fields. You will have to tell ListBuilder the length (number of characters) of each field. To do this, just append the fieldlength to the filename with a comma (no spaces!) to seperate name and length. In this case your file with fieldnames should look like example 2:

Example 2: fieldnames for files with fixed lengt fields:
=========
first_name,10
middle_name,6
family_name,35
adress,35
city,20

Now save your the file you created on your harddisk and follow the steps below:

STEP 1:
When starting ListBuilder, you will  be invited to enter the name of the file with the fieldnames. The fieldnames are shown in the listbox on the left side of te screen. There is another listbox on the right side that will be empty. 

STEP 2:
You can select any field on the left side that you want to use for the new list. Then click the 'Add field' button. You wil see that that each fieldname you add wil be shown in the listbox on the right. This is the way you define the new list you are going to create. You can select fields from the left in any order that you like and thus change the sequence of the fields in the new list.
It is also possible to add the same field more than once to the output list definiton (in case you ever feel the need to do that).
When you make a mistake you can allways remove any field in your output list definition. Just select the field and click the 'Remove field' button. 
Please be aware of the fact that every fieldname you add to the list on the right will be placed at the bottom of the list. So if you need your data to be in a predefined sequence you will have to select and add each field to the list definition in that order.

STEP 3:
When you are finished creating the list definition it's time to go to the next button that is labelled 'Input / Output'. When clicked a new window will open where you can specify the filename and path of the source file with the data that you want to use. Now use the radio-buttons to tell the program if this file is TAB delimited, Comma delimited or Fixed field.
Having done that you use the lower part of this window to set a name and path for the output file that will be written by ListBuilder. Also choose the type of delimiter you want to be used in this new file. Now close this window to return to the main screen.

STEP 4 (OPTIONAL):
If you want only selected records to be written to your new file click the 'Select' button. This will open a window where you can use the spin-button to choose the field that has to be used for selection Then add the value (text or number) in the text field below. This will be the value that is used for selection. On the right side of the window you can select the operator that has to be used when selecting. Currently there are only two operators to choose from: 'equal to value' or 'not equal to value'. When you skip this step, no selection will be made when writing the output file (which means that from all records from the source file the fields you selected will be present in the output file). When done, close this window to return to the main screen.

STEP 5
When you click the 'Build list' button, ListBuilder will create the output file using the information you supplied in the previous steps. This will take some time, depending on the number of records available in the source file. There will be a read warning text at the top of the screen as long as ListBuilder is working. When finished a pop-up window will appear to inform you that the job is done.

As you have seen creating a new list from an existing set of data can be accomplished by the 5 buttons in the middle of the ListBuilder's main screen. This screen also has a menu bar. Using the file menu you can:
- load fieldnames: This is basicly the same thing as you have seen in step 1. The menu option makes it possible to load another set of fieldnames without exiting the program and restarting it again. It will be loaded in the left hand listbox.
- load list definition: Use this option to load a previously defined list in the right hand listbox. This makes it easy if you have to create the same list more frequently (please note that you also have to load the fieldnames from the source file in the listbox on the right. ListBuilder needs both to be able to write a new list).
- save current list definition: Use this option if you want to save the list definition that is currently on screen for future use. List definitions are saved with a default filename extention of .def.


4. ListBuilder limitations:
ListBuilder is designed to work with plain ASCII-files. The program can not read files (database, spreadsheet or whatever) that use a different file format. However, most of these programs will be able to export data in some ASCII format that ListBuilder can use (most likely TAB or Comma delimited).
Some spreadsheets will export data to TAB- or Comma delimited ASCII and put text values between quotes where numbers are written without quotes. This is something ListBuilder can not solve. So you will see those quotes in your output list as well. The easiest way to lose the quotes is to load the file in an ASCII-editor and tell this program to search for qoutes and replace them with nothing. Fast and simple.  ;-)


5. Installing ListBuilder:
Just unzip the distribution ZIP-file in a directory of choice. After the unzip you will find these five files in your directory:

- 	README.TXT	this text
- 	BUILDER.EXE	the executable file
-	SAMPLE1.TXT	a small sample ASCII datafile you can use for a testrun (see STEP 1)
-	S_FIELDS.TXT	a sample  ASCII file with fieldnames that match the sample datafile (see STEP 3)
- 	SAMPLE.DEF		a sample list definition for the sample datafile that can be loaded from the File menu

Now you can run the program and use the sample files to see how it works. 


6. Command line parameters:
Well... actually there's only one parameter that you can use when starting ListBuilder. It is not needed most of the time, but on some TFT-screens (including laptops) it might be useful. On some screens the text in the buttons of the ListBuilder screen will not be shown completely (button to small). If this is the case, start ListBuilder with the option /SMALL . With this option the text in the buttons will be shown in normal WarpSans 9 points font. When this parameter is not used, WarpSans Bold 9 points will be used.


7. Some questions and answers:
Q: I've used ListBuilder to create a new list but all I get is an output list with a lengt of zero bytes (or a very small file with some garbage). What's wrong?
A: Check the delimiter you specified for the source file that holds your data. If you specify TAB as delimiter where the source file uses Comma's (or the other way around) this effect may occur. 
Q: I've got two files with data. The structure of both files is the same (at least for the fields that I need). Can I use ListBuilder to combine data from these two sources in one new file?
A: Yes. First make a new list from the first datafile, using a list definition that has all the fields you need (and are available also in the second file). Then do the same for the second file. Specify the same output file as the one you've just used for the first list. Data from the second list will be appended to the end of this file. Of course you have to be sure to write the same kind of fields in the same sequence for both files.
Q: OK, I've used ListBuilder to create a new list. But my sourcefile is not indexed the way I want. Can ListBuilder be used to sort te file on one or more user specified fields?
A: No. ListBuilder can not sort a datafile. I'm working on another program to do this. This will be called ListSorter (obvious, isn't it?). You can download it from my website when it's available.
Q: I don't want to use a full size database or spreadsheet to view the data in these lists. Is there some other program I could use?
A: Yes. Have a look at my Contacts Viewer program. Actually I developped ListBuilder in support of this viewer. It can be found on my website (see contact information).


8. Contact information
I would appreciate it if you send me an e-mail when you are going to use this little program. Just because I'm curious to know how many people are using my hockXware. ;-) 
You can find some information and the most recent versions of my programs (including ListBuilder and Contacts Viewer) on the 'useful utilities' page of my 'Psion to OS/2 Connection' website. If you need more information, or if you want to submit suggestions or bug reports, please contact me by email at <jcm.hockx@hccnet.nl>


12. History
version 1.00 : first working version that could only read TAB delimited ASCII sources and used standard filenames for filenames and data (same names as in Contacts Viewer)
version 1.01: nasty bug fixed that caused ListBuilder to crash when trying to write more than 12 fields for each record.
version 1.02: added startup screen to select file with fieldnames (no standard filenames used), added select button and functionality
version 2.00: ListBuilder can now work with sourcefiles that use TAB's or Comma's as delimiter between the fields as well as with sources with fixed field length without any delimiters. 
version 2.01: some minor bugs fixed, error handling added on every places I could think off and cleaned up parts of the REXX code. Added the /SMALL parameter to eliminate problems om some (TFT) screens.