README
               
Release Notes for WPL 3.0

These notes describe new features that have not yet 
been included in the manual.


TABLE OF CONTENTS

Installing WPL
Share.exe Ensures Auto-Recovery
Setting PLHOME, PLTEMP, and PLDATABASEHOME
Log Files Help Troubleshoot
Displaying Records in Word or WordPerfect
Displaying Word Records in the Hit List
Hypertext Links in Word and WordPerfect Files
Displaying Images
Blocking Factors Automatically Optimized
"Save Database" is Equivalent to OK
Reorganizing Your Database
Verifying Your Database
Translation of Foreign Characters
Exporting Records in ASCII Format
Hit List from File
Creating Links that Work Database-Wide
Encryption
Known Problems in WPL 3.00.30


INSTALLING WPL

If you have been using an older version of WPL, install this 
version in a completely new directory to avoid conflicts with 
your existing WPL files. 

To install the software:

(1) Close all other applications before you run the 
    installation program.

(2) Insert disk 1 into drive A (or a drive of your choosing).

(3) Double-click on a:\setup.exe in Windows' File Manager.  
    Or, while in Windows' Program Manager, choose "Run" from 
    the File menu and type a:\setup.exe into the "Command Line:" 
    box and click OK.  

Note: If you are using a different drive, replace the a with the 
letter of the drive you are using.

	
SHARE.EXE ENSURES AUTO-RECOVERY

If share.exe is in your operating system environment, PL-Admin 
will attempt automatic recovery from a system crash that occurs 
during indexing.  If share.exe is not installed when your system 
crashes during indexing, consult the Recovery Strategies... section 
in your Database Administration Manual for information on how to 
make your database ready for a new indexing operation.  

If you use share, setting String 65 in defaults.cpl to Y provides 
better protection for your database.  Set String 65 to N when you 
want the use of share to be optional.


SETTING PLHOME, PLTEMP, AND PLDATABASEHOME

Several control variables are used by WPL to locate needed files.  
These variables, PLHOME, PLTEMP, and PLDATABASEHOME, are saved in 
the [WPL] section of the wpl.ini file.  Normally, these variables 
are set by the installation program, but you may wish to reset 
them later.

PLHOME points to the directory containing WPL and PL-Admin 
executable and control files.  Without this setting, you will 
get various "cannot find..." messages whenever you try to start 
an administration process.  PLHOME is similar to the PLLIBDIR 
environment variable used in previous versions of Personal 
Librarian.

PLTEMP should be set to a device that has enough disk space for 
building and maintaining databases.  See your Database 
Administration Manual for more information on how much disk space 
is needed.  PLTEMP is similar to the TMP environment variable used 
in previous versions of Personal Librarian.

PLDATABASEHOME sets the default directory in which new 
databases will be created unless you specify another directory.  
The PLDATABASEHOME setting appears in the file selection box when 
you create a new database, so minimal navigation is required.

To modify these defaults after they are set initially, choose 
"Directories..." from the Options menu in PL-Admin, or edit your 
wpl.ini file using an ASCII text editor.

When you choose "Directories..." from within PL-Admin, PLHOME is set
in the "Control Files" box.  PLTEMP is set in the "Temporary Files" 
box. PLDATABASEHOME is set in the "Database Files" box.


LOG FILES HELP TROUBLESHOOT

The wpl.log and wpladmin.log files are automatically created in 
your windows directory, and always get appended to.

A separate entry is created in wpl.log each time you start up WPL.  
Typically, the date and time you start each WPL session is the only 
information that appears in this log.  When you experience a problem 
with WPL, wpl.log may provide valuable information which can help you 
resolve the problem immediately, or which can help the technical 
support department troubleshoot the problem with you.

Wpladmin.log is appended to each time you start up PL-Admin and helps 
troubleshoot problems you have while using PL-Admin.

If these logs grow too large in size, you may want to delete them.  
Avoid deleting a log that contains unresolved errors.  The first time 
you open WPL or PL-Admin after a log is deleted, a new log is 
automatically created.


DISPLAYING RECORDS IN WORD OR WORDPERFECT

You can instruct WPL to display records in Word or WordPerfect instead 
of in the usual WPL Record Window.  To display records in Word, add the 
following lines to your wpl.ini file:

[ApplicationDisplay]
.doc=1

where:
.doc is the suffix for the Word application, as specified through 
     Windows' "registration database" feature; the suffix for a 
     "registration database" is set through the Windows File Manager.
1 causes files having a .doc extension to be displayed in Word.

To display records in WordPerfect, add the following lines to your 
wpl.ini file:

[ApplicationDisplay]
.wp=1

where:
.wp is the suffix for the WordPerfect application, as specified 
     through Windows' "registration database" feature;  the suffix 
     for a "registration database" is set through the Windows File 
     Manager.
1 causes files having a .wp extension to be displayed in WordPerfect.


DISPLAYING WORD RECORDS IN THE HIT LIST

If you display records in Word instead of in the usual WPL Record 
Window, "No Title" sometimes appears in the Hit List.  This usually 
occurs after a Word record is displayed in Word.  To display the 
record's summary instead of "No Title," set hitlist=container in 
the database's definition file, or make the Word file "Read Only."


HYPERTEXT LINKS IN WORD AND WORDPERFECT FILES

WPL will recognize hypertext links in ASCII, Word, or WordPerfect 
files, but will not recognize field labels in Word or WordPerfect 
files.


DISPLAYING IMAGES

To display an image, the image type must be defined in your wpl.ini 
file.  For example, to display PDA images, your wpl.ini file should 
contain the following:

[WPLImage]
pda=rasterb,command

where:
pda is the image type
rasterb is the image program you want it to run 
     (i.e., PLS's Image Module in this case)
command is the type of link being executed (DLL is the only other 
     valid value)


An image link for a PDA image would look as follows:

<I<pda,c:\images\plane.pda>>Double-click here to display a picture 
of the plane.</D>


BLOCKING FACTORS AUTOMATICALLY OPTIMIZED

The performance of operations on a database's dictionary of unique 
terms is affected by the size of the data blocks used to store the 
terms.  The size of the data blocks used are referred to as 
blocking factors.  You can either set a specific blocking factor, 
or you can let PL-Admin automatically optimize the blocking factor.

When you choose "Save Database As..." from the File menu in PL-Admin, 
your database is reorganized.  During a reorganization, blocking 
factors are automatically optimized resulting in the fastest possible 
build and search speed, and in the best memory usage for your database.

For databases that will grow to have many unique words, you may want 
to specify your own blocking factor when you create the database's 
definition file.  For example, if your database will have more than 
200,000 words, you may set this value to 12288 (i.e., 12K).  The 
definition file entry would be as follows:

	INDEX_BLOCK_SIZE=12288

If a blocking factor is not present in the database's definition file, 
the value in String 76 is used.


"SAVE DATABASE" IS EQUIVALENT TO OK

The "Save Database" command functions the same way the OK button does 
in the "PL-Admin" dialog box.  It saves the database's definitions 
selected in the "Define Database" dialog box, it adds records to a 
new database, or it modifies an existing database.  Please see the 
Database Administration Manual for a more complete description of the 
OK button.


REORGANIZING YOUR DATABASE

The "Save Database As..." command takes an existing database and 
reshapes it to conform to the parameters of a new definition file.  
This is also referred to as "reorganizing the database."  

Open the database you wish to reorganize in PL-Admin. Choose 
"Save Database As..." from the File menu.  When the "Save Database As" 
dialog box appears, navigate to the directory where you want to store 
the reorganized database. Enter the name of the database you are 
reorganizing (without an extension).

A "Save Database Options" dialog box appears, and the database's 
original definition file is displayed. You can add fields 
(i.e., click ADD...), add database-specific settings 
(i.e., click MORE...), or accept the database's original definition 
file and begin the reorganization of the database (i.e., click OK).  

Note: If you click MORE... to add special settings to your 
definition file, please press CONTROL-RETURN to end each line and 
begin another.  To exit the dialog box and begin the reorganization, 
press RETURN.

A message appears reminding you to move the new database files to 
the database directory.  Press RETURN to acknowledge that you have 
seen the message.

When the reorganization is complete, PL-Admin displays a "Ready" 
message.  Exit PL-Admin. To replace the old database with the newly, 
reorganized one, delete the old database files dbname.def and 
dbname.pls.  Copy the new database files to the original database 
directory.  

For example, suppose you reorganized the news database.  The 
original database is stored in D:\wpl30\news and includes a 
news.def, a news.pls, and a news.src file.  The reorganized database 
is in D:\wpl30\reorg and includes the new news.def and news.pls files.  
Delete the news.def and news.pls files from D:\wpl30\news, and copy 
the new files from D:\wpl30\reorg to D:\wpl30\news.


VERIFYING YOUR DATABASE

"Verify Database..." checks the integrity of the open database's 
index files.  To run a verify, start up PL-Admin and open the 
database you want to check.  Choose "Verify Database..." from the 
File menu and check any combination of the following options:

Dictionary - checks the dictionary for consistency.

Postings - checks the postings list for each word in the dictionary.

Postings and Documents - checks the same things the  "Dictionary" 
     and "Postings" options check.  In addition, this option tries 
     to instantiate each record.  Almost the same amount of checking 
     is done in a fraction of the time by choosing "Dictionary" and 
     "Postings" without choosing "Postings and Documents."

Non-stop - runs the verify until the end of the database is reached.  
     When this option is not chosen, verify stops processing after a 
     certain number of errors are accumulated. 

Click OK to start the verification process.  A "Verify Output" dialog 
     box appears which flashes % complete status messages throughout 
     the verify.  When the verify is complete, it will display the 
     number of errors found and the number of warnings issued.  When 
     errors are discovered, please pass the warning messages along to 
     technical support if you are not sure whether or not you need to 
     rebuild your database.

Click OK to return to the PL-Admin menu.


TRANSLATION OF FOREIGN CHARACTERS

PL-Admin supports uppercase English characters directly, and other 
8-bit characters indirectly.  Characters with decimal values of 128 
or higher are interpreted by PL-Admin as foreign characters.  
Strings 264 and 265 in the defaults.cpl file are used to translate 
foreign characters into known (8-bit) English characters.  String 264 
translates characters 128 to 191.  String 265 translates characters 
192 to 255.  

The first character in each string defines the delimiter character 
for the string.  The delimiter, used to indicate characters that 
should not be translated, cannot be a binary zero (0) or a 
double-quote (").  The next 64 characters represent decimal 
characters 128 to 191 for String 264, and 192 to 255 for String 265.  

To translate an upper ASCII character to an 8-bit character, enter 
the replacement value for the 8-bit character in the position in the 
string that corresponds to the 8-bit character value.  A valid 
replacement character is one uppercase letter (from A to Z) or one 
number (from 0 to 9).

Place the delimiter character in the position of any upper ASCII 
characters you do not want translated, or leave the position blank.  
Untranslatable characters are treated as white space.
  
For example, if decimal 128 should be viewed and indexed as a "C," 
and you use a hyphen as your delimiter, String 264 should begin 
like this:

264 -C---------------

Here is another example of the beginning of String 264:

264 -CUEAAAACEEEIIIAAE--OOOUU-OU----AIOUNN------

The first character after the string number and space is a hyphen (-).  
Therefore, the hyphen is the delimiter for this string.  The second 
character, in the character position 128, is "C."  This means that any 
occurrences of character 128 will be viewed by PL-Admin as the 
character "C."  Positions for the characters 145 and 146 are filled 
with the delimiter, so these characters will not be translated or indexed.

Note: Strings 264 and 265 should be set once, when the software is 
installed.  You may see strange behavior if these strings are modified 
after databases are created.


EXPORTING RECORDS IN ASCII FORMAT

Choosing "Export..." from the File menu displays an "Export" dialog 
box.  This dialog box enables you to send a range of records (by rank 
or ID number) to an ASCII file.    By clicking SELECT FILE, you can 
select an existing file or create a new file to copy the records to.  
If you select an existing file, you can append the new records to the 
end of the file, or you can overwrite what was in the file before by 
not checking the "Append to File" box.

Only choose "Export..." when a record is displayed in the Record 
Window.


HIT LIST FROM FILE

It is possible to create a special summary for each record in your 
database.  This summary will appear in the Hit List whenever the record 
is retrieved by a query.  There are two steps involved when you want to 
create your own Hit List summary for each record.  First, enter the 
following into your database's definition file:

HITLIST=FILE filename

where:
filename is the name of the file that contains the summary that will 
     appear in the Hit List for any record in the database that is 
     retrieved by a query.

Second, create the file containing the summaries for each record.  
This file will be read by PL-Admin as a binary file.  This file should 
include one summary for each record in the database.  The first summary 
in this file will be displayed whenever the first record is displayed 
in the Hit List.  The tenth summary will be displayed whenever the 
tenth record is displayed in the Hit List, and so on.

The information in the file you create needs to be correctly positioned 
so it will be displayed properly in the Hit List.  Wrapping the lines 
in this file is optional.  If you use carriage returns, each carriage 
return-line feed counts as two bytes in DOS.  On a Mac, each carriage 
return counts as one byte.

Note: You can terminate summaries that are smaller than the fixed 
maximum length with an ASCII 0.  The data after the 0 will be ignored.
Following is an example of the beginning of a file containing record 
summaries for a database.  

CplDiskArray Class Version 1.00/June, 1991                 90
       40         2000       Soviet Empire:The Rise and Fall of0     
       Independence:Now the Work Begins0       Devoured by Dreams?0 . . .

where:
CplDiskArray Class Version 1.00/June, 1991 must be in position 
     0 - 42 in this file; this is a constant
90 must start in position 60 and identifies the byte position 
     where the summary for the first record begins in this file; 
     this is a constant
40 must start in position 70 and indicates the maximum number of 
     bytes each summary can be; this variable can be set to any number
2000 must start in position 80 and indicates the total number of 
     record summaries contained in this file; as you add more records 
     to the database and more summaries to this file, increase this number
Soviet Empire:The Rise and Fall of0 must start in position 90 and 
     continue for 40 bytes.  The 0 assures that the spaces between the 
     end of this summary and the beginning of the next will be ignored;  
     this is the first record's summary


CREATING LINKS THAT WORK DATABASE-WIDE

You can configure WPL to display an additional menu item named Actions.  
This menu contains links that can be activated from anywhere within 
the database, provided a record is displayed in the Record Window.

To make the Actions menu appear, add the following line to your 
wpl.ini file.  The wpl.ini file is located in your Windows directory.

[wpl]
ActionsMenu=1

In the database directory, create a dbname.act file, using the 
following format.

fielded link description

For example, for the news database, our news.act file might look 
as follows.

C<d:\win30\notepad.exe>notes
D<5>display record 5

where:
clicking on notes in the Actions menu activates the command link 
     C<d:\win30\notepad.exe> to bring up notepad
clicking on display record 5 activates the document link D<5> 
     to display record 5


ENCRYPTION

Since encryption is not available in WPL 3.0, you should decrypt
your databases before indexing them for searching in WPL 3.0.
Please use the decryption feature that came with your Advanced
Authoring Tools.  Encryption for WPL 3.0 is under development.
We will let you know as soon as it is available.


KNOWN PROBLEMS IN WPL 3.00.30

When printing a List, fieldnames do not print, even if they are
turned ON for display.


The following settings in the definition file, as described in
Appendix A, are not yet implemented: hide_fields, admin_password,
and stemming=.


The Export feature in the File menu does not capture hypertext
link or character formatting markup (e.g., <D<2>>, <BI>, </BI>,
etc.)


If you Print to File instead of directly to a printer, select 
a printer font (one that has a printer icon next to it) in 
the Fonts dialog box off of the Print dialog box.  If you 
have difficulty printing directly to a printer while using
a software font, select a printer font.


The key combination CTRL-PgUp and CTRL-PgDn can cause a
distortion in the display of the Search Box, but does not 
otherwise have any adverse effects.


Avoid setting the default search mode to Table of Contents 
through the WPL.INI file.  When it is called up this way, 
the Table of Contents screen does not disappear to allow 
the records to be viewed; if you use this setting, you will 
need to drag the Table of Contents screen out of the way to 
view the record.


If you attempt to display a record that has been deleted, do
not use CTRL-Plus to display the next record in the database.
Instead, use CTRL-D, or select the record you want to view 
from the list.


Do not attempt to print from the image module if an image is not
being displayed.


The PL-Admin Verify feature may not function correctly on very
small databases.


WPL ignores the LOGON=N setting described in Appendix B of the
manual.


Appendix B does not describe all of the steps needed to make
WPL automatically display up to three files.  To use this 
feature, enter into the WPL.INI file the View1File, View2File, 
and View3File settings (as described in Appendix B of your 
manual).  Then, start up WPL and use the "Open General..." 
command to open the files you want opened up automatically.  
Once you have the windows opened and positioned on the screen,
use the "Save Settings..." command so WPL will know where to
the windows should be automatically placed the next time WPL
is started.

END OF README


