Category : File Managers
Archive   : TPMNUS16.ZIP
Filename : TPMNU.DOC

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ ³
³ TpMnu ³
³ A Menu Utility Program ³
³ Version 1.6 March 22, 1990 ³
³ ³
³ Mark D. Rafn ³
³ Rt1 Box138A ³
³ Two Harbors, MN 55616 ³
³ ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

Revision Record
Addendum 1 16Dec89
Addendum 2 21Mar90

TPMNU.EXE is a menu utility program written in Turbo Pascal 5.5
for non-programmers who are familiar with MS/DOS batch files and want
to run menus to load their various programs. It also works well as a
Network menu system where there may be several users unfamiliar
with MS/DOS commands or Network menus' RAM usage prohibits use of
640k programs. (A Network structure is where this program originat
ed.) The program is run under a host MS/DOS batch file and a basic
understanding of MS/DOS batch command processing is all that is
needed.


IN SHORT: The TPMNU.EXE program is loaded from a looped batch
file, called the 'host'. The menu creates a generic batch file based
on the selection and its associated command lines, then exits to the
host file. The host batch file then 'calls' the generic batch file
that was created by the menu program. After the selected program
terminates, control is passed back to the host batch file and the loop
is repeated.

Because TPMNU.EXE is run under a host batch file, the menu system
uses 0k of ram and programs requiring a full 640k can be successfully
run. TPMNU.EXE works for both mono adapters and EGA adapters and
autodetects/enables a mouse. The program was also created to be as
transparent as possible, with no background screen.




PROGRAM CRITERIA IN BRIEF:

1) Create an ASCII data file containing menu selection text
as it will appear in the menu and associated command lines
in batch form. Optional menu position, colors, and prompts
can also be specified. This data file is passed as an argu-
ment to TPMNU.EXE

2) Create a loop batch file to act as host.

3) Set DOS environment variable "TPMNU" equal to a batch
file name.





DATA FILE
The ASCII data file must be a nondocument type file with no
extraneous characters. The '[ ]' characters are used for denoting pro
gram parameter words and line numbers. Parameter words between the '[
]' characters must be in lower case. The '^' character is used in the
menu text line to denote the Alt function or 'Hot' key. This symbol
precedes the Alt character. Spaces serve as seperators between menu
entries. Optional lines at the beginning of the file provide for
custom colors, location, and prompt line.

COLORS - an optional line at the beginning of the file provides
for custom coloring of the menu. It is denoted by using [colors] as
the parameter word followed by numbers corresponding to standard color
numbering systems. Each color however, must be two integers. No spaces
are used between color numbers. Only the first 8 colors are allowed
for any background color. The default colors are NORMAL TEXT - Black
text on Cyan background; SELECTION BAR - White test on Red background;
ALTKEY - Red text on Cyan background. A mono adapter is autodetected
and ignores the color line, using default mono attributes.

[colors]< Normal text foreground >< Normal text background >
< Selection Bar foreground >< Selection Bar background >
< Altkey foreground >< Altkey background >

Black - 00 DarkGray - 08
Blue - 01 LightBlue - 09
Green - 02 LightGreen - 10
Cyan - 03 LightCyan - 11
Red - 04 LightRed - 12
Magenta - 05 LightMagenta - 13
Brown - 06 Yellow - 14
Lightgray - 07 White - 15

example: [colors]000715041507

LOCATION - Another optional line is for positioning a menu at
other than the default setting of 01,01. The line is denoted by using
the parmeter word [locate] followed by the position in x,y coordinates
of the upper, left corner of the menu. Each coordinate is a two digit
integer corresponding to the horizontal and vertical screen position
for text screens ( max 80,25 ). The program will self-justify if the
menu excedes the screen in both x and y directions.

example: [colors]000715041507
[locate]0612
locate upper,left corner at X (horizontal) = 6
Y (vertical) = 12

PROMPTS - Optional lines providing for prompt line capabilities
can also be added to the beginning of the file. The parameter words
[esckey],[altxkey], and [f1key] provide text supporting their special
functions. ( These special functions are handled by the exit code of
the program and controlled by the host batch file; see below, section
2). Maximum number of characters for each parameter is 12. Text will
appear exactly as it appears after the ']' character, including lead
ing spaces. Any, all or none of these parameters may be used. If none
are used, no prompt line will appear.

example: [colors]000715041507
[locate]0612
[esckey]-LOGOUT
[altxkey]AltX-EXIT
[f1key]F1-????????????

MENU - After the optional lines comes the menu section itself. The
start of the menu section must be marked by the parameter word
[startmenu].The program will allow for 22 menu lines. Each menu entry
is tagged with its sequence number. The sequence number is contained
within the '[ ]' characters. The text following the sequence number is
the text as it will appear in the menu window. Use of the '^' symbol
will assign the following character as the Alt function or 'Hot' key.
This 'Hot Key' is case insensitive, lower case characters appear the
same as upper case to the program. Next, batch command lines assoc-
iated with the menu selection are placed immediately below the menu
line. These command lines are the lines DOS will execute in batch
mode upon a menu selection. They should appear exactly as they would
in a batch command file. Each menu selection and its associated com-
mand lines are seperated from the next menu selection by a blank line.
Command lines are written to the DOS environment variable 'TPMNU'.

example:
[colors]000715041507
[locate]0612
[esckey]-LOGOUT
[altxkey]AltX-EXIT
[f1key]F1-????????????
[startmenu]
[1] e^Ditor program { Menu selection line1, Alt function key 'D' }
c: { batch commands }
cd\editdir { " }
edit { " }
cls { " }
d: { " }
{ blank line }
[2] ^Cad program { Menu selection line2, Alt function key 'C' }
mouse
mode com1:12,8,0
c:\caddir\cad

[3] etc.





HOST BATCH FILE

The host batch file is the principle command file that would be
entered from the DOS command line to start the menu and execute any of
the menu selections picked. A loop should be contained in this file to
re-initialize the menu after exiting the selected program. This batch
file uses the DOS environment variable %TPMNU% as a dummy parameter to
execute the set of command lines written by the menu program. For DOS
versions 3.3 and later this is done with the DOS 'call' command. For
DOS versions prior to 3.3, a copy of command.com must be issued using
the /C switch. These procedures must be used to insure return to the
host batch file after the called program exits. If you do not include
a drive and path along with TPMNU.EXE, you must set PATH= the directo
ry where TPMNU.EXE resides. The same applies to the
ASCII data file argument. An example of a host batch file in its
simplest form follows:

(v3.3) REM Host.bat (prior v3.3) REM Host.bat
@Echo off Echo off { note no @ }
:Loop :Loop
TPMNU Menu.dat TPMNU Menu.dat
call %TPMNU% COMMAND /c %TPMNU%
goto Loop goto Loop

As an added feature, if you want to get fancy with your host file, the
following errorlevels are returned based on the menu program termina
tion.
Program I/O Error ERRORLEVEL 1 { addendum 2 }
Escape key pressed ERRORLEVEL 27
AltX key pressed ERRORLEVEL 45
F1 key pressed ERRORLEVEL 59
( FYI: These, by no coincidence, correspond to the correct scancodes
of the key pressed.)

They could be used as such:

REM Host.bat
@Echo off
:Loop
TPMNU Menu.dat
if ERRORLEVEL 59 goto NewMenu
if ERRORLEVEL 29 goto Quit
if ERRORLEVEL 1 goto EscapeMenu
call %TPMNU%
goto Loop
:NewMenu
TPMNU NewMenu.dat
call %TPMNU%
goto Loop
:Quit
:EscapeMenu





ENVIRONMENT VARIABLE

The MS/DOS environment variable "TPMNU" contains the batch command
filename written to by TPMNU.EXE and called by the host batch file.
The file must contain the .BAT extension. This varible can contain the
full path and filename if you do not want it to reside in the same
directory as the menu program. If you do not specify a path, the file
written by TPMNU will reside in the current DOS directory. It is
recommended using a full path/filename throughout the program files to
avoid confusion as to where the program is Reading/Writing to unless
you have a clear understanding of the relationship between PATH and
file accessing. In the case of Networked systems, the user must have
full Read/Write capabiities to this directory. Use the DOS 'Set'
command in your Autoexec.bat as such,

SET TPMNU=C:\BATCH\RUNMENU.BAT





======================================================================
QUERY.EXE
======================================================================

This utility program is not necessary to run TPMNU, but it allows
for a user response to a Yes/No question from a batch file and take
appropriate action. I use it quite frequently in various batch files
and you might find it useful.

QUERY.EXE simply returns an appropriate errorlevel based on the
answer to a yes/no question. Errorlevel 1 is returned if the answer is
NO. This errorlevel is handled in the batch file by using the GOTO
label instruction. A maximum of 20 words or 80 characters can be used
with the program.

EXAMPLE: ( Autoexec.bat )

@echo off
prompt=$P$G
path=C:;C:\DOS
QUERY Do you want to run Dos FASTOPEN?
if errorlevel 1 goto END { skip over fastopen command }

echo Loading FASTOPEN
Fastopen C:=150 D:=50

:end





======================================================================
INCLUDED FILES
======================================================================

TPMNU.EXE Menu utility program
TPMNU.DOC This file
MNUEXP33.BAT Host batch file to show sample menu, Dos v3.3
MNUEXP30.BAT Host batch file to show sample menu, prior to Dos v3??
MNUEXP33.DAT Menu data file containing menu configuration for samples
QUERY.EXE Yes/No utility program for batch files


======================================================================
ADDENDUMS
======================================================================

Addendum1 - Release v1.5:
With the release of v1.5, the '/p' option has been incorporated to
provide for menu paging. This paging feature allows for 10 menu ent-
ries per page, 10 pages per menu. Without the paging switch, the menu
still is a single page consisting of no more than 22 menu entries. To
activate the paging feature use /p after the filename entry. The ASCII
data file will hold all the information for up to 100 entries. The hot
key is page dependant so just make sure not to use the same letter for
the AltKey function on the same page more than once. You can repeat
the same letter after 10 entires ( new page ).
You can successfully use the F1 key (or Esc, AltX) errorlevel ret-
urn and run another TPMNU program with another data file and thereby
increase the standard menu from 22 to 44 entries or the paging menu
from 100 to 200 entries.

pageing example: TPMNU /p

Addendum2 - Release v1.6
Added Ctrl-Break ISR procedure to prevent keyboard lockup if errors
are encountered in command file. Also added errorlevel exit code (1)
for abnormal program termination. See Errorlevel documentation in the
HOST BATCH file section for implementation.

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

These programs are provided to you free of charge as ShareWare.
(Please read SHAREWRE.TXT) You may use it, copy it for your friends,
upload it to your favorite BBS, etc. provided all accompanying files
are distributed intact and unmodified. If you continue to use Tpmnu
and would like to reward the efforts of this author, please consider
sending a small contribution ($10 suggested) to me at:

Mark D. Rafn
Rt1 Box 138A
Two Harbors, MN 55616

Once a you have done so, you are considered a 'registered' user
and can expect prompt replys to coorespondence as well as the latest
version. A copy of the source code for TPMNU and QUERY will also be
supplied if requested by registered users. A registration form has
been provided for your convenience. The author retains ALL rights
to this program.

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







REGISTRATION FORM



Dear Mark,

Enclosed please find my check or money order for $________.
Please register me as a TPMNU user and send me the latest version
if my current version is not the latest.

Thanks!


NAME ____________________________________________________________

ADDRESS _________________________________________________________

CITY-STATE-ZIP __________________________________________________

TPMNU version ___________________________________________________

TPMNU acquired from _____________________________________________

COMMENTS ________________________________________________________

_________________________________________________________________

_________________________________________________________________

_________________________________________________________________