============
MENU EDIT II - 11/20/2005 - v1.1.5 - Copyright (C)2003 Bob Stockler
============

========
Contents
========

   1 - Introduction and Release Notes
   2 - Conventions & Definitions
   3 - Start Up
   4 - Main Menu Screen
   5 - Re-arranging Choices on a Menu
   6 - Menu Element Screens
   7 - Action Command Line Checking
   8 - Creating or Editing Script/Batch Files
   9 - Frequently Used Options Menu
  10 - Browse Screens
  11 - Copying a Menu to a Different PFMENU Directory
  12 - Managing Script/Batch Files
  13 - Executing a User Menu
  14 - Renaming or Copying a User Menu
  15 - User Menu Help File Assistant
  16 - Documenting a User Menu

==================================
1 - Introduction and Release Notes
==================================

Release Note:

    This version adds the convenience of the processing table
    "util", which can be CALLed from the Main Menu Screen by
    typing the letter "H" for Helpful Utilities. This accesses
    options to Rename or Copy filePro User Menus or access the
    filePro User Menu Help File Assistant.  Using it, a user
    can create, edit, view or test User Menu Help files.  It
    assumes the Help File is that for the Menu currently being
    created or edited, but - when in the Help-File Assistant -
    it may be used to work with any Help File in the current
    PFMENU directory.  Perl must be in the user's PATH to be
    able to Rename or Copy filePro User Menus.

    The "Help" option on the Help-File Assistants Menu offers
    introductory remarks about filePro User Help Files.  For
    more detailed information about them see the article:

      Writing filePro Help Files, by Laura Brody
      The filePro Developer's Journal, Volume 1, number 4, p 23.

    available from www.hvcomputer.com.

MENU EDIT II does what 'dmakemenu' and 'DMAKEMEN.EXE' do, and
much more (more easily).

It requires filePro v4.8.11 or later, running on UNIX or Windows
operating systems.  The discussion and screens below are written
from the viewpoint of a UNIX user, so Windows users will in some
cases need to translate "Shell Script" to "Batch File", "[Del]"
to "[Ctrl-C]", etc.

The program gains exclusive access to a Menu while it is edited
by writing a lock file in the style of "MenuName.-X" in the
current PFMENU directory.  It is possible for a lock file to be
left in place if the program is exited in any abnormal way
(system crash, UNIX user sending it a QUIT signal, etc.).  To
remove an orphaned lock file, elect to edit (or create new)
another Menu, then type an asterisk ([*]) at the Main Menu Screen
prompt line.  A list of all locked Menus displays, then a prompt
to enter the name of the Menu to be released.

One important note:  Changes to the fields in Menu Elements are not
made permanent until one exits the editing of a Menu with [X] at
the Main Menu Screen and responds [Y] to the prompt to save
the Menu (or the Menu has been saved when using [R] to have filePro
run the Menu for testing or inspection).  However, Script or Batch
Files that are created, edited, renamed or deleted have those
changes made to them in real time, and are effected whether or not
the Menu is saved, with this exception:

  If a Choice Character for a Menu Element is changed, where
  its Action Command executes a Script/Batch File with the
  name of the Menu and an extension ending with the original
  Choice Character, if the user elects to have the program
  rename the Script/Batch File to have a name ending with the
  new Choice Character, it's not done until saving the Menu.

Typing an unprompted [!] at the Main Menu Screen may escape
from the program, giving the user access to the command line.
This may be useful for, among other things, copying a Menu to
a new Menu name or for renaming a Menu.

  UNIX:  A shell escape gives the user the Effective User ID
  (EUID) of user "filepro" with the current PFMENU being the
  working directory.  If the parameter SHELL is set in the
  environment the shell will be its value, defaulting to be
  /bin/sh.  It requires a file named ME2SHELL.AOK, owned by
  user "filepro", with read-write permissions for the owner
  only, in the filePro file directory in which "prc.me2" and
  "README.me2" are installed.  This file may contain login
  names of users privileged to exercise shell escapes, those
  names listed one to a line, with no whitespace.

    On entering the shell, the screen shows:

      You are effectively user "filepro", in PFMENU:
      /appl/fp/menus
      ME2SHELL_AOK=/appl/filepro/me2/ME2SHELL.AOK
      $ _

    so editing ME2SHELL.AOK may be done by:  vi $ME2SHELL_AOK

  Linux:  As above, but the EUID of the user "filepro" will
  (most probably) not be assigned.  If this is the case, only
  the user "filepro" is permitted to execute the program.  For
  an explanation of this limitation, and workarounds allowing
  execution by other users, see the file "ReadMe2.linux".

  Windows:  An escape to the command line puts the user in the
  current PFMENU directory.  It requires a file that is named
  ME2SHELL.AOK be in the filePro file directory in which
  "me2.prc" and "README.me2" are installed, but its contents
  are not read; existence of the file is sufficient to permit
  escape to the command line.

    On getting a command line prompt, the screen shows:

      Type 'EXIT' to return to MENU EDIT II
      C:\fp\menus> _

The subroutine "Initial" near the top of the table ("prc.me2"
or "me2.prc") contains assignments of default values to some
of the variables used by the program.  The user may want to
edit these, or at least become familiar with them.

This file (README.me2) may also be referred to while using the
program by typing an unprompted [?] at the Main Menu Screen.

=============================
2 - Conventions & Definitions
=============================

In the screen display examples and discussions to follow, square
brackets indicate screen highlighting [reverse video] of the
text they surround.

Throughout the program, when only one of two or more choices in a
prompt is highlighted that choice is the default; pressing [Enter]
alone will select it.

The acronym "IUA" refers to filePro's "Inquire, Update, Add" user
interactive file and record access (dclerk or rclerk) program.

A "Browse" Screen displays a page of lines, each containing fields
in one record (Menu Choice Character, Description, and as much of
the Action Command Line as space allows).

At NO prompt does [X]-Exit exit from the program; it simply exits
to a previous phase (higher level) of the program.

At ONLY ONE prompt does [Del]-Exit exit from the program, and that
is at the prompt to enter a Menu Name, which is always displayed
after typing [X] to exit from the Main Menu Screen:

  Press [Enter] for a List of Available Menus or to Create a New Menu.

  Enter the Menu Name: _                               .     [Del]-Exit

At all other times its effect is similar to that of the [X]-Exit
described above.

[Q]-Quit at the Main Menu Screen quits the program immediately
with no opportunity to save the current Menu.

============
3 - Start Up
============

The UNIX distribution contains a shell script ('me2') which
may be used to start the program.  The Windows distribution
contains a batch file ('me2.bat') for the same purpose, and
along with it a shortcut icon ('MENU EDIT II') that can be
moved to the Windows desktop for convenience.

On UNIX and Windows the filePro User Menu Action Command line:

  /fp/dclerk me2 -sme2 -y '' -z me2 -d -h "MENU EDIT II" -t 200000 -tf 200000

executes MENU EDIT II and brings up this screen:
================================================================================
                               +--------------+
                               | MENU EDIT II |  v1.1.5  (C)2003 Bob Stockler
                               +--------------+

  Press [Enter] for a List of Available Menus or to Create a New Menu.

  Enter the Menu Name: _                               .     [Del]-Exit

================================================================================

Pressing [Enter] alone displays all of the available User Menu
names in a LISTBOX, from which a selection may be made.  All
files that may reasonably be expected to be User Menus (and
only those files) will be listed.  This is based on their
having a file size of 5661, 4719 or 2801 bytes and having the
appropriate number of newline separated records.  The first
item in the LISTBOX is "[[ NEW ]]", and selecting it allows
creation of a new Menu.

If the variable ME2MENU is set in the environment to the name
of an existing User Menu, the program skips the above prompt
and goes immediately to the Main Menu Screen.

====================
4 - Main Menu Screen
====================

After a Menu name (eg: "dpromenu") is entered or selected
a screen similar to this one displays:
================================================================================
[Menu:] [dpromenu]  [PFMENU=/appl/fp/menus]                             04.08.00
+------------------------------------------------------------------------------+
|                            filePro Plus Main Menu                            |
+------------------------------------------------------------------------------+
|                                                                              |
|  1   Creation Programs                 13   Runtime Programs                 |
|  2                                     14                                    |
|  3 1 Define Files                      15 ? filePro Directory                |
|  4 2 Define Screens                    16 A Expand Files                     |
|  5 3 Define Output                     17 B Inquire, Update, Add             |
|  6 4 Define Edits                      18 C Index Maintenance                |
|  7 5 Define Processing                 19 D Request Output                   |
|  8 6 Define User Menus                 20 E Set/Change File Name             |
|  9 7 Printer Maintenance               21 F filePro Utilities Menu           |
| 10                                     22 G Run A User Menu                  |
| 11 8 Define Processing - Quickstart    23 H Inquire, Update, Add -Quickstart |
| 12                                     24 I Request Output - Quickstart      |
|                                                                              |
|  T   Title                        X - Exit                                   |
|                                 [F10] - Help                                 |
+------------------------------------------------------------------------------+
|                              Enter Selection > _                             |
+------------------------------------------------------------------------------+
                 Select a Menu Element (1-24) or Press [Enter]

================================================================================

(The two columns of Menu Element Numbers are highlighted for
better visual distinction.)

This is an emulation of a filePro User Menu Screen, from which
Menu Elements may be selected by entering their Element Number
(1-24), to view, create or edit, and from which other operations
may be performed as explained below.

Each Menu Element, following its Element Number, displays its
Choice Character and Description for easy identification.

Typing [T] displays the Title, Version and Remarks fields to
be viewed, created or edited.

[P] in the lower right corner of the Main Menu Screen indicates
the Menu has a password.  Typing [P] at the Main Menu Screen will
initiate the Password Manager, by which passwords may be assigned
for, changed or removed from a Menu.  How this works depends on
the Operating System and the version of filePro being used.

[Legacy Menu] in the upper left corner of the Main Menu Screen
indicates a Legacy Menu.  Saving a Legacy Menu converts it to
the current User Menu format and a size of 4719.

Typing [F4] allows deletion of the current Menu and ALL of its
Associated Script Files, or its Associated Script Files alone.

[F10]-Help provides help screens relative to MENU EDIT II and
filePro program flags.  When in that help routine, [F9] works
to search directly to subsections of it.

This same help facility is also available via [F10] when editing
Action Command Line fields, going directly to a LISTBOX menu of
primary Help subsections.  When editing any other Menu Element
field of length greater than 1, an unprompted [F10] displays a
screen of help on the effects (noted below) of the special keys
when in a field on a filePro IUA screen.

==================================
5 - Re-arranging Choices on a Menu
==================================

To re-arrange choices on a User Menu, type [S] at the Main Menu
Screen prompt or from the Frequently Used Options Menu.

The prompt then becomes:

  Swap Menu Element Number: _

On entering a Menu Element Number the prompt becomes:

  Swap Menu Element Number:   1  with Menu Element Number: _

On entering a second Menu Element Number it becomes:

  Swap Element [#1] with Element [#2] ? ( [Y] or N ): _

On typing [Y] or pressing [Enter] the swap is made.

The operation may be cancelled by entering [N] at this
prompt or by pressing [Enter] alone at either of the two
previous prompts.

In concluding a swap, if both Menu Elements already had
Choice Characters, the user is prompted:

  Swap Choice Characters along with Elements ?  ( Y or [N] ): _

The default response to this prompt is [N] in consideration
of those who like menus with choices ordered 1, 2, 3 , etc.
in one column and A, B, C, etc. in the other.

Be aware that when changing the Choice Character of a Menu
Element with an Action Command Line calling a Script/Batch
file with a command in the format "/fp/menus/menu.-C", it
may be desireable to use Script/Batch File Management to
rename the script and to edit the Action Command Line that
calls it.

A similar option, to copy a Menu Element to an empty Menu
Element can be initiated by typing [K] at the Main Menu
Screen prompt or from the Frequently Used Options Menu.

========================
6 - Menu Element Screens
========================

Selecting Menu Element 3 displays this screen:
================================================================================
                               +--------------+
                               | MENU EDIT II |  v1.1.5  (C)2003 Bob Stockler
                               +--------------+

 [Menu Name:  ]  [dpromenu]  [PFMENU=/appl/fp/menus]

 [Menu Item # ]  3

 [Menu Choice:]  1.

 [Description:] Define Files                    .

 [Action Commands:]

   /fp/ddefine                                                                .

 [Long Description:]

   Create/modify filePro file layout.                                         .

--------------------------------------------------------------------------------
                               Enter Selection > _

                [U]-Update   [B]-Browse   [D]-Delete   [X]-Exit

================================================================================

This is an emulation of an IUA screen, and at its main
prompt line one may page through the Menu Element screens
as one would page through records in a filePro file.  The
Up (or Left) Arrow moves to the previous Menu Element and
the Down (or Right) Arrow or [Enter] moves to the next one.
This movement wraps at Elements 1 and 24.

[B]-Browse presents an emulation of an IUA Browse Screen
showing more information about each Menu Element than can
be seen from the Main Menu Screen.  This will be discussed
more fully later.

[D]-Delete will erase the entire Menu Element (after an
"Are you Sure ?" prompt).

[X]-Exit returns to the Main Menu Screen.

The main difference between this IUA screen emulation and
a real IUA screen is that the [HOME] key, rather than [Del],
is used to break out of (cancel editing/creating) it.  This
is because WAITKEY, used to capture keystrokes, can not trap
the special key "BRKY".  There are some minor differences in
behavior when a user presses [ESC] and then a different key
(to cancel the save), but for the most part behavior is the
same, and any differences should cause no problems.

[U]-Update puts the user in Update Mode in field 1 (the
Choice Character) where the prompt line becomes:

                         [ESC ESC]-Save   [HOME]-Cancel

When editing the Choice Character, if any Choice Characters
have already been assigned, a string similar to:

   Already Used: [123456789?ABCDEFGHI]

appears to the right of the Choice Character field, with
those Choice Characters already used in sorted order.  The
program prevents duplicate use of any Choice Character.

When in Update Mode, cursor movement from field to field
and within fields is much as in a real IUA screen.  Editing
of fields supports all special keys filePro supports when
entering data in a field on a real IUA screen (plus emulating
'dmakemenu' where [F5] is used to create/edit a Script/Batch
File when in the Action Commands field).  Keys and their effects
are listed below (some key labels differ on Windows):
 
  [F1] - Insert a space under the cursor.
  [F2] - Delete the character under the cursor.
  [F7] - Move to space after the last non-blank character in the field.
  [F8] - Tab within the field.
  [TAB] - Move cursor to the first character in the field.
  [Ctrl-O] - Clear from cursor to end of field (UNIX).
  [Ctrl-End] - Clear from cursor to end of field (Windows).
  [Enter] - Move cursor to the next field.
  [Dn Arrow or Page Dn] - Move cursor to the next field.
  [Up Arrow or Page Up] - Move cursor to the previous field.
  [Right Arrow] - Move cursor to the right.
  [Right Arrow] - Move to next field when at end of a field.
  [Left Arrow] - Move cursor to the left.
  [Left Arrow] - Move to previous field when at beginning of a field.
  [Backspace] - Move cursor to the left (non-destructive).

Typing an unprompted [F10] while in either of the Description
fields will display the above reference.

When editing an Action Command Line the prompt becomes:

     [ESC ESC]-Save   [HOME]-Cancel   [F5]-Create Script File
or
      [ESC ESC]-Save   [HOME]-Cancel   [F5]-Edit Script File

according to whether or not the line already contained the
command "/fp/menus/MenuName.-".

The prompt [F10]-Help displays above the data entry field.
Typing [F10] at any point in this field brings up the Help
Screen's Search LISTBOX, allowing a category choice for a
quick reference to the various filePro programs' flags.

Pressing [F5] when in this field is the only way to create
a Script/Batch File, though they may be edited as well in
the Script/Batch File Management feature of the program.

When creating a Script/Batch File, if there is a current
Action Command that doesn't execute it, that line will be
made a remark as the first line of the new file.  This is
an aid in converting a command into a Script/Batch File.

Note: The program automatically converts backslash ("\")
      characters to forward slashes ("/") in any created
      or existing Action Command Line which executes a
      Script/Batch File (ie: "\fp\menus\" is converted
      to "/fp/menus/").  The Script/Batch File will be
      executed by filePro with the pathname appropriate
      to the operating system, while this consistency
      is helpful to the MENU EDIT II program.  This is
      the only way in which MENU EDIT II will alter the
      descriptions or commands in any User Menu.

================================
7 - Action Command Line Checking
================================

A certain amount of checking is performed on new or
modified Action Command Lines if they appear to execute
filePro programs.  Ignoring the User Menu command line
special initial characters ("@", "*" and "!"), if a
command line begins with "/cc/" or "\cc\" ("cc" being any
two characters), if the two characters are not "fp" a
prompt asks if they were meant to be "fp".  An
affirmative response makes them "fp", otherwise they are
left as entered and no further checking is done.

Command lines beginning with "/fp/" or "\fp\" have the
word following those four characters checked to see if it
is a filePro program.  If it doesn't exactly match the
name of a program, a prompt asks if it might have been
misspelled.  Upon an affirmative response the user is put
back in the field to correct its spelling.

Command lines executing the "clerk" or "report" programs
are subjected to further checks.  The filePro file name
is checked for its existence.  If it does not exist the
user is placed back in the field to correct its name.

All flags on the command line are checked to see if they
are legal for the program.  If the flag has an argument
pointing to a file (ie: an index, processing table,
selection set, browse format or output format), that file
is checked to see if it exists.  Existence of indexes is
checked on all file systems pointed to by PFDSK, and the
legality of the index name is checked.

Finally, the user is notified if a flag appears more than
once on the command line.

When the cursor is in the Action Conmmand Line field, this
line appears above it:

 [Action Commands:]     [F10]-HELP     [F6]-Toggle Command Checking - Now [ON]

The command line checking described above can be toggled
on and off by typing the [F6] key.  Command line checking
can be totally disabled if the variable "Chk_Act_Cmds" is
set to "OFF" in the subroutine labeled "Initial" near the
top of the table (this also eliminates the prompt to
toggle it off and on).  Setting it to "N" defaults it to
off, but permits toggling it.

==========================================
8 - Creating or Editing Script/Batch Files
==========================================

A text editor on the user's system is used to create and
edit Script/Batch Files.  It will be the editor whose name
is held in the environmental parameter EDITOR, or defaults
to 'vi' on UNIX or 'edit' on Windows.

Associated Script/Batch Files may be created only from the
Action Command Line field when creating or editing a Menu
Element by pressing [F5] when in that field.  They may be
edited, renamed or deleted from within Script/Batch File
Maintenance (accessed with [M] from the Main Menu Screen).

Menu Elements with the Choice Characters "?", "*", or "\"
are not permitted to have Script/Batch Files with those
characters in their filename extensions.

================================
9 - Frequently Used Options Menu
================================

Pressing [Enter] alone at the Main Menu Screen brings up
this MSGBOX menu:
  +--------------------------------------------------------------------------+
  |                                                                          |
  |   [E] - Select a Menu Element (1-24).                                    |
  |                                                                          |  
  |   [T] - Select the Title-Version-Remarks Element.                        |
  |                                                                          |
  |   [B] - Browse Menu Elements (Choice, Description & Action on 1 line).   |
  |                                                                          |
  |   [S] - Swap two Menu Elements (Re-arrange the Menu).                    |
  |                                                                          |
  |   [K] - Copy a Menu Element to an Empty Menu Element.                    |
  |                                                                          |
  |   [R] - Run:  Have filePro execute this Menu.                            |
  |                                                                          |
  |   [C] - Change PFMENU to be a Different Directory.                       |
  |                                                                          |
  |   [M] - Manage Shell Scripts.    [D] - Document this Menu.               |
  |                                                                          |
  |   [P] - Assign a Menu Password.  [H] - Helpful Utilities.                |
  |                                                                          |
  |   [Q] - Quit Immediately (the Menu will NOT be Saved).                   |
  |   [X] - Exit (prompted to Save if edited, then to Edit another Menu).    |
  |                                                                          |
  +------------------------------------[==>]  Your Choice or Press [Enter]: _+

Keys that exit this menu and initiate the indicated features
are also active in the same way when at the Main Menu Screen.

The Choice:

  [P] - Assign a Menu Password.

will instead be:

  [P] - Change the Menu's Password.

if the Menu already has a password.  After its selection, the choices:

    [C] - Change the password.

    [R] - Remove the password.

    [Q] - Quit.

are offered.

===================
10 - Browse Screens
===================

Typing [B] for Browse on the Options Menu, or at the main prompt
line of the Main Menu Screen or a Menu Element Screen, displays
this simulated Browse Screen:
================================================================================
                               +--------------+
                               | MENU EDIT II |  v1.1.5  (C)2003 Bob Stockler
                               +--------------+
[Browse] - Page 1
--------------------------------------------------------------------------------
 Choice        Description                       Action Command Line
--------------------------------------------------------------------------------
 [   Creation Programs                                                        ]

   1 Define Files                      /fp/ddefine
   2 Define Screens                    /fp/dscreen
   3 Define Output                     /fp/dmoedef
   4 Define Edits                      /fp/deddef
   5 Define Processing                 /fp/dcabe
   6 Define User Menus                 /fp/dmakemenu
   7 Printer Maintenance               /fp/pmaint

   8 Define Processing - Quickstart    /fp/rcabe

--------------------------------------------------------------------------------

      Use [Arrow] or [Page] Keys to Move the Cursor, or [B]-Bottom [T]-Top

                     [Enter]-Select   [U]-Update   [X]-Exit

================================================================================

It consists of two pages of 12 Menu Elements each.  The Page
keys move between the two pages and all Arrow keys (and [B]
and [T]) move the highlight cursor.  The Up and Left Arrows
are equivalent, as are the Down and Right Arrows.

[Enter] selects a Menu Element to view, [U] puts the user in
update mode in the Element, and [X] returns to the Main Menu
Screen.

When the Browse Screen is accessed by [B] from the prompt line
of a Menu Element Screen the highlight cursor will be on that
Menu Element.

===================================================
11 - Copying a Menu to a Different PFMENU Directory
===================================================

To copy a Menu from one PFMENU directory to another:

  1 - Load the Menu to be copied.
  2 - At the Main Menu Screen, type [C] to change PFMENU.
  3 - Enter the pathname of the new PFMENU directory.
  4 - Respond [Y] to this prompt:

            +-------------------------------------------------------+
            |                                                       |
            |  The Menus Directory has been changed to:             |
            |                                                       |
            |  PFMENU: [/u/appl/fp/menus]                           |
            |                                                       |
            |  The current Menu [dpromenu] was loaded from:         |
            |                                                       |
            |  PFMENU: [/appl/fp/menus]                             |
            |                                                       |
            |  [SAVE] this Menu in the [NEW] PFMENU Directory ?     |
            |                                                       |
            |                                                       |
            +------------------------------ Select ( [Y] or [N] ): _+

  5 - To copy all Active Associated Script/Batch files to the
      new PFMENU directory, respond [Y] to this prompt:

                 +--------------------------------------------+
                 |                                            |
                 |  Copy the Active Associated Shell Scripts  |
                 |                                            |
                 |  to the new PFMENU directory ?             |
                 |                                            |
                 +------------------- Select ( [Y] or [N] ): _+

       "Active" means Script/Batch Files that are executed by an
       Action Command Line command: /fp/menus/MenuName.-?.  If
       there are none this prompt will not display.

================================
12 - Managing Script/Batch Files
================================

Selecting [M] on the Options Menu or entering it at the Main
Menu Screen presents a screen similar to:
================================================================================
                               +--------------+
                               | MENU EDIT II |  v1.1.5  (C)2003 Bob Stockler
                               +--------------+
  User Menu [menu] Shell Scripts in [/appl/fp/menus]

  [Select] a Shell Script to Edit, Rename, Delete or Execute.
                               +--------------+
                               |[ 2> menu.-2] |
                               |  9> menu.-9  |
                               |  C> menu.-C  |
                               |  F> menu.-P  |
                               +--------------+
  Type the Choice Character and/or Use Arrow Keys to highlight your choice.

                          [Enter]-Select   [Del]-Exit

  +---------------------+
  | [Orphans:] menu.-9  |
  +---------------------+

================================================================================

All of the Associated Shell Scripts are displayed in a
LISTBOX.  Some, or all, of them may be orphans (files
not executed by any current Action Command Line), and
are listed in a SHOW POPUP box lower on the screen.  

On selecting an orphan the display becomes:
================================================================================
                               +--------------+
                               | MENU EDIT II |  v1.1.5  (C)2003 Bob Stockler
                               +--------------+

           [Selected:]  [menu.-9] in [/appl/fp/menus]

   [Choice Character:]      [Used:] 123ABCDEMPSZ

        [Description:]  [NO] Action Command executes this Shell Script.

          [1]-Edit   [2]-Rename   [3]-Delete   [4]-Execute   [X]-Exit

                                 Your choice: _

================================================================================

On selecting an active one, it shows:
================================================================================
                               +--------------+
                               | MENU EDIT II |  v1.1.5  (C)2003 Bob Stockler
                               +--------------+

           [Selected:]  [menu.-C] in [/appl/fp/menus]

   [Choice Character:]  C   [Used:] 123ABCDEMPSZ

        [Description:]  Display a Calendar

   [Long Description:]

         [=>] Display a 3-Month Calendar with Today's Date Highlighted

          [1]-Edit   [2]-Rename   [3]-Delete   [4]-Execute   [X]-Exit

                                 Your choice: _

================================================================================

Choosing to Edit the Script/Batch File, the file is opened
using the editor specified by the environmental parameter
EDITOR (UNIX default: 'vi'; Windows default: 'edit').

On choosing to Rename the Script/Batch File, the prompt is:

           [RENAME] menu.-C

           Choice Characters Used in the Menu: [123ABCDEMPSZ]

           Characters Used by Shell Scripts: [9CP]

           Enter the new final character: menu.-_

Attempting to rename a file to the name of an existing file
will provoke this warning (which defaults to NO):

              +--------------------------------------------------+
              |                                                  |
              |  [W A R N I N G]                                 |
              |                                                  |
              |  Renaming [menu.-C] to [menu.-P]                 |
              |                                                  |
              |  will overwrite the existing file by that name.  |
              |       ^^^^^^^^^     ^^^^^^^^^^^^^                |
              |  Is it [OK] to continue ?                        |
              |                                                  |
              +---------------------------------- ( Y or [N] ): _+

A choice to Delete a Script/Batch File affords a chance to
reconsider (with the default being NO):

                                [DELETE] menu.-C

                          Are you sure ?  ( Y or [N] ): _

If the choice is to execute a Script/Batch File the user is
prompted:

         "Press [Enter]" on completion ?  ( Y or [N] ): _

so an Action Command Line beginning with a "@" is emulated.

Next the user is given the opportunity to modify parameters
in the environment in which the Script/Batch File executes:

  Modify the environment in which it executes ?  ( Y or [N] ): _

If SYSTEM's environment had already been modified, the SHOW
POPUP box (explained below) containing the modified variables
and their current values displays along with the above prompt.

If it is elected to modify SYSTEM's environment and it has
already been modified, the prompt is:

  Restore [SYSTEM's] Environment to its Initial State ?  ( Y or [N] ): _

If the response to this is [Y], it is done, and it's assumed
this satisfied the request to change SYSTEM's environment.

If the response is [N], or there had been no previous changes
to SYSTEM's environment, the user is prompted to enter pairs
of names and values:

   +------------------------------------------------------------------------+
   |                                                                        |
   |  Enter a variable [NAME] (enter a blank when done):                    |
   |                                                                        |
   |  [>]  _                             .                                  |
   |                                                                        |
   +------------------------------------------------------------------------+

Variable names are restricted to those beginning with an alpha
character or underline, and consisting thereafter of letters,
digits or underlines.  UNIX is case sensitive, but Windows
is not, so on it all variable name are converted to upper case,
while on UNIX they are not (so what you enter is what you get).

If, on Windows, you require variable names not permitted by
these constraints, they won't be enforced if STRICT_VAR_NAMES=N
is set in the environment.  The subroutine "Initial" may also be
edited so the label "Strict" tests false (ie: If: "1" eq "0").

After an acceptable variable name (eg: PFDATA) is entered, the
prompt becomes:

   +------------------------------------------------------------------------+
   |                                                                        |
   |  Enter the [VALUE] to assign to [PFDATA]:                              |
   |                                                                        |
   |  [>]  _                                                              . |
   |                                                                        |
   +------------------------------------------------------------------------+

These name = value pairs are put into the environment of the
SYSTEM command with PUTENV.  Changes to SYSTEM's environment
remain until the initial state is restored as describe above,
or when changing Menus, at which time they may be retained or
set to their initial values.

A SHOW POPUP box near the top of the screen lists name=value
pairs as they are put in SYSTEM's environment.  These are in
the order in which they are initially entered.  If a certain
parameter is set to a new value it retains its order in the
list, but the value it holds is changed.

After a Script/Batch File has executed, its elapsed time of
execution appears in the upper left of the screen:

                               +--------------+
   Elapsed Time:               | MENU EDIT II |  v1.1.5  (C)2003 Bob Stockler
         0:00:11               +--------------+

and remains there until another choice from the prompt line
is selected.

Following an Edit or Execution the program remains with the
selected Script/Batch File as its subject, and [X] must be
pressed to return to the LISTBOX of file choices.  After a
Rename or Delete it returns to the LISTBOX immediately.

Script/Batch File Maintenance may be exited only by exiting
from its LISTBOX of Script/Batch File names.

============================
13 - Executing the User Menu
============================

The option [R] typed at the Main Menu Screen or selected from
the Options Screen will execute the User Menu being created
or edited.

If changes have been made to the Menu the user is given the
opportunity to save it before it executes.

Also, before the Menu is executed the user is given an option
to modify its environment as described above for executing
Script/Batch Files.

A SHOW POPUP box in the upper left of the screen displays a
list of any variables that have been modified in SYSTEM's
environment, and the choice given to restore them to their
initial state, or to Add to or Modify them.

A note about SYSTEM's environment.  After [X] to exit a Menu,
if SYSTEM's environment has been modified, the user is given
the option to maintain it as it is or to restore it to its
initial state (ie: the environment in which MENU EDIT II was
initiated).

------------------------------------
14 - Renaming or Copying a User Menu
------------------------------------

While perhaps tasks not often required, it's convenient to be able to
rename or copy a User Menu and its Associated Shell Scripts with but
one command.  The Perl programs "rename_menu.pl" and "copy_menu.pl"
provide that facility.  These program prompt for the name of the Menu
to be renamed or copied, and then the new name, then accomplish the
task very quickly.  Action Command Lines that call any scripts or
batch files are edited to replace the old name with the new one and
the script or batch files (and any Menu help file) are renamed.

As well as being used as independent programs, these programs can be
used from within Menu Edit II to rename or copy the Menu being edited
if Perl is in the user's PATH.  They are part of the Helpful Utilities
accessed by typing [H] at the Main Menu Screen.

See the files "RenameMenu.txt" and "CopyMenu.txt" for more complete
information.

==================================
15 - User Menu Help File Assistant
==================================

Another feature in the Helpful Utilities accessed by typing [H] at
the Main Menu Screen is the filePro User Menu Help File Assistant.

It allows one to create or edit a Menu Help file, to view one that
already exists, or to execute the Menu to test the Help file.

While it defaults to using the Help file for the Menu being edited,
it allows changing to any other Menu's Help file.

It also includes a brief tutorial on writing Menu help files.

============================
16 - Documenting a User Menu
============================

Documentation may be written to a file or printer or both.
Whatever the output selected, the user is given the choice
to view it with a PAGER before returning to the Main Menu
Screen.

Entering [D] at the Main Menu Screen brings up this MSGBOX:
  +--------------------------------------------------------------------------+
  |                                                                          |
  |  [Document Menu:]  [dpromenu]  [PFMENU=/appl/fp/menus]                   |
  |                                                                          |
  |  Print Command:                                                          |
  |  ^^^^^^^^^^^^^^                                                          |
  |    laser - hplaser - [lp -s -d laser]                                    |
  |                                                                          |
  |    [1] - Specify a Different Print Command                               |
  |                                                                          |
  |  Output File:                                                            |
  |  ^^^^^^^^^^^^                                                            |
  |    [/tmp/dpromenu.txt]                                                   |
  |                                                                          |
  |    [2] - Specify a Different Output File                                 |
  |                                                                          |
  |  [Direct Output to:]                                                     |
  |                                                                          |
  |    [F]-File  [P]-Printer  [B]-Both  [X]-Exit to Main Menu                |
  |                                                                          |
  +----------------------------------------- Select ( 1, 2, F, P, B or X ): _+

Here the default printer and/or file can be changed, and
output can be directed to one or the other or both.

The default printer is that indicated by @PR, @PT and @PD.
If the user elects to change it, the file pointed to by the
environmental parameter PFCONFIG, or the default filePro
"config" file, is read and as many ninety-nine printers that
are defined there-in are offered as options in a LISTBOX.

The default documentation output file name is:

  UNIX:     "/tmp/MenuName.txt"

  Windows:  "C:\temp\MenuName.txt", or
            "C:\WINDOWS\temp\MenuName.txt", or
            "MenuName.txt" in the current folder.

            (Chosen in that order according to where the
            program first finds a directory it which it
            may write.)

If the user types in a different output file name it is
checked for filePro having permission to write to it.

Typing [F], [P] or [B] continues with the documentation.
Selecting [B] brings up this MSGBOX:

          +----------------------------------------------------------+
          |                                                          |
          |   [Document the User Menu:]                              |
          |                                                          |
          |     [dpromenu] in [/appl/fp/menus]                       | 
          |                                                          |
          |   Directing Output to:                                   |
          |   ^^^^^^^^^^^^^^^^                                       |
          |     File: [/tmp/dpromenu.txt]                            |
          |                                                          |
          |     Print Command: [lp -s -dlaser]                       |
          |                                                          |
          |   [Select what is to be documented:]                     |
          |                                                          |
          |   [1] - Menu Screen         [2] - Action Command Lines   |
          |                                                          |
          |       - Long Descriptions   [4] - Shell Scripts          |
          |                                                          |
          |   [A] - All Features        [5] - Help File              |
          |                                                          |
          |   [Q] - Quit Selecting      [X] - Exit to Main Menu      |
          |                                                          |
          +------------------- Your Choice ( A, 1, 2, 4, 5, Q, X ): _+

Here, the extent of the documentation may be selected.

Notes:  1 - Option:

              [A] - All Features

            does a complete documentation.

        2 - For partial documentation, option:

              [2] - Action Command Lines

            prints the Choice Character, Description and
            Action Command Line:

               --------------------------------------------
              1- Define Files
                 /fp/ddefine
               --------------------------------------------

            Only menu Elements having Choice Characters are
            documented in this section.

        3 - For partial documentation, option:

              [3] - Long Descriptions

            is not offered until option:

              [2] - Action Command Lines

            is selected.  If selected, it would add the
            Long Description (if any) as the third line
            in the report as shown in #2 above.

        4 - Option:

              [5] - Help File

            is not offered if no Help File is associated
            with the Menu.

        5 - Only options [A], [Q] or [X] leave this screen,
            with [Q] leaving it only after at least one
            other option has been selected.

If a subset of the documentation features is selected, the
number of each subset selected displays, highlighted, to
the right of the line:

              [Select what is to be documented:]  [1 2 3]

Selecting [A] writes its output in this format:
================================================================================
  Menu Name:  dpromenu                                 Aug 13, 2001 @ 13:13:13
     PFMENU:  /appl/fp/menus
  ----------------------------------------------------------------------------
                             filePro Plus Main Menu                   04.08.00
  ----------------------------------------------------------------------------
      Creation Programs                       Runtime Programs

  1 - Define Files                        ? - filePro Directory
  2 - Define Screens                      A - Expand Files
  3 - Define Output                       B - Inquire, Update, Add
  4 - Define Edits                        C - Index Maintenance
  5 - Define Processing                   D - Request Output
  6 - Define User Menus                   E - Set/Change File Name
  7 - Printer Maintenance                 F - filePro Utilities Menu
                                          G - Run A User Menu
  8 - Define Processing - Quickstart      H - Inquire, Update, Add -Quickstart
  9 -                                     I - Request Output - Quickstart
  ----------------------------------------------------------------------------
  Legend:  Choice_Character- Description.
                             Action Command Line.
                             Long Description (if any).
  Only Menu Elements with Choice Characters are documented.
  ----------------------------------------------------------------------------
 1- Define Files
    /fp/ddefine
    Create/modify filePro file layout.
  ----------------------------------------------------------------------------
 2- Define Screens
    /fp/dscreen
    Create/modify data entry screens.
  ----------------------------------------------------------------------------
 3- Define Output
    /fp/dmoedef
    Create/modify report, forms, and label formats
  ----------------------------------------------------------------------------
 4- Define Edits
    /fp/deddef
    Create/modify user edits.
  ----------------------------------------------------------------------------
 5- Define Processing
    /fp/dcabe
    Create/modify processing tables.
  ----------------------------------------------------------------------------
 6- Define User Menus
    /fp/dmakemenu
    Create/modify user menus.
  ----------------------------------------------------------------------------
 7- Printer Maintenance
    /fp/pmaint
    Create/modify print codes.
  ----------------------------------------------------------------------------
 8- Define Processing - Quickstart
    /fp/rcabe
    Create/modify processing tables (Quickstart version)
  ----------------------------------------------------------------------------
 9- Change filePro Directories
    #/fp/changedir dpromenu
    Change directories where filePro programs may be found.
  ----------------------------------------------------------------------------
 ?- filePro Directory
    /fp/ddir
    Display information about filePro files.  Delete files and formats.
  ----------------------------------------------------------------------------
 A- Expand Files
    /fp/dexpand
    Pre-expand filePro files.
  ----------------------------------------------------------------------------
 B- Inquire, Update, Add
    /fp/dclerk
    Display/modify/create/delete records within a filePro file.
  ----------------------------------------------------------------------------
 C- Index Maintenance
    /fp/dxmaint
    Create/rebuild filePro indexes.
  ----------------------------------------------------------------------------
 D- Request Output
    /fp/dreport
    Generate reports, forms, and labels.
  ----------------------------------------------------------------------------
 E- Set/Change File Name
    #/fp/changename  dpromenu
    Set a default file name for filePro to use.
  ----------------------------------------------------------------------------
 F- filePro Utilities Menu
    !util
    Run the filePro utilities menu.
  ----------------------------------------------------------------------------
 G- Run A User Menu
    !
    This will ask for the name of the user menu to run.
  ----------------------------------------------------------------------------
 H- Inquire, Update, Add -Quickstart
    /fp/rclerk
    Display/modify/create/delete records within a filepro file. (Quickstart)
  ----------------------------------------------------------------------------
 I- Request Output - Quickstart
    /fp/rreport
    Generate reports, forms and labels. (Quickstart version)
  ----------------------------------------------------------------------------
  * * * There are no Associated Shell Scripts * * *

  ========= dpromenu HELP File =========

#		Help text for DPROMENU
#
#	Version: 4.1.00
#	Updated: 26 March 1991
#	     By: Laura Weathers
#
##(7,41,13,40,1) 1
#	ddefine - define files
 Allows you to create or modify the
 structure of a filePro file.

 You can also modify a file by
 changing field lengths and/or edit
 types, add a new field or delete an
 existing field. If the file contains
 data, the entire file will be
 restructured to make the existing
 data fit into the new structure
 definition.
##(8,41,9,40,1) 2
#	dscreen - define screens
 Allows you to create, copy, delete or
 modify data input screens that will
 be used with Inquire, Update, Add.
 A data input screen is the empty
 "form" that the user fills-in when
 he adds records to the filePro data
 file.
##(3,41,17,40,1) 3
#	dmoedef - define output
 In general terms, "output" is the
 results produced by the computer.
 filePro has five types of output -
 four printed and one for data
 processing only.  Define Output
 allows you to:

	define the data you want in
	    the printed materials &
	    what the print-outs
	    should look like.

	define the kinds of batch
	    processing you want & the
	    records to be processed.
##(10,41,10,40,1) 4
#	deddef - define edits
 This program lets you change or
 create edit (field) types. Edits are
 used in Inquire, Update, Add - after
 the user types the data, each entry
 is checked for errors.  Some edits
 change the data by adding punctuation
 or characters, and changing
 capitalization.
##(8,41,8,40,1) 5
#	dcabe - define processing
 filePro processing lets you run
 certain functions automatically
 whenever an event occurs, such as
 when saving a record, when entering
 or leaving a field, or when the user
 types a certain keystroke.
##(9,41,11,40,1) 6
#	dmakemen - define menus
 This program allows you to customize
 the entire filePro system. You can
 replace the standard filePro menus
 with your own menus, replace program
 headings with your own headings and
 automatically answer filePro prompts.
 Your users see only the prompts and
 messages that they need to see to run
 your application.
##(10,41,10,40,1)7
#	pmaint - printer maintenance
 Use this program to tell filePro
 about the printer(s) on your system.
 You can add, delete or change print
 code tables, then define up to nine
 printers by giving filePro a name
 for the printer, the print code table
 to use and the destination (which can
 be a hardware port, or a filename).
##(1,41,16,40,1)8
#	rcabe - QS define processing
 filePro processing lets you run
 certain functions automatically
 whenever an event occurs, such as
 when saving a record, when entering
 or leaving a field, or when the user
 types a certain keystroke.

 Using the Quikstart version of Define
 Processing allows you to create token
 tables which are needed if you wish
 to use the Quickstart versions of
 Inquire, Update, Add and Request
 Output.
##(3,1,17,40,1)  ?
#	dprodir - directory program
 Use this program to find out what
 filePro files are in the system, what
 the names of reports and selection
 sets are, whether or not processing
 tables have been defined for a
 particular file, and so on.

 You can also use it to delete a file,
 the data in the file, or any
 individual part of the file. You can
 also use it to delete formats
 (screens, tables, reports, etc.). It
 also allows you to delete the
 lockfile (multi-user systems only)
 when a file has been locked in error.
##(8,1,9,40,1)A
#	dexpand - expand files
 This program adds empty records to
 the system and can expand data files
 onto secondary hard disk drives (and
 logical drives in UNIX/XENIX).  It
 can also tell you how many more
 records of the current file can be
 added to each of your hard drives.
##(9,1,8,40,1)B
#	dclerk - inquire, update, add
 Inquire, Update, Add is the "file
 cabinet" of the filePro system, where
 your data are entered and stored.
 Once information is entered, it can
 be reviewed, copied, edited or
 deleted.
##(4,1,16,40,1)C
#	dxmaint - index maintenace
 This program enables you to create,
 delete and re-build indexes.  An
 index is a quick reference chart that
 filePro uses to find a record which
 contains desired information more
 quickly.

 There are two types of indexes.
 "Automatic" indexes (which are
 constantly maintained by filePro) are
 used mostly for inquiry operations.
 "Demand" indexes are used mostly with
 output programs to organize reports,
 mailing lists and other output.
##(11,1,8,40,1)  D
#	dreport - request output
 Use this program to generate reports,
 forms and mailing labels and do batch
 operations such as posting statements,
 archiving outdated records,
 recalculating math formulas and
 generating merge files.
##(10,1,9,40,1)  E
#	set/change filename
 This operation, which is actually
 part of the menu program, lets you
 specify which file to use.  Once you
 set a filename here, filePro won't
 ask you for a filename again until
 you reset it or completely exit
 filePro, and then run it again.
##(3,1,17,40,1) F
#	Run Utiliy menu
 From the utility menu, you can change
 the colors that filePro uses to
 display all screens (unless you have
 defined the new environmental
 variables).

 You can also set the site password
 which will give all of your
 processing tables this password.

 If you purchase and install
 additional utility programs, such as
 fpTransfer, fpCapture, fpCopy or
 fpSQL, they will be accessible
 from this menu.
##(14,1,4,40,1)  G
#	runmenu - run a user menu
 Use this program to run menus that
 you created in Define User Menus.
##(9,1,14,40,1)  H
#	rclerk - QS inquire, update, add
 Inquire, Update, Add is the "file
 cabinet" of the filePro system, where
 your data are entered and stored.
 Once information is entered, it can
 be reviewed, copied, edited or
 deleted.

 If your application uses processing
 tables, you must use QuikStart Define
 Processing to create a token table
 for each processing table in the
 application.
##(9,1,14,40,1)  I
#	rreport  - QS request output
 Use this program to generate reports,
 forms and mailing labels and do batch
 operations such as posting statements,
 archiving outdated records,
 recalculating math formulas and
 generating merge files.

 If your application uses processing
 tables, you must use QuikStart Define
 Processing to create a token table
 for each processing table in the
 application.

----- END of Documentation for: dpromenu
================================================================================

If the menu contains text in its "Remarks" field and it has
been elected to print the Menu Screen, that text is printed
just below it: 
  ----------------------------------------------------------------------------
  Remarks: This menu was edited by RCS on 04/18/2001.
  ----------------------------------------------------------------------------

If there are Associated Script/Batch Files their lines are
documented in this fashion:
  ----------------------------------------------------------------------------
 =========================
 Associated Shell Scripts:
 =========================

 ---- MenuName.-C ----
#!/bin/ksh
print "$cl"
cal

If the Script/Batch File is not executed by an Action Command
Line in the form "/fp/menu/MenuName.-" it is indicated as being
an "orphan":

 ----MenuName.-F ---- >>> Orphan <<<

================================================================================

The nice thing about the Documentation feature is that
if you don't like the way it works you can change it.

In fact that pretty well sums up MENU EDIT II:

  If you don't like the way it works you can change it.
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Please send bug reports, feature requests or suggestions
for cosmetic changes to the author.

fpsuuport@fptech.com

                                 - 0 - 0 - 0 -
