>Introduction
┌───────────────────────────────────────────┐
│ KP5 Help Document * small version *       │
│ KP5 version 5.07, January 1992            │
└───────────────────────────────────────────┘

This document BRIEFLY describes the features and use of KP5, a
keypunch system for PC's and compatibles. A complete description is
given in the 'large' help file. This 'small' help file is for use
on machines with very limited disk space (eg, 360K floppies). If
you downloaded KP5 from a BBS or CompuServe, note that the small
help file is in KP507A.ZIP/KP507A.EXE (basic system), and the large
help file is in KP507B.ZIP/KP507B.EXE (supplemental files).

       ┌───────────────────────────┐
       │  Peter Charpentier        │
       │  47 Meeting House Hill Rd │
       │  Durham, CT 06510         │
       │                           │
       │  CompuServe: 70053,705    │
       └───────────────────────────┘
>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     ■Mask Editor:TABS/
Jan 1992       are now supported.             ATTRIBUTES

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

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

               Bypass-verify fields          ■Mask Editor:TABS/
                                             ATTRIBUTES
>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 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. If
the menu bar is not on-screen, you may usually activate it by
pressing F10.

DIALOGS

There are a number of 'dialog boxes' or screens that KP5 uses to
get information from you. 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       Move to next field.
BackTab   Move to previous field.
F10       Activate the menu.
arrows    Move up or down within the dialog.
>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:

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

The FILE STRUCTURE dialog will be displayed when a file is created.
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)

RECORDS AND CARDS EXPLAINED

RECORDS are made up of one or more CARDS. In the old days, 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'. Of course, KP5 cards may be of any
reasonable length, and many KP5 files have just one card per
record.

RECORD KEYS

A requirement of KP5 files is that each record must have a unique
key. KP5 files are always indexed 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.

Each record key is defined by 1) position and 2) length.

AN EXAMPLE

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

Press F2 when you are finished entering the record key(s), and the
file will be 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 "command line
syntax" for details. The other way is to select Open from the FILE
menu.
>How to enter new records into a KP5 file
There are four steps involved in opening a file and entering new
records into it:

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.

Step 3. ENTER THE RECORD KEY

Enter the new record's 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.

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. 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 the window between the 'rulers'. For records
with card sizes exceeding 80 columns, the window will 'slide'
through the record as you key in the record.

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

THE KEYBOARD DURING DATA ENTRY

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

F4   Switches the display mode between 'normal' and 'wrap'.

sF4  (Shift-F4) Enables or disarms the 'protect' feature.

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.

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.

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.

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.

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. 

sF9  (Shift-F9) Sets or releases the DELETE flag for the current
     record.

aF9  (Alt-F9) This is the UNDO key: any changes made while in the
     record editor will be 'undone'.

F10  Activates the main menu.

The following additional keys have special meaning:

Enter          Ends data entry and accepts the record.
F2             Acts as an alternate Enter key.
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)
>Verifying records
You start a verification session by selecting Verify from the
DATAENTRY 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 or Ctrl-right arrow. 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.

VERIFICATION ERRORS

The verification error condition is raised 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.
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'.
>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. 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
KP5 files (files with names like *.KPF) are NOT ASCII text files.
They must be 'exported' to ASCII before they can be used.

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.
>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.
>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.
>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     Save and exit.

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

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. Protected areas are usually blank, but they may contain
data that is to be 'hard wired' into 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. 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.

Protected areas appear in the PICTURE editor in reverse video.

It is important to remember that the PICTURE editor ONLY affects
the data entry mask, and NOT the actual data. If you want to add or
remove columns or cards in the data set, use the KPI utility.
>Mask Editor: The Tabs/Attributes mask element
Each position in a KP5 record may have any of seven 'attributes':
tab, vertical copy, key copy, numeric, bypass verify, 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                           │
│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. 

KEY COPY

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.

VERTICAL COPY

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. 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.

BYPASS VERIFY

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.

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.
>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.

IMPORTANT NOTE: Unless defined as 'numeric', fields are treated as
character strings for the purpose of range-checking. This means
that numbers should be left-zero-filled (eg, '001', not '  1').
>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.

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, eg, merge the two files.

EMPTY

This procedure removes all records from the current KP5 file, but
keeps the structure and mask intact.

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.

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.

MASK STRUCTURE REPORT

This procedure generates a printout of the mask structures.

PACK

This procedure removes deleted records from the KP5 file.

INDEX

Run the INDEX procedure if you think the index has become
'trashed'. 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.

KP4 IMPORT

This procedure is used to convert KP4 files into KP5 files (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.

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.

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.
>Session statistics files
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 given in the 'large' online help file and its printable
version, KP5.DOC.
>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.