>Introduction
┌───────────────────────────────────────────┐
│ KP5 Help Document                         │
│ Copyright (c) 1991 by Peter Charpentier   │
└───────────────────────────────────────────┘

Documentation for KP5 version 5.07, January 1992.

This document describes the features and use of KP5, a keypunch
system for PC's and compatibles. It is included in the KP5 package
as KP5.DOC, and is also available online through the KP5 HELP
system.

KP5 is being distributed as shareware. This means that you are free
to try it out and pass it around, as long as it is understood that
if you decide to use it, you must register (and pay for) your copy.
Registered users are entitled to technical support and free
upgrades. If you do not have the registration form and disclaimer
(REGISTER.DOC), write to me, on paper or electronically, at the
address given in the "How to get HELP" section of this document.

This document is arranged as a set of 'topics' that describe the
day-to-day use of KP5.

I suppose that the way to begin describing this program is to state
what it IS, and what it is NOT, and where it belongs in a typical
data management operation.

WHAT IT IS:

KP5 is a two-pass data entry editor. It was designed to facilitate
the rapid and accurate entry and verification of data from well-
designed data collection instruments. The end products are ASCII
text files that may be processed by statistical or flat-file data
management packages.

WHAT IT IS NOT:

KP5 is not a general data base management program, although it has
within it a number of functions that are used to manage KP5 files.
KP5 is not a forms-style data entry program: you cannot
(efficiently) design data entry screens that resemble the data
collection forms, nor can you build a computer-assisted
interviewing system around KP5. If you require this type of data
entry support, you should use one of the commercial database
packages.

WHERE IT BELONGS:

KP5 is typically used as a data entry component in data management
systems for survey research projects. In such operations,
administrative functions -- anything involving subject contacts --
are managed using one of the commercial, business-oriented data
base packages (FoxPro, Paradox, etc.).  The volumes of research
data from interviews are entered and verified using KP5, then
regularly 'exported' to ASCII files. A statistical or flat-file
management package, SAS, for example, takes over from there, and is
used to maintain the master files for analysis.

Because of the cost and training involved with specialized key-to-
disk machines, many research projects now use service bureaus for
large batches of data. KP5 provides an alternative: using KP5 on
your own equipment, through data entry structures that you have
designed and understand, brings the entire data flow under your
control. The error detection and correction cycle can be as tight
as possible, because newly entered and verified records are
immediately available for processing. Quality control is up to you,
not an outside agency.

Some features:

   o All functions are accessed using a single set of drop-down
     menus.

   o Record sizes can be gigantic (32,000 characters).

   o No reasonable limit on file size.

   o A file may be set up in a matter of minutes.

   o Partial or 100% verification is supported.

   o A 'picture' may be designed that edits data type on input.

   o Data may be automatically duplicated between or within
     records.

   o Record keys may be made up of up to 255 characters among up to
     10 fields located anywhere within the record.

   o Two-level range checking is supported. Any single or multiple
     character field may be defined to have a valid-value range, as
     well as a missing-value range.

   o Files may be password-protected.

   o Record keys may be validated against a master index file as
     they are entered.

   o KP5 data sets may be restructured, copied, merged, imported
     from ASCII files, and emptied.

   o Session statistics are automatically saved to disk, in dBase-
     III or ASCII text format.

   o Will work on floppy-disk systems with 350K memory (400K
     recommended).

   o KP5 is 'operator-tolerant': failure to properly exit the
     program should not result in data loss.
>What's New
This section describes new features since version 5.05 (the first
general distribution version of KP5).

Version        New features                  See topic:

5.06           New UTILITES menu options:    ■The UTILITIES menu
Oct 1991       -Delete Exported
               -Global Flag Set

5.07           Numeric data entry fields     ■Numeric fields
Jan 1992       are now supported.

               dBase-III or ASCII            ■Session statistics
               'session statistics' files     files
               automatically written.

               New FILE menu option:         ■Shelling to DOS
               -Shell to DOS

               Verification 'bypass'         ■The TABS mask
               fields may be defined,         element
               for which verification
               is not enforced.
>How to Start KP5
This discussion assumes that KP5 has been installed on a hard disk.
If you are using floppies, refer to the text file README.DOC for
suggestions on how to use floppy diskettes. Assuming KP5 has been
properly installed, and the program directory is on the
workstation's PATH, the simplest way to start KP5 is to issue the
command:

      ┌────────────┐
      │   kp5      │
      └────────────┘

If the KP5 program directory is NOT in the PATH, you would have to
include the program directory in the command:

      ┌───────────────┐
      │   c:\kp5\kp5  │
      └───────────────┘

This will load the program with no files open, so you will have to
select Open from the FILE menu in order to get to work (more on
that below).

You may also specify, on the command line, which KP5 file you wish
to process:

      ┌─────────────────────────┐
      │  kp5 filename username  │
      └─────────────────────────┘

In this syntax, filename is the DOS path plus KP file name, and
username is you (1-10 characters). For example:

      ┌──────────────────────────────────┐
      │  kp5 \kp5\files\studyx theodore  │
      └──────────────────────────────────┘


DOS Note: If no username is given, KP5 looks for a DOS environment
          variable named USERNAME. If it is defined, KP5 will use
          it, and not prompt the user. You use the SET command to
          define the environment variable from DOS. For example:

          set username=Peter
>Complete Command-Line Syntax
The complete KP5 command-line syntax is as follows:

  ┌───────────────────────────────────────────────────────┐
  │  KP5 [filename [username]] [-B] [-M] [-C] [-S]        │
  │                            [-X] [-V] [-N]             │
  │                            [-R] [-T] [-E]             │
  │                            [-A] [-O]                  │
  │                            [-K:<valid-key-index>][-I] │
  └───────────────────────────────────────────────────────┘

  switches:

    -B   use default black & white color set for CGA/EGA/VGA
    -M   use default monochrome ('green screen') color set
    -C   use default polychrome color set
    -S   compensate for 'snow' on CGA displays
    -X   export records and quit
    -V   select Verified records (use with the -X switch)
    -N   select New or modified records (use with the -X switch)
    -R   restricted editing (forced entry of entire record)
    -T   total verification mode (records must be 100% verified)
    -L   record session information in the Log file (KP5.LOG)
    -E   entries must be confirmed by pressing the Enter key
    -A   write session statistics in ASCII format instead of dBase
    -O   nO session statistics file will be written
    -K:<valid-key-index>  open a 'valid-key' index file
    -I   display the compile date, version, and registration

The -B, -M, and -C switches are used to override the default and
user-designed colors. The colors used by KP5 are stored in a
configuration in the local directory, and so become the default the
next time that KP5 is loaded from that directory.

The -X switch is used to export records in 'batch' mode. See "How
to Export" topic for details.

The -V and -N switches may be used to select verified and/or new or
modified records for batch export. They have meaning only if the -X
switch is also specified.

The -R switch is for sadistic administrators.  It invokes a
'restricted editing' mode which disables most of the cursor
movement keys, and which requires the user to enter complete
records.  The user may go backwards to correct an error, but cannot
go forward using the arrow or tab keys.

The -L switch tells KP5 to maintain a log file. The log file is a
running account of KP sessions, including dates and times each KP
file is opened and closed, as well as selected file statistics
(#records entered, verified, deleted, etc.).  The log file is named
KP5.LOG, and resides in the KP5 program directory.

The -A and -O switches determine what type of 'session statistics'
file will be written, if any. The default is dBase-III compatible
(KP5STATS.DBF), but -A specifies ASCII text (KP5STATS.DAT) and -O
suppresses statistics file generation.

The -K: switch opens a valid-key index file. This is an ordinary
index file associated with some 'master' KP5 file, and will be used
to validate record keys as they are input. You must provide the DOS
path and file name, eg, -K:C:\KP5\FILES\MASTER.

The -I switch results in a display which shows the KP program
version number, the registration number, and the registree's name.

The -E switch causes KP5 to require that the user press the Enter
key to confirm each entry, including menu selections. This also
disables the AUTOWRITE feature: the Enter key must be pressed after
a record has been filled in. Normally, KP5 automatically accepts
entries as they are filled out.

If you load KP5 with a ? as the only parameter, a screen showing
the command-line switches will be displayed.
>The KP5 Interface
The KP5 interface consists of a single drop-down menu system, a
series of dialog screens, and a record editor.

THE MENU SYSTEM

KP5 functions are accessed through a system of drop-down menus.
This system is activated when KP5 is started.

If the menu bar is not on-screen (for example, during data entry),
you may usually activate it by pressing F10.

To move between menus, use the left or right arrow keys, or press
the space bar. To select an option from a menu, either highlight
the choice using the up and down arrow keys and press Enter, or
simply press the highlighted 'hot key' for the option. If KP5 was
started using the -E command-line switch, you will have to press
ENTER after the 'hot key'.

Not all menu items are active (selectable) all the time. For
example, if there is no file open, the DATA ENTRY menu has no
meaning and so none of its selections will be active.

There are five menus:

FILE           Functions that operate on the file or system
               level:quit, open/close, export to ASCII, list,
               printer setup, help.

DATA ENTRY     Access to records: enter new records, modify
               existing records, verify, look.

RECORD         Operations on the current record: delete, change
               record key, mark, blank, undo.

FEATURES       KP5 global features: sound, lock keyboard on error,
               allow entry into protected fields, define the 'fill
               character'.

MASK           Edit the five data entry mask elements: picture,
               tabs/attributes, minimum valid, maximum valid,
               minimum missing.

UTILITIES      Access to seldom-used but vital functions: pack,
               reindex, restructure, copy, empty, remove exported,
               global flag set, merge, set password, list mask
               structure, colors.

Two menu selections have 'really hot' keys assigned to them. When
a 'really hot' key is pressed, the associated function is
activated, no matter what you are doing at the time (eg, the menu
does NOT have to be displayed). The 'really hot' keys and their
functions are as follows:

Alt-P     Printer Setup
Alt-F1    Online HELP document (see "how to get HELP")

DIALOGS

There are a number of 'dialog boxes' or screens that KP5 uses to
get information from you (file names and the like). There are
certain keys that behave consistently during these occasions, and
they are:

F1             Context-sensitive HELP (see "How to get HELP").
F2             Finish the dialog and accept input.
Esc            Finish the dialog and cancel.
Enter          Finish field and advance to next field.
Tab            Advance to next field
BackTab        Go to previous field
Ctrl-Backspace Erase (blank) the current field.
F10            Activate the menu.
arrows         Move up or down within the dialog.

Normally, the cursor will automatically advance when an item is
completely filled in. This is called the 'autowrite' feature. If
the autowrite feature is disabled, the user must press the Enter
key to confirm each entry. The autowrite feature may be disabled
either through the FEATURES menu, or using the -E command-line
switch. Within dialogs, the usual editing keys are active: Ins,
Del, Backspace, left and right arrows, Home, and End.
>How to get HELP
There are five levels of HELP available. The first is a 'context-
sensitive' system activated by pressing F1. This system tries to
provide help on whatever it is you are doing at the time. If no
specific help is available, it displays general keyboard-usage
information.

The second kind of HELP is accessed by selecting HELP DOCUMENT from
the FILE menu, or by pressing Alt-F1: this provides access to the
online help document, which is what you are reading right now. You
may print a single topic, or the entire document, from within this
HELP facility. The file KP5.DOC is generated in this manner.

The third HELP level comes in the form of 'item information' boxes
that are displayed whenever you are required to provide information
to KP5. For example, item information boxes guide you through the
process of structuring a data set.

The fourth kind of HELP is a listing facility that is loaded by
pressing SHIFT-F1 whenever you are entering a file name, or looking
for an existing record key. It presents a menu from which you may
select. In the case of KP5 files, selected information from the
file headers (label, number of records..) will also be displayed.

The final kind of help is me:

       ┌───────────────────────────┐
       │  Peter Charpentier        │
       │  47 Meeting House Hill Rd │
       │  Durham, CT 06510         │
       │                           │
       │  CompuServe: 70053,705    │
       └───────────────────────────┘

Be sure to indicate which version of KP5 you are using (select
About.. from the FILE menu).
>How to set up a new KP5 file
Select Open from the FILE menu. A dialog box will be displayed,
into which you must enter the DOS directory and KP5 file name. For
example, to create a file named STUDYX in the C:\KP5\FILES
directory, the dialog box will look something like this:

       ┌──────────────────────────────────────┐
       │    KP5 File  C:\KP5\FILES\STUDYX___  │
       └──────────────────────────────────────┘

If KP5 finds a file with the specified name, it will be opened.
However, if the file name is not found, you will be asked if you
want to create a new file.

When you respond with Y to that prompt, the FILE STRUCTURE dialog
will be displayed. Into this screen you must enter:

     1) The CARD SIZE
     2) The number of CARDS per RECORD
     3) The position(s) and length(s) of the RECORD KEY(s)

This seems a good place to explain the basic elements of the KP5
file structure, so here goes.

RECORDS AND CARDS EXPLAINED

RECORDS are made up of one or more CARDS. In the old days (10 years
ago), cards were made out of paper and had 80 columns. If your
'logical record' had more than 80 columns, you had to break it up
into two or more cards, or 'physical records'. KP5 uses this
paradigm, even if it seems a bit dated. Of course, KP5 cards may be
of any reasonable length, and there is no law that says you ever
have to use more than one card per record. However, you may want
to, and here's why:

If you have experience in survey research, you know that, during
the pretest period, the data collection instruments tend to change
dramatically. It is usual to place the column specifications on the
data collection form, generally in the right margin next to the
data entry blanks. As the form undergoes revisions, you continually
have to change column specifications, and if you are committed to
just one large card per record, huge blocks of columns may have to
be changed. This gets a little crazy after a while, not to mention
expensive. Also, column specifications like '5385-5387' can be hard
to place in the margin.

We have found that a good strategy is to use a moderate card size
of (say) 160 or 240 columns, but leave a blank 'expansion zone' at
the end of each card. For example, if the card size is 240, we
start a new card when the current column gets to around 200. With
this setup, inserting new questions into a form involves reprinting
a few pages, not the entire form. Similarly, the input programs
used to read the records are easier to modify when insertions or
deletions affect cards, not entire records.

Another reason to stay away from huge card sizes is that the
software used to read the ASCII files created by KP5 may have some
record length restriction. You will probably never get into
software trouble if you keep the card size below 256.

To complete the file structure, you must provide the position and
length of one or more RECORD KEYS. These are explained next.

RECORD KEYS

A requirement of KP5 files is that each record (NOT each card) must
have a unique record key. KP5 files are always sorted (indexed,
actually) by the record key. The record key is usually a subject ID
code, but sometimes two or more fields must be combined to form a
unique key. For example, in a hospitalizations data set, the unique
key may be hospital unit number plus date of admission.

Each record key is defined by 1) position and 2) length. KP5
assumes that all record keys will be located on the first card. If,
for some reason, you have a record key on some other card, you must
add the lengths of the preceding card(s) to its position. For
example, if the card size is 240, and the key is on card 3, column
11, the key position will be 240+240+11=491.

AN EXAMPLE

Here is a reasonable facsimile of the file structure dialog screen
for a hypothetical STUDYX. This file has two record keys: a five-
digit subject ID at column 1, and a date (yyyymmdd) at column 23.

 ┌─────────────────────────────────────────────────────────────┐
 │                data set label  KP5 file example             │
 │                     card size  240                          │
 │    number of cards per record  8                            │
 │           total record length  1920                         │
 │                                                             │
 │    key(s):  position   length       position   length       │
 │    ─────┬──────────────────────┬─────────────────────       │
 │         │1. 1          5       │ 6.                         │
 │         │2. 23         8       │ 7.                         │
 │       ....                    ....                          │
 └─────────────────────────────────────────────────────────────┘
 The FILE STRUCTURE Dialog Screen

(The above screen is squashed -- the real thing allows for up to
ten keys)

By the way, if you panic at this stage, press the Esc key.

If you don't panic, press F2 when you are finished entering the
record key(s), and the file will be created. A default mask will be
constructed, but you will probably want to fine-tune it a bit (see
"Designing the Mask").

The file is now ready for data entry.
>How to open a KP5 file for data entry
One way to open a file is on the command line; see "how to start
KP5" for details. The other way is to select Open from the FILE
menu. When you do this, a dialog box will pop up, into which you
must enter the DOS directory and KP5 file name. For example, if the
file is named STUDYX and is located in a directory named
C:\KP5\FILES, the completed dialog box will resemble the figure
shown below.

 ┌────────────────────────────────────┐
 │   KP5 file  C:\KP5\FILES\STUDYX___ │
 └────────────────────────────────────┘
 OPEN FILE Dialog

If you like, you may press Shift-F1 to select from a list of all
KP5 files found in the specified directory (eg, enter C:\KP5\FILES,
or some other directory name, then press Shift-F1). You may open
any file on this list by selecting it with the up or down arrow
keys, then pressing Enter.

If, after entering the name of a file that SHOULD exist, you get an
"Ok to create new file?.." prompt, respond with N! The reason for
the prompt is that KP5 did NOT locate the file in the specified
directory, and assumes you want to create a new file. If you really
do want to create a new file, see that topic.
>How to enter new records into a KP5 file
There are four steps involved in opening a file and entering new
records into it. These are discussed below.

Step 1. OPEN THE FILE

Follow the instructions in "how to open a file for data entry".

Step 2. SELECT 'ENTER NEW RECORDS' FROM THE DATA ENTRY MENU

A RECORD KEY dialog, similar to that shown below, will be
displayed.

┌────────────────────────────────────────────────────────────┐
│ ┌───────record key────────┐    ┌───current record key────┐ │
│ │                         │    │ 00001                   │ │
│ │                         │    │ 19910325                │ │
│ └─────────────────────────┘    └─────────────────────────┘ │
│┌──────────────────────────────────────────────────────────┐│
││     mode entry                                           ││
││ shift-f1 browse record keys                              ││
││      f10 main menu                                       ││
││    ctrl. retrieve next record                            ││
││    ctrl. retrieve previous record                        ││
││  ctrl<─┘ access current record                           ││
││      Esc return to main menu                             ││
│└──────────────────────────────────────────────────────────┘│
└────────────────────────────────────────────────────────────┘
The RECORD KEY Dialog Screen

There are two 'record key' boxes in this screen: the right-hand box
shows the current record's key, and the left-hand box is a data
entry area into which you enter the key for the new record. The
current record key is explained in "How to verify records" topic --
it is not really important when you are creating new records.

Step 3. ENTER THE RECORD KEY

KP5 will search the file for the record key, and if it is NOT
found, the record will be added to the data set. If the record key
IS found, you will be notified, and asked if you want to MODIFY the
existing record.

Step 4. KEY IN THE RECORD

Once the record has been added, control will pass to the RECORD
EDITOR. This editor is used for entering, verifying, and modifying
records. The cursor will be placed at the first normal, or
'unprotected', data entry position. Now what you do is, naturally
enough, key in the record. See the next topic for a description of
how the editor behaves during data entry.
>The Record Editor
The record editor screen looks something like this (the example
shown is a little squashed -- the real thing has 80 columns):

┌───────────────────────────────────────────────────────────────┐
│peter studyx 3 records (0 deleted)      data entry/modification│
│┌───────────────────────────────────────────────────┬─────────┐│
││ f1 help   f4 wrap√  f6 fill '9' f8 key    f10 menu│■Error   ││
││<─┘ save  sf4 prot√ sf6 dup      f9 mark           │ Message ││
││Esc abort af4 lock   f7 current sf9 delete af9 undo│         ││
│└───────────────────────────────────────────────────┴─────────┘│
│1        10        20        30        40        50        60> │
│╞═══╤════╪════╤════╪════╤════╪════╤════╪════╤════╪════╤════╪═╤═│
│00002                 19910105                                 │
│                                                               │
│╞═══╧════╪════╧════╪════╧════╪════╧════╪════╧════╪════╧════╪═╧═│
│────────────────╥──────────┬──────────╥─┬─┬─┬─╥─────┬───┬────┬─│
│0000219910105   ║PETER     │06/01/1991║v│X│M│D║  241│  2│   1│*│
└───────────────────────────────────────────────────────────────┘
The RECORD EDITOR Screen

The data entry area is between the 'rulers'.  This is essentially
a window into the record. For records with card sizes exceeding 80
columns, the window will 'slide' through the record as you key in
the record. The data entry area will display up to twelve lines
(cards) at a time.

An 'information box' is displayed above the data entry area. The
left portion of this box shows the active function keys. The right
side is a message area, used by the range-checking and verify-
error-condition routines.

At the bottom of the screen is a 'status line'. The following items
are displayed in the status line:

     - the record key
     - username
     - date created/modified
     - record flags (V-verified X-exported D-deleted M-marked)
     - the absolute record position
     - the card number and column
     - whether the current record position has been verified
       (indicated by a diamond in the extreme lower right corner)

THE KEYBOARD DURING DATA ENTRY

During data entry, certain keys have special actions. These are
listed in the upper information box, but in abbreviated form. A
more detailed explanation of the special keys is herein provided.

F1   Help (shows the data entry specifications for the current
     position).

F4   Switches the display mode between 'normal' and 'wrap'. In
     'normal' mode, the data entry window slides to the right or
     left as you enter data. One card always takes up one display
     line in normal mode. In 'wrap' mode, cards are wrapped at the
     screen borders, each card may occupy two or more display
     lines, and the data entry window will not shift right or left.

sF4  (Shift-F4) Enables or disarms the 'protect' feature. When
     protect is disarmed, data entry is allowed into protected
     areas.

aF4  (Alt-F4) When a range check or verification error condition
     has been raised, pressing Alt-F4 overrides the error condition
     and accepts the entered value. When there is no error
     condition raised, Alt-F4 disarms the keyboard locking feature.
     When the lock feature is disarmed, KP5 will report, but not
     enforce, data entry and verification errors.

F6   Pressing this key causes a designated 'fill character' to be
     copied into the current record. Copy proceeds from the current
     position to the next tab stop (or the end of the current card,
     if no tabs are assigned).

sF6  (Shift-F6) This key causes whatever was entered into the
     PREVIOUS record (during the current data entry session) to be
     copied into the CURRENT record. The copy proceeds from the
     initial position to the end of the data entry field, as
     defined in the mask. If the cursor is not positioned in a
     multiple-column field, a single character will be copied. Old-
     timers recognize this function as the DUP key.

F7   Activates the 'show current' feature. This causes whatever was
     in the current card BEFORE the data entry/verification session
     to be displayed below the data entry window. This feature is
     automatically activated when the verify error condition is
     raised.

F8   Allows you to change the record key value.

F9   Sets or releases the MARK flag for the current record. This
     may be used to identify problem records during data entry.
     Marked records may be listed and shown to a data manager or
     administrator for review.

sF9  (Shift-F9) Sets or releases the DELETE flag for the current
     record. Deleted records must be removed in a separate step,
     using the PACK procedure on the UTILITIES menu.

aF9  (Alt-F9) This is the UNDO key: any changes made while in the
     record editor will be 'undone', eg, the record will be
     restored to its pre-edit state.

F10  Activates the main menu. Each of the actions carried out by
     the function keys explained in this section may also be
     selected from the RECORD or FEATURES menus. You may also
     select Help from the FILE menu, to check out this document
     while entering data.

The following additional keys have special meaning:

Enter          Ends data entry and accepts the record.
F2             Acts as an alternate Enter key.
F3             Exit to DOS.
Esc            Cancels data entry.
Tab            Moves cursor to the next tab stop (if any).
Shift-Tab      Moves cursor to the previous tab stop.
Numpad-Plus    Acts as an alternate Tab key.
Numpad-Minus   Acts as an alternate BackTab key.

(Numpad-Plus and Numpad-Minus are the '+' and '-' keys on the
numeric keypad)

RANGE CHECK ERRORS

It is possible to set up the data entry mask so that valid-value
and missing-value ranges are checked during data entry. If the
range check error condition is raised, the keyboard will (normally)
lock up, and a nasty message will be displayed in the information
box. You have two options: 1) if you goofed, retype the field, or
2) if you need to override the error condition, press Alt-F4. If
the error indicates a coding mistake, and the chucklehead who
filled out the form is not around to resolve it, one thing you
might do is leave the field blank (or set it to a missing value),
MARK the record by pressing F9, then list the marked record(s) at
the end of your data entry session. Put those yellow sticky things
all over the form and place it aside.

You may disarm the keyboard-lockup-on-error feature at any time
using the Lock option on the FEATURES menu. When this feature is
disarmed, range check errors are reported in the information box,
but not enforced.

When the cursor is located on a field for which an error condition
has been raised, you may press F1 to diagnose the error. A
'details' box will be displayed, showing the defined valid and
missing value ranges, along with the entered value.

>Verifying records
Verifying records is pretty much just like entering new records.
You start a verification session by selecting Verify from the DATA
ENTRY menu. The record key dialog pops up, and you will be expected
to enter the key of an existing record to verify. Since you will be
entering existing keys, the 'Current Key' box now has some
relevance, and so will now be explained.

HOW TO SELECT AN EXISTING RECORD KEY

The most direct way to select an existing record key for
verification (or modification) is to simply type it. However, you
may also locate and retrieve record keys by 'cruising'. Here's how.

There is always a 'current record', and its key is shown in the
right-hand box on the record key dialog screen. You may change the
current record by pressing Ctrl-left arrow (obtain the previous
record) or Ctrl-right arrow (retrieve the next record). You may
access (verify) the current record by pressing Ctrl-Enter.

Another way to locate record keys is to press Shift-F1. This will
display the record keys on a menu from which you may make a
selection. The record key browser can select all keys, or a subset
of keys based upon the record flags (exported / verified / marked
/ deleted). One obvious use of this screening capability in verify
mode is to browse only unverified records. The browser operates
much faster when you opt for all keys.

VERIFICATION ERRORS

During verification, the range-checking error handler is replaced
by a verification error handler. This procedure raises the
verification error condition whenever a keystroke does not agree
with what was entered during the first pass. As with range checks,
the keyboard will lock up, and you must either retype the old
keystroke, or press Alt-F4 to accept the new keystroke.

Records may be partially or 100% verified. You may partially verify
a record by typing in a portion of the record, then pressing Enter.
The arrow keys (NOT the Tab keys) may be used to skip over areas
that are not to be verified. KP5 keeps track of the verification
status of every character in every record, so it knows if a record
has been fully verified. Whenever the verify flags are printed or
displayed, lower-case 'v's indicate partial verification, while
upper-case 'V's indicate 100% verification. If the -T the command-
line switch was used when KP5 was loaded, 100% verification will be
enforced (see "Complete command-line syntax").
>Modifying records
Modifying records is easy: select Modify from the DATA ENTRY menu,
then enter the key of the record you wish to modify. You may use
the methods described under verification to locate record keys.

HOW MODIFYING AFFECTS THE RECORD FLAGS

When records are modified, the export flags are set to 'not
exported'. The reason for this is that it is routine for
administrators to regularly export to ASCII only those records
flagged as verified but 'not exported yet'. By setting modified
records to 'not exported', the regular export runs will include not
only new, but modified records as well. The verification flags are
not changed when records are modified, although there is nothing
wrong with re-verifying a drastically modified record, just to be
safe.
>Looking at records
There are times when people, especially administrators, need to
just LOOK at records, without the possibility of (accidentally)
modifying them. For this, select Look from the DATA ENTRY menu.
'Look' mode is similar to modify mode, except that it is impossible
to actually modify data. An added feature in Look mode is that,
even when the record editor is running, the Ctrl-left and Ctrl-
right keys are active, allowing you to retrieve adjacent records
without exiting to the record key dialog.
>Exporting records to ASCII files
As I have probably mentioned a few dozen times, the idea behind KP5
is to prepare ASCII text files for processing by statistical or
data management software.

KP5 files (files with names like *.KPF) are NOT ASCII text files.
They must be 'exported' to ASCII before they can be used. There are
two ways to export records: you may do it interactively, using the
menus, or you may do it in batch mode, by using KP5 command-line
options. Following is a discussion of each of these methods.

HOW TO EXPORT USING THE MENUS

Select Export from the FILE MENU. The export dialog screen will be
displayed. Into this screen you specify the name of the ASCII file
to be created, as well as any record selection criteria. A
facsimile of the export dialog screen is shown below.

┌──────────────────────────────────────────────────────────┐
│ export (ASCII) file name C:\KP5\FILES\STUDYX.DAT________ │
│                                                          │
│ exported  N     minimum date  __________                 │
│ verified  Y     maximum date  __________                 │
│   marked __                                              │
│                                remove trailing blanks? N │
└──────────────────────────────────────────────────────────┘
   The EXPORT Dialog Screen

The information that you enter into the dialog box is as follows.

   o The name of the ASCII file to be created.

   o Whether to select records based on whether or not they have
     already been exported (Y-select EXPORTED records, N-select
     UNEXPORTED records, blank-ignore the export status).

   o Whether to select records based on whether or not they have
     been verified (Y-select 100% VERIFIED records, N-select
     UNVERIFIED records, P-select PARTIALLY or 100% verified
     fields, O-select partially verified records ONLY, blank-ignore
     verification status).

   o Whether to select records based upon the MARK flag (Y-select
     MARKED records, etc.).

   o Whether to select records based upon the date they were
     created or last modified.

   o Whether to remove trailing blanks from the exported ASCII
     records. Depending on the record layout, this may save a
     considerable amount of disk space.

In the above example, records that have been verified but not yet
exported will be selected. This is the usual selection criterion
for exported data.

Deleted records are NEVER exported.

The ASCII file record length will be determined by the CARD SIZE
value of the KP5 file. The number of physical ASCII records
generated per logical record will be the same as the CARDS PER
RECORD value.

HOW TO EXPORT RECORDS IN BATCH MODE

As explained "The complete command-line syntax", the -X, -N, and -V
command-line switches may be used to generate export ASCII files.
Thus, it is possible to write batch files that export records, then
feed them to other programs that add them to master files, check
for logical consistency errors, etc.

In batch mode, the export file name is always <filename>.DAT, where
<filename> is the name of the KP5 file. For example, the command
line:

     kp5 c:\kp5\files\studyx peter -x -n -v

..will generate an ASCII file named c:\kp5\files\studyx.dat. That
file will include all the verified records that are new or
modified. WARNING: in batch mode, the target ASCII file will be
replaced if it already exists.
>Listings
KP5 supports a variety of listings, or reports. Before you generate
a report, it is a good idea to make sure the printer is correctly
defined (see "Printer Setup").

Select List from the FILE menu. A pop-up menu, providing the report
options, will be displayed. There are three kinds of reports:

   o A 'basic' listing that describes the file structure, and shows
     record counts (total, exported, verified, deleted, marked).

   o An 'abstract' listing that includes a file structure report
     plus a list of record keys and flags.

   o A 'full' listing that includes a file structure report plus a
     listing of records.

The abstract and full listings may be restricted to a subset based
upon record flags, user name, and/or date of last access.

If you select either abstract or full, the listings dialog screen
will be displayed. The purpose of this dialog is to allow you to
enter a record-selection criterion. A reasonable facsimile of this
screen is shown below.

┌──────────────────────────────────────────────────────────┐
│               Printer type HP LaserJet/DeskJet           │
│                Destination Printer                       │
│           Extended Charset Yes                           │
│──────────────────────────────────────────────────────────│
│ Full      line size (80/132) 80                          │
│                                                          │
│ exported __     minimum date __________                  │
│ verified __     maximum date __________                  │
│   marked __                                              │
│  deleted __             user __________                  │
└──────────────────────────────────────────────────────────┘
The LISTINGS Dialog Screen

For full listings, and depending on the printer type and card size,
you may be asked to specify a LINE SIZE. If you enter 132 columns,
a slightly more readable printout will be generated.

The remaining items are used for restricting the list to subsets of
records. The criteria are ANDed together. For example, if you enter
PETER for 'user name' and enter N for 'verified', you will obtain
a listing of records entered by PETER that were not verified.
Criteria that are left blank will be ignored. For example, Y for
'verified' selects verified records, N selects unverified records,
and blank causes verification status to be ignored.

If you don't like what you see regarding printer type and printout
destination, press F10, select Printer Setup from the FILE menu,
and change it (or press the 'really hot' key, Alt-P). You will be
returned to the report options dialog screen right where you left
off.
>Printer Setup
The Printer Setup option on the FILE menu allows you to specify 1)
what kind of printer you have, and 2) where the printout should be
directed (eg, to a file or to the printer). The PRINTER SETUP
dialog box is shown below.

┌───────────────────── Printer Setup ─────────────────────┐
│┌───────────────┐                                        │
││Exit           │                                        │
││Type of printer│      Printer type  HP LaserJet/DeskJet │
││Destination    │       Destination  Printer             │
│└───────────────┘  Extended Charset  Yes                 │
└─────────────────────────────────────────────────────────┘
The PRINTER SETUP Dialog

The dialog is controlled by the pop-up menu at the left. Press T to
change the printer type, and D to change the printout destination.
Press E to exit and save the definitions. The printer setup
information is saved in the KP5 configuration file.

The various printout-generating dialogs in KP5 display the current
printer setup information. This is to give you a chance to change
it, by pressing F10 and activating the menu system, before
printing.
>Designing the Mask
The data entry 'mask' consists of five elements, or records:

   o A PICTURE that determines what kind of character (if any) can
     be entered into each position.

   o A TABS/ATTRIBUTES element that defines the tab stops, as well
     as a number of special 'attributes' that a record position may
     have.

   o A MINIMUM VALID record that contains lower limits for 'valid'
     (non-missing) ranges.

   o A MAXIMUM VALID record that contains upper limits for valid
     ranges.

   o A MINIMUM MISSING record that contains the lower limits for
     missing value ranges.

These elements are edited using the 'mask editor', which is
available from the MASK menu. Modifying a mask element is very much
like entering a data record.

It is not necessary to modify any of the mask elements, as KP5 will
cook up a default set for you. However, most users feel the need at
some point. The general usage of the editor is explained in "The
Mask Editor", and details for using the editor for each of the mask
elements are given in separate topics.
>The Mask Editor
The Mask Editor is the means by which the five mask elements may be
modified to fit your record structure.

No matter which element is being edited, there are certain keys
that behave similarly. These are explained below.

Enter     Pressing Enter causes the current mask definitions to be
          save (on your approval), and exits the mask editor.

F2        Same action as the Enter key.

Esc       Cancels mask edit.

sF3       (Shift-F3) Switches between the five elements,
          maintaining the cursor at its current position.

F1        Displays a HELP screen that is specific to the current
          mask element.

cF1       (Ctrl-F1) Switches the contents of the 'information box'
          at the top of the mask editor screen.

F10       Activates the menu.

Details on how to use the Mask Editor for each of the mask elements
are provided in separate topics.
>Mask Editor: The Picture mask element
The PICTURE is probably the most important mask element. It is used
not only to define the kinds of data that may be entered, but also
to determine what areas may be used for data entry.  A picture
editing screen is shown below.

┌──────────────────────────────────────────────────────────┐
│┌────────────────────────────────────────────────────────┐│
││           @ any character       ! uppercase            ││
││ f1 help   9 numeric (0-9)       ^ nonblank character   ││
││cf1 more.. # numbers (0-9,blnk)  $ nonblank+uppercase   ││
│└────────────────────────────────────────────────────────┘│
│1        10        20        30        40        50      >│
│╞═══╤════╪════╤════╪════╤════╪════╤════╪════╤════╪════╤═══│
│99999!@@@@@@@@@@@@@@@@99999999@@@@@@@@@@@@@@              │
│@@@@@@#############################!@@@@@@@@@@@@@@@@@@@   │
│╞═══╧════╪════╧════╪════╧════╪════╧════╪════╧════╪════╧═══│
│Tab Prot vCpy Strt End kyCpy                   1    │1  │1│
└──────────────────────────────────────────────────────────┘
The PICTURE Editor

If you look at the default picture for any KP5 file, you will see
a record that is filled in with '@'s. The @ tells KP5 to accept ANY
character into that data entry position. Other so-called 'editing
characters' have different meanings:

@    - any character
9    - digits (0-9 only)
#    - numeric characters (0-9, blank, '+', '-', and '.')
^    - any non-blank character
!    - any character; will be converted to uppercase
$    - any non-blank character; will be converted to uppercase

These characters are displayed in the 'information box' at the top
of the PICTURE editing screen.

Modifying a mask is simply a matter of entering the appropriate
editing characters into the proper places in the record. If a
character is entered into the mask that is NOT one of the above
editing characters, that position will be considered a 'protected
field'.

What is a protected field? I hear you ask. Read on:

PROTECTED FIELDS

A 'protected' field is a region into which data entry is normally
prohibited. To illustrate, consider the scenario described in the
section about setting up new files. Under that scheme, the card
size was 240 columns, but most cards were blank starting around
column 200, to allow for 'expansion' within the record. Those blank
areas should be protected from data entry, at least until the
expansion takes place. Protected areas are usually blank, but they
may contain data that is to be 'hard wired' into each record. For
example, you may want to place a constant 'file code', or 'record
layout code', somewhere in each record. This code will be the same
for each record.

It is possible during data entry to temporarily 'unprotect' a
protected area.

Defining protected fields is usually accomplished by typing
whatever it is that is supposed to be there. For example, use the
space bar for blank protected fields, type 'A123' if a file code is
supposed to have that value, etc. The only problem that should
arise is in the case where a protected field is supposed to contain
one of the editing characters (say that the file code is 'A009').
In that case, you will have to manually protect the position(s).
You do that by pressing Ctrl-F4, which is one of the 'attribute
function keys' that are shared between the PICTURE editor and the
TABS/ATTRIBUTES editor (see the discussion of the TABS/ATTRIBUTES
editor).

Protected areas appear in the PICTURE editor in reverse video. You
may also verify that a position is protected by looking at the
'attribute status' display at the bottom of the screen. All of the
possible attributes are displayed in this line, and the attributes
for the current position are highlighted and in uppercase.

SPECIAL KEYS FOR THE PICTURE EDITOR ONLY

The PICTURE editor sports an enhanced set of editing keys, at least
compared to the data entry record editor. Insert mode and
destructive deletes are supported, so columns may be shifted left
or right as you wish. Ctrl-End will blank out (protect) the rest of
the current card. You may also insert and remove entire cards.

All of the special keys are explained in a special HELP screen
available by pressing F1.

It is important to remember that the PICTURE editor ONLY affects
the data entry mask, and NOT the actual data. For example,
inserting a new card in the PICTURE will NOT insert blank cards in
the actual records. The number of cards in the file structure will
remain the same (cards below the insertion point will be shifted
down, and the last card will be removed). If you want to add or
remove columns or cards in the data set, use the KPI utility
program that is shipped with KP5.
>Mask Editor: The Tabs/Attributes mask element
Each position in a KP5 record may have any of five 'attributes':
tab, vertical copy, key copy, field start, and field end. In the
TABS/ATTRIBUTES editor, you set attributes by typing in 'surrogate
characters' for each of the attributes. These are: t, v, k, n, b,
[, and ], as shown below in the sample TABS/ATTRIBUTES mask editor
screen.

┌──────────────────────────────────────────────────────────┐
│┌────────────────────────────────────────────────────────┐│
││                            b bypass verify  f1 help    ││
││ t set tab v vertical copy  [ field start   cf1 more..  ││
││ n numeric k key copy       ] field end                 ││
│└────────────────────────────────────────────────────────┘│
│1        10        20        30        40        50      >│
│╞═══╤════╪════╤════╪════╤════╪════╤════╪════╤════╪════╤═══│
│kkkkk     [   ]       kkkkkkkkt   bbbbbbbbbbbbbbbbbbbbb   │
│vvvvvt             t                                      │
│vvvvvt                                                    │
│╞═══╧════╪════╧════╪════╧════╪════╧════╪════╧════╪════╧═══│
│Tab Prot Vcpy Strt End kycpy                   1    │1  │1│
└──────────────────────────────────────────────────────────┘
TABS/ATTRIBUTES mask editor

TABS

To set a tab stop, enter a 't' in the appropriate position.

KP5 will beep when the cursor meets a tab stop during data entry,
so many users set tab as audible cues that indicate to the data
entry operator where the cursor is. A really good data entry
operator rarely looks at the screen, so audible cues are most
helpful.

Another use for tab stops is in conjunction with the 'fill key'.
When the operator presses the 'fill key' (F6), a 'fill character'
is entered into the record, starting with the current position and
proceeding to the next tab stop. The most common use of the 'fill
key' is to fill with 'not applicable' codes. For example, if the
response to the question 'do you smoke?' is NO, the rest of the
current smoking section should be coded as 'not applicable'. If the
convention is that 'not applicable' codes consist of strings of
9's, then the operator would press F6, then press 9.

KEY COPY FIELDS

Key copy (k) fields are normally set by the program. However, you
may have the record key duplicated anywhere in the record by
setting the 'k' attribute. Warning: this procedure is not
recommended for records having multiple keys. The program will
attempt to duplicate the entire multiple key as it finds enough
'k's, which may not be what you want. I recommend that vertical
copy (next paragraph), NOT key copy, be used wherever possible. Key
copy fields are super-protected; they cannot be unprotected as can
normal protected fields. The ONLY way to change record keys is by
using the 'key name' key (F8) available in the record editor.

THE VERTICAL COPY ATTRIBUTE

A position that has the 'vertical copy' (v) attribute will have
copied into it whatever was entered into the preceding card at the
same column. In the sample screen, columns 1-5 of cards 2 and 3 are
set for vertical copy, which means that columns 1-5 of the first
card will be copied straight down onto the next two cards. This
happens to be a record key field (subject ID), so the result is
that the subject ID will be entered into the first 5 columns of
each card. Vertical copy fields are automatically protected.

FIELD START and END

The [ and ] characters are used to define data entry fields that
have more than one column. When a field has been defined in this
way, any range checks defined in the remaining mask elements will
operate on the entire field, not each character individually. If a
data entry position has neither attribute, it is assumed to be a
single-column field.

NUMERIC FIELDS

Numeric fields are evaluated as numbers during range and
verification checks (eg, '005.3' and '5.300' are equivalent). In
addition, entries will be right-justified on input.

To define a field as numeric, first set its start and end points
with the [ and ] keys. Next, position the cursor anywhere in the
field and press the 'n' key.

See the NUMERIC FIELDS topic for more information.

BYPASS VERIFY FIELDS

Bypass verify (b) fields are those for which you will not require
verification. For example, you may not wish to verify a 'fuzzy'
field such as one containing a free-text comment. A record will be
considered 100% verified if all fields except for the bypassed ones
have been verified.

MULTIPLE ATTRIBUTES

It is possible to set multiple attributes in the same position,
but, obviously, only one attribute character may be displayed. To
clarify things, the 'attribute status' display in the lower left
corner of the mask editor shows all of the attributes for the
current position.

ATTRIBUTES VIA FUNCTION KEYS

It is also possible to set (and release) attributes using function
keys. To see which keys do what, press Ctrl-F1. The information box
display will change, showing all of the function key assignments.
For example, Ctrl-F4 may be used to protect a field, and Ctrl-F9
will define a field as 'numeric'. The function key assignments are
common to both the PICTURE and TABS/ATTRIBUTES editors, which means
that you may set attributes from within the PICTURE editor. The
function key assignments may be displayed from within the PICTURE
editor, also by pressing Ctrl-F1.

┌────────────────────────────────────────────────────────────────┐
│cf1 more..   cf4 protect    cf7 field start   f4 wrap  f10 menu │
│cf2 set tab  cf5 vert copy  cf8 field end  sf3 switch  <─┘ save │
│cf3 unprot   cf6 key copy   cf9 numeric               Esc cancel│
└────────────────────────────────────────────────────────────────┘
ATTRIBUTES function keys
>Mask Editor: The Range-Check mask elements
The remaining mask elements (MINIMUM VALID, MAXIMUM VALID, MINIMUM
MISSING) define ranges for validity checks. These mask elements
work with the FIELD START and FIELD END attributes, set by the
TABS/ATTRIBUTES editor, to check data as they are input. For a
given field, any, all, or none of the range values may be defined.

The range-check mask elements may be used to define data types that
are not included in the PICTURE editing characters. For example,
say that two fields are to be defined: a 1-column field containing
a number in the range 1-3, followed by a three-digit number in the
range 001-240. The missing value codes for the first field are 7
(refused), 8 (unknown), and 9 (not applicable). Similarly. the
missing value codes for the second field are 997, 998, and 999.
Blanks are prohibited in the first field, but allowed in the
second. The mask elements might look like this:

PICTURE             9###
ATTRIBUTES           [ ]
MINIMUM VALID       1001
MAXIMUM VALID       3240
MINIMUM MISSING     7997

IMPORTANT NOTE: Unless a field has been defined as numeric, it will
be treated as a character string for the purpose of range-checking.
This means that numbers should be right-justified and left-zero-
filled (eg, '001', not '  1').

A NOTE CONCERNING RANGE CHECKS

Even though I have implemented range checks in KP5, you might want
to think twice about using them. The reason is that range checks
are generally used to trap CODING mistakes, not DATA ENTRY errors.
The latter are controlled by double-pass keying (verification). It
is usually the case that when a coding error is found during data
entry, it cannot be immediately resolved. The operator must put the
form aside, and wait until the data manager or some other
administrator can determine what to do about the error. This
process can slow down considerably the data entry operation. We
have found that the place to check for coding mistakes is at the
point at which the exported ASCII records are input and added to
the master statistical files. Batches of records with errors are
thus identified and resolved at some regularly scheduled time.
>Numeric fields
It is now possible to define a 'numeric field' in a KP5 mask.
Values entered into numeric fields will be automatically right-
justified, or aligned to a decimal point position if one is defined
in the picture. Range checks will be evaluated numerically (up to
19 significant digits) instead of as characters, so you don't have
to worry about left-zero-fills.

HOW TO DEFINE A NUMERIC FIELD

The first step is to define a standard field in the TABS mask
editor, eg, place a '[' where the field starts and a ']' where it
ends. Next, while still in the TABS mask editor, position the
cursor anywhere within the field and press 'n'. The field should
fill up with n's and the attribute display at the lower left should
indicate NUM.

THE PICTURE MASK FOR NUMERIC FIELDS

You may use any picture-editing characters for numeric fields,
although usually you would use either '#' or '9'. If you place a
period ('.') in a numeric field's picture, a 'decimal anchor' will
be defined at that position. If a decimal anchor is defined, then
entered values will be aligned around it.

ENTERING NUMBERS

If a decimal anchor exists for a numeric field, the entered value
will be right-justified to the anchor position as soon as:

   - the '.' key is pressed
   - the space bar is pressed
   - the cursor leaves the numeric field via an arrow or tab key

If there is not a decimal anchor, the entered value will be right-
justified to the last position as soon as:

    - the operator presses the space bar
    - the cursor leaves the numeric field via an arrow or tab key

Note that a decimal point will be placed in the field only if the
operator keys it in: a decimal anchor is NOT a protected,
'constant' field.

ENTERING NON-NUMERIC DATA INTO NUMERIC FIELDS

So-called numeric fields do not have to be numbers. You may define
a numeric field to accept entry of any datum that you would like
right-justified, or aligned at a decimal anchor. For example,
epidemiologists do a lot with the International Classification of
Diseases (ICD) codes. These codes look like fixed decimal numbers,
except that trailing blanks are important and many start with an
alpha character. A KP5 numeric field may be set up to accept ICD
codes with a picture like this:

   !!!!.!!!

When a code like 'E83', '140.9', or '20.0' is entered, followed by
pressing the space bar, the entry will be correctly aligned and the
cursor will advance to the next field. The numeric range check will
be bypassed if the entered value is not numeric.
>Session statistics files generated by KP5
A session statistics file consists of records that provide
summaries of keypunch sessions. A record is generated each time a
KP5 file is closed. By default, the statistics file generated by
KP5 is dBase-III compatible and named KP5STATS.DBF. However, the
file will be ASCII text and named KP5STATS.DAT if the -A command-
line switch is used, or suppressed entirely if the -O switch is
used. KP5 attempts to place the statistics file in the program
directory (usually C:\KP5); if this cannot be done (on a network
with restricted access to that directory, for example), the file is
placed in the same directory as the KP5 file that was most recently
processed.

The dBase record structure, as well as the layout of the ASCII text
file, is as follows:

Field  Field Name  Type       Width
    1  DATE        Date           8     Date (YYYYMMDD)
    2  FILE        Character      8     KP5 file name
    3  USER        Character     10     User name
    4  TIMEIN_HH   Numeric        2     Time started (hours)
    5  TIMEIN_MM   Numeric        2     Time started (minutes)
    6  TIMOUT_HH   Numeric        2     Time finished (hours)
    7  TIMOUT_MM   Numeric        2     Time finished (minutes)
    8  ELAPSED     Numeric        6     Elapsed time (minutes)
    9  KEYSTROKES  Numeric        6     #keystrokes
   10  RATE        Numeric        6     #keystrokes/hour
   11  ADDED       Numeric        6     #records added
   12  VERIFIED    Numeric        6     #records verified
   13  MODIFIED    Numeric        6     #records modified
   14  DELETED     Numeric        6     #records deleted
   15  EXPORTED    Numeric        6     #records exported
   16  N_RECORDS   Numeric        6     total #records in file
   17  DIRECTORY   Character     64     KP5 file DOS directory
>The UTILITIES Menu
The UTILITIES menu provides access to functions that are not
necessary for normal processing. These functions are discussed in
this section.

COPY FILE

This procedure is used to make a copy of the KP5 file, optionally
removing deleted records as it goes. You may also use DOS for the
same purpose (eg, COPY or XCOPY), but DOS will not fix the file
header to reflect the new data set name. This is not a big deal,
since KP5 will do this, on your say-so, when the new file is
opened.

The COPY FILE procedure is included for administrators who wish to
isolate their data entry operators from the DOS command line.

COPY STRUCTURE

This procedure makes a copy of the file structure and mask. It is
used to initialize a new file having the same characteristics as
the current KP5 file, but no records.

UPDATE

This procedure is used to update the current file with records from
another KP5 file. Normally, records having the same keys in the
update file will replace records in the current file, although you
may prevent this.

EMPTY

This procedure removes all records from the current KP5 file, but
keeps the structure and mask intact. Obviously, it is not for the
faint of heart, and will require you to confirm (twice) that it is
your intention to zap the file.

DELETE EXPORTED (*new in 5.06*)

This procedure will delete all exported records in the current KP5
file. The PACK procedure (below) must then be run to physically
remove the deleted records. Make a backup first: you never know
when one of those supposedly 'finished' records will come back to
haunt you.

GLOBAL FLAG SET (*new in 5.06*)

This procedure allows you to set or release the DELETE, EXPORT,
and/or MARK flags for ALL records in the current KP5 file. For
example, you may use it to remove all record marks.

RESTRUCTURE

This procedure allows you to make structural changes to the KP5
file. You may change the card size, number of cards per record, and
key locations. If the file has records in it, they will be
truncated or padded with blanks if the card size is adjusted. If
you increase the number of cards per record, one or more blank
card(s) will be appended to each record. If the number of cards per
record is decreased, one or more card(s) will be removed from the
end of each record. If the key definitions are changed, the file
will be re-indexed.

If what you want to do is insert or remove columns or cards from
the data set, you probably should use the utility program, KPI.EXE,
which is shipped along with KP5 (see Appendix V). The RESTRUCTURE
procedure built into KP5 will always operate on data 'in place'.

MASK STRUCTURE REPORT

This procedure generates a printout of the mask structures. It may
be a long printout, since one line is printed for each data entry
position.

PACK

This procedure removes deleted records from the KP5 file. The PACK
procedure requires free disk space in order to make a temporary
backup of the data set, but it will check first to make sure enough
is available.

INDEX

Run the INDEX procedure if you think the index has become
'trashed'. Normally, KP5 will sense this condition and
automatically reindex the file, but there may be times when it
won't. Symptoms of a damaged index are: failure to locate records
that you know are in the file, or retrieval of the wrong records,
or catastrophic lockups when retrieval is attempted. Indexes tend
to get out of whack when KP5 is 'abnormally terminated' (the
machine locks up or is turned off or rebooted while the program is
running).

ASCII IMPORT

This utility allows you to import data from an ASCII data set into
the current KP5 file. The structure of the ASCII file must match
that of the KP5 file, eg, there must be the same number of physical
records (cards) per logical record.

KP4 IMPORT

This procedure is used to convert KP4 files into KP5 files. It is
not necessary to have a KP5 file open when KP4 IMPORT is run -- a
new file will be created from the information in the KP4 file and
mask (KP4 is the prior incarnation of the KP system).

FILE PASSWORD

Select this option if you want to add password protection to a KP5
file, or if you want to change a file's password. The password will
be required whenever the file is opened, packed, emptied, or
restructured. WARNING: Do not forget the password! It is stored in
the file header in encrypted form, and you may not be able to hack
it out (at least, I HOPE you won't be able to).

You may remove password protection entering a blank password.

COLORS

This procedure is used to modify the colors used by KP5. The color
set will be saved in a configuration file named KP5.CFG in your
current directory. If you wind up with crazy colors, and want to
restore the default set, simply erase the configuration file, or
use one of the colorset command-line switches (-m, -b, or -c) the
next time you run KP5.

VALID KEY INDEX

This option establishes a 'valid-key' file for the current session.
The valid-key file is some master KP5 file that contains a complete
set of record keys. Using a valid-key file ensures that only valid
record keys will be entered, and is useful when entering records
for some pre-defined set of respondents.
>Shelling to DOS
There may be times when you would like to use DOS while running
KP5. For example, you might want to create a new KP5 in some
directory, but you forgot to create the directory first. Or, you
might want to delete files to free up disk space prior to packing
or copying a file.

The process of temporarily exiting to the DOS environment is called
shelling to DOS, and you may do this by selecting Shell to DOS from
the FILE menu. As a precaution against accidentally manipulating
any open files (a sure recipe for disaster), the Shell to DOS
option is not available whenever a KP5 file is open.

To return to KP5, type EXIT at the DOS prompt.
