Like most general-purpose databases, Cardbox doesn't have a built-in facility for creating Key Word in Context (KWIC) listings.  But there is a way of producing such reports, using a macro and a couple of separate databases. Here is an example.

Suppose that you have a database of books, called BOOKLIST.FIL.  You want to produce a printout of these books, listed in alphabetical order by title; but if a title has several indexed words, it should occur in several places in the printout, in positions corresponding to each individual indexed word.

Simply sorting on the Title field won't work, because each record would then occur once only.  Instead, you have to build a separate database which contains several copies of each record, one for each intended position.

Preparation

You need two auxiliary databases.

KWIC.FIL

This is the database that will contain the full KWIC listing, with records repeated as necessary.

Using Windows Explorer (or File Manager), make a copy of BOOKLIST.FMT and call it KWIC.FMT.  Then, within Cardbox, use the File, Open dialog box to open KWIC.FMT.  Cardbox will ask you whether you want to create a new KWIC.FIL.  Say Yes, and Cardbox will create the database and get you ready to type the first new record: Ctrl+Q to leave the "New Record" mode, so that you now have a blank database.

The new database has the same layout and indexing strategy as BOOKLIST.FIL.  Since you are not going to be doing any sorting or searching on this database (you will only create it and then print it out) it will make things faster if you now edit the native format and change the indexing mode of every field to "None".  Speed will also be improved if you remove altogether any fields that you are not going to be using in your printed report.

TEMP.FIL

Use the command File, New Database to create a new, empty database.  Create one field within it, with no indexing.  Give the field whatever name you like: in this example, we'll assume that you've used Cardbox's default field name, NONAME1.  Save the native format and give the format file the name TEMP.FMT.  Cardbox will ask you whether you want to create a new TEMP.FIL.  Say Yes, and Cardbox will create the database and get you ready to type the first new record: Ctrl+Q to leave the "New Record" mode, so that you now have a blank database.

Listing the index

Make sure that you are now in Cardbox with all three databases open: KWIC, TEMP, and the original BOOKLIST.

1. Switch to BOOKLIST.
2. Right-click on the Title field.  The Select dialog box will appear.
3. Press the button marked Preview.  A preview dialog box will appear.  Depending on the size of your database, a warning message may tell you that the listing in the dialog box is incomplete.  Don't worry about this.
4. Right-click on the title bar of the preview dialog box and select "Copy preview to file".  A dialog box will appear, asking you what name to give to the file.  Use TEMP.LST as the filename, and press OK.
5. You will be back in the preview dialog box.  Press Cancel to close it.
6. You will be back in the Select dialog box.  Press Cancel to close it.

All the above steps can be recorded in a macro, which will look something like this:

Filling the temporary file

1. Switch to TEMP.
2. Use the command File, Transfer, Read.  A dialog box will appear.
3. Enter the filename TEMP.LST.  Do not press OK yet.
4. At the bottom of the box, there is a box marked "List Conversion Types".  Select "Read a comma-delimited file".  Do not press OK yet.
5. Press the button marked Edit, and a new dialog box will appear.  On the left will be a list of the first few lines in the temporary file, and on the right will be a list of the fields in the database, which will contain a single field, NONAME1.
6. Press the button marked Add, and NONAME1 will be listed under "Linked items".
7. You could press OK at this point, but if you want to perform this procedure in the future, you can save yourself some time if you save this definition so that you do not have to specify everything again.  And if you want to record this procedure as a macro, you must save the definition:
   1. Enter a name, such as "Read Index", in the Customised Title box.
   2. Press the Save button.
8. Press OK.  Cardbox will now read the entire index listing from TEMP.LST into the TEMP database.
9. You will be back in the Select dialog box.  Press Cancel to close it.

The above steps can be recorded in a macro, but only after you have saved the field definition as described in step 7.

Before continuing, you may wish to edit the TEMP database and remove any index terms that you do not want to be used as keywords in the KWIC index.

Recording the KWIC macro (once only)

You only ever need to perform this step once.  If you find the recording process complicated, you may prefer to create an empty macro and then use the Macro Manager to edit and insert the appropriate macro commands.

1. Press the Record button on the Cardbox toolbar.
2. Switch to BOOKLIST.
3. Use the command Search, Relational, Select.  A dialog box will appear.  Fill it in as follows:
   1. Field: TITLE
   2. Get search text from window: TEMP.FIL
   3. Field: NONAME1
   4. Leave the other options at their default settings, and press the OK button.
4. Switch to TEMP.  Press Ctrl+Home to make sure that you are on the first record of the database.
5. Switch to KWIC.
6. Enter the command File, Transfer, Read from Window. A dialog box will appear.
7. Select BOOKLIST as the window to read from, and press OK.  Cardbox will read a batch of records in to KWIC.
8. In the macro toolbar, press the button marked Loop.  A dialog box will appear.  In the dialog box, press the button marked << until the *StartLoop command is shown just above the command *SwitchTo "KWIC.FIL".  Press the Accept button.
9. In the Cardbox toolbar, press the Stop button.  A dialog box will appear: give the macro a name (we used KWIC2), and save it.

Before continuing, you will have to undo the search and record transfer that you performed while recording the macro: remember, the macro only has to be recorded once!

• In BOOKLIST.FIL, undo the relational selection command.
• In KWIC.FIL, delete all records.

Building the KWIC listing

1. Press the Play button on the Cardbox toolbar.
2. Select the macro name (KWIC2) and press OK.
3. Sit back and wait.  Cardbox will now automatically scan through each search term listed in the TEMP database.  It will find the records in BOOKLIST that match each term in TEMP, and it will add them to the KWIC database.  The speed of this macro depends on the size of your database and the speed of your computer.  When we tried it on a 5643-record database with 3557 distinct index terms in the Title field, it took about 7 minutes.

Refinements

If you want the titles to appear in a certain order (still grouped within each keyword, of course), then sort the BOOKLIST database into that order before playing the KWIC2 macro.

This procedure does not automatically highlight the keyword that was used to position each title, so it may be difficult to search the listing alphabetically by eye.  Here are two ways of getting round this:

1. Alter the KWIC2 macro so that it copies the current term from the TEMP file into an otherwise blank record in the KWIC file.  These records can then act as headings to help the user of the listing to navigate.
2. Alter the KWIC2 macro so that immediately after reading each block of records, it edits them and inserts the current term from the TEMP file into a special field in each one.  This can be done by batch editing each block after it has been read.