ANSIPLAY vs. 2.1 - Copyright 1991, J. Ibarra
ALL RIGHTS RESERVED
U S E R ' S M A N U A L
(updated 08/12/91)
INDEX: PAGE NO.
------------------------------------------- --------
Copyright Notice and Regulations . . . . . . . . 2
Introduction . . . . . . . . . . . . . . . . . . 3
Files included with the program. . . . . . . . . 4
Printing the manual. . . . . . . . . . . . . . . 5
How ANSIPLAY works . . . . . . . . . . . . . . . 5
INSTALLATION program . . . . . . . . . . . . . . 6
Editing your ANSI file . . . . . . . . . . . . . 6
Using alternate characters in place of ESC . . . 7
Music string syntax. . . . . . . . . . . . . . . 7
Music string contents. . . . . . . . . . . . . . 7
Music codes / Sound codes definition . . . . . . 8
Using Music Codes. . . . . . . . . . . . . . . . 9
Using Sound Codes. . . . . . . . . . . . . . . . 9
Variation in Music String formats. . . . . . . . 11
Music string Tutorial (TUTOR.BAT). . . . . . . . 11
Making the music strings invisible . . . . . . . 12
Using ESC/Music Note characters during editing . 13
Getting familiar with ANSIPLAY . . . . . . . . . 13
ANSIPLAY command syntax (and options). . . . . . 13
File viewing with /L option. . . . . . . . . . . 14
Reinitializing the display screen (ANSIPLAY.CLS) 15
Removing music strings (MUSCSTRP.EXE). . . . . . 16
How ANSIAUTO works (slide-show). . . . . . . . . 16
Running ANSIAUTO . . . . . . . . . . . . . . . . 17
Using PLAY.EXE (music string player/editor). . . 17
Registering ANSIPLAY . . . . . . . . . . . . . . 19
APPENDICES . . . . . . . . . . . . . . . . . . . 20-24
* Page 1 *
First of all, let me get this over with...
COPYRIGHT NOTICE AND REGULATIONS -- Please read !!!
--------------------------------
THIS CONDITION STATEMENT SUPERSEDES ALL PREVIOUS AGREEMENTS.
ANSIPLAY and included files are NOT Public Domain and they
are not free. All copyrights to ANSIPLAY and included files are
reserved by the author, Julie M. Ibarra, and are protected by
United States Copyright Laws. ANSIPLAY is distributed under
the ShareWare concept.
To continue development/enhancement of ANSIPLAY to make it the
quality program you expect depends solely on the honesty and
integrity of YOU, the ANSIPLAY user.
The Copyright notice which is displayed after each file is
viewed will not be shown on registered versions of ANSIPLAY.
Non-registered users of this program are hereby granted a limited
license to use ANSIPLAY and included files to and see if it
fullfills their needs.
If you intend to use ANSIPLAY or included files for usage other
than this limited purpose you are required to register each copy
used.
Use of ANSIPLAY by non-registered people outside of this limited
license is prohibited. Violators of the license will be held
accountable for their actions in a Court of Law and may face
financial penalties and/or imprisonment.
User's are free to use ANSIPLAY and included utilities for a trial
period of 30 days. If after 30 days you decide to keep the program,
you must register your copy by sending the required payment to the
author. Failure to register your copy after 30 days is in direct
violation of copyright laws.
Neither ANSIPLAY nor any of the included program files nor
documentation may be altered in any way.
Non-registered versions of ANSIPLAY (and included files) may be
distributed freely in unaltered form provided that NO CHARGE is
made for the program itself (postage and disk costs excluded).
All files and documentation must be included.
System Operators may make ANSIPLAY available for download only if the
above conditions are met.
Distributors of "Public Domain", "Shareware", and/or User Supported
software may distribute ANSIPLAY and included files subject to the
above conditions only after obtaining WRITTEN permission from
The author, Julie M. Ibarra.
This product is provided "AS IS" WITHOUT WARRANTY OF ANY KIND.
The entire risk as the results and performance of the PRODUCT is
assumed BY YOU.
* Page 2 *
In NO event shall the author, nor employees of the author be
liable for any damages whatsoever (including without limitation
damages for loss of business profits, business interuption, loss
of business information and the like) arising out of the use of
or inability to use this product even if the author has been
advised of the possibility of such damages.
This license does not apply to the REGISTERED version of
ANSIPLAY. Different conditions and agreements pertain to the
REGISTERED version of ANSIPLAY, and are included with all
registration orders.
INTRODUCTION
------------
If you have this program, more than likely you are already
familiar with ANSI control sequences. But just for sake of
reference, here's a few more details about what ANSI is and
how it works.
ANSI (American National Standards Institute) control sequences
are simply sets of characters which, when put together, will
enable computer-users to have extended control over their display
screen.
This extended control is given by DOS's device driver, ANSI.SYS,
which reads these sets of characters, interprets them, and then
processes the commands by moving the cursor positions, changing
screen colors, etc. They also will allow your monitor to display
the extended ASCII character set (Decimals 128 - 255).
These sets of characters are referred to as Escape Command
Sequences. In other words, a sequence of commands preceeded by
an Escape character (Decimal Character 27).
Each computer system processes these command sequences at
different speeds...for example, an AT will processes much
faster than an XT.
There are several software packages which allow the user to edit
and save these command sequences into a file (called an ANSI
file) without having to know the actual command sequences.
Some of these (Such as Shareware's "THE DRAW") will
allow you to specify the speed of which you want the ANSI file
to be displayed.
Once the ANSI.SYS device driver is installed in DOS (Disk
Operating System), these ANSI files may be displayed by simply
typing a DOS command something like:
TYPE FILENAME.ANS
Installation of ANSI.SYS is discussed later in this manual.
Until now, the ANSI files have had one drawback...they have
screen control, but no sound.
* Page 3 *
ANSIPLAY was developed for the purpose of adding music/sound
ability to ANSI files. ANSIPLAY is NOT intended to be an ANSI
editing program such as the well known Shareware program
"TheDraw" which enables on-screen selection of colors, cursor
positions and movement, etc., but rather ANSIPLAY is intended
allow the user to use ANY ANSI file and, by adding a few extra
escape command sequences (we'll call them music codes), enable
the integration of screen display and music/sound/pauses to it.
Once these music codes are added to the file (by use of most any
text editor), the simplest command used to display/play them
would replace the 'TYPE' command with 'ANSIPLAY', thus something
like:
ANSIPLAY FILENAME.ANS
Later in this manual is a more detailed breakdown of command
syntax and additional options available with ANSIPLAY.
One thing to remember: Adding music strings to the file
is kind of like putting icing on the cake...it's the final
touch to your ANSI file.
You can't re-bake the cake once the icing's been put on it,
and you can't reconstruct the ANSI file with an ANSI editor
(such as "The Draw") with the music strings in it. The reason
being that the editor will try to interpret the escape
sequences containing music strings as text, therefore displaying
it to screen.
You CAN however, remove the music strings using MUSCSTRP.EXE,
to make the file compatible for the ANSI editor again.
(Refer to the section on "Removing Music Strings".)
A text editor, of course will interpret ALL characters as text
so there's no problem there.
FILES INCLUDED
--------------
Files included with this package are as follows:
---Program Files---
INSTALL .EXE - Installation program (please read INSTALL.DOC)
ANSIPLAY.EXE - Program to read/display/play ANSI files.
ANSIAUTO.EXE - Program to automate ANSIPLAY.EXE into a
slide-show.
PLAY .EXE - Allows you to play a music string from the
DOS prompt.
MUSCSTRP.EXE - Removes music strings from your ANSI files.
GO .BAT - An Introduction to the entire program package.
TUTOR .BAT - A brief tutorial on some of ANSIPLAY's more
advanced features. (Read this manual first.)
* Page 4 *
---Documentation---
INSTALL .DOC - Information of using the INSTALLation program.
OVERVIEW.DOC - A quick look at most of ANSIPLAY's features.
ANSIPLAY.DOC - User's Manual (This documentation).
ANSICODE.TXT - Listing of ANSI control sequences available.
MUSICODE.TXT - Listing of Music and Sound codes available to
be used with ANSIPLAY.EXE.
ORDER .FRM - Registration Form to purchase your registered
and most current version of ANSIPLAY.
UPDATE .TXT - Info. about changes made from prior versions.
BBS .TXT - Some pointers for BBS user's
---Data Files---
ANSIAUTO.DAT - Sample Data file used with ANSIAUTO.EXE.
INTRO .ANS - Data file used with GO.BAT
TUTOR .ANS - ANSI file used with TUTOR.BAT
XMASTREE.ANS - Demonstration ANSI file (using music codes)
FAUCET .ANS - Demonstration ANSI file (using sound codes)
SEA .ANS - Demonstration ANSI file (using music and sound codes)
PRINTING THE MANUAL
-------------------
The installation program (INSTALL.EXE) will allow you print
any/all documentation included with the ANSIPLAY program package.
If you'de rather print the manual from the DOS prompt, log onto
the drive/directory in which this file (ANSIPLAY.DOC) exists, and
type COPY ANSIPLAY.DOC PRN.
All other documentation files/order form may be printed the same
way by using different filenames. Form-feeds are included at the
end of each text file.
HOW ANSIPLAY WORKS
------------------
When you run ANSIPLAY, you will specify the filename of the file
you want to be displayed/played. ANSIPLAY will read the file and
display it to the screen using the ANSI.SYS device driver, while
at the same time, searching for music codes which tell ANSIPLAY
what music notes/sounds to play.
The music codes are NOT ANSI escape command sequences, but rather
they are interpreted and processed by ANSIPLAY.
ANSIPLAY will be just slightly slower than DOS's TYPE command
since it must search the text for each music string and process
it accordingly. DOS's TYPE command will process the strings as
text. The text may be made hidden (invisible) by embedding
additional escape command sequences in the ANSI file. (Refer to
the section on "Making the music strings invisible".)
* Page 5 *
Shareware versions will then display a short message in ANSI
to remind users that the version in not registered. This message
is not displayed with registered versions.
INSTALLATION (INSTALL.EXE)
--------------------------
Installation will allow you to do the following...
1. Installation of your ANSI device driver into your
CONFIG.SYS file.
2. Setting a PATH in your AUTOEXEC.BAT file
(for use with ANSIPLAY program files).
3. Creating/Updating your ANSIPLAY.CLS file.
4. SETting an environment variable via your AUTOEXEC.BAT file
(for use with the file ANSIPLAY.CLS)
5. Option to print documentation file(s).
To run the installation program, type INSTALL at the DOS prompt.
A two-page document (INSTALL.DOC) gives more information on
these options. To print INSTALL.DOC while in the INSTALL program,
answer Yes when asked..."Print the file INSTALL.DOC now ?".
About your ANSI device driver
-----------------------------
Many programs use ANSI control characters, but if the device
driver ANSI.SYS is not installed before comming accross them,
you'll just get a lot of funny looking characters that don't mean
much.
The ANSI device driver "ANSI.SYS" is included in your own DOS files.
The installation program will determine whether or not the driver
is already installed. If you're still wondering, you can type
'ANSIPLAY' at the DOS prompt. When the copyright message is
displayed, if you see color, the driver is installed. If you get
a menagery of strange characters on the screen, the driver is NOT
installed.
Once the ANSI device driver is installed into your CONFIG.SYS,
it will be loaded automatically each time you boot up.
If you wish to install the driver manually rather than using the
included installation program (INSTALL.EXE), consult your DOS
user's manual for information on how to do this.
EDITING YOUR ANSI FILE
----------------------
If you are starting from scratch, you may want to look into an
ANSI screen editor such as the Shareware program "TheDraw".
Without such a program, ANSI file creation can be tackled, but it
would be extremely tedious and time-consuming at best.
* Page 6 *
Your DOS user's manual will explain the escape control sequences
used with ANSI.SYS. There is also a reference listing included
in the file ANSICODE.TXT (see section on "printing the manual").
One example would be, to set the foreground color to bright
yellow on a blue background...
ESC[44;1;33m
Unless you're very familiar with these escape sequences, it can
be a bit like learning a foreign language.
USING ALTERNATE CHARACTERS IN PLACE OF ESC
------------------------------------------
If for some reason the ESC character is stripped, for instance
by a BBS that does not allow extended ascii characters during
file transfers, etc., ANSIPLAY will still process the file:
ANSIPLAY will detect the non-existance of the ESC characters when
none are found within the first block of characters read. Then it
will determine the alternate character automatically by locating
the first "[" occurance in the file and using the character prior
to the "[" as the alternate character. ANSIPLAY will then auto-
matically replace every occurance of this alternate character
with the ESC character.
If character replacement is used this way, the display rate may
be slightly slower, but barely noticeable.
MUSIC STRING SYNTAX
-------------------
Once your ANSI file has been created, all that's left to do to
make it musical is add a few extra escape command sequences, for
example, a music code of...
ESC[MF O2 CDEC CDEC EFG.... EFG....(music note)
would play the introduction to the song "Frere Jacques".
Below is a breakdown of how the music strings are to be used.
By using your own text editor, you can insert these codes into
any desired location in your ANSI file, then play it back using
ANSIPLAY.EXE.
(see section below on using ESC character during editing)
MUSIC STRING CONTENTS
---------------------
The word "string" simply means a set of characters (including
spaces and ascii characters) strung together.
* Page 7 *
There are 3 sections to a Music string, broken down as follows:
ESC[MF CDEC CDEC EFG (music note)
------ ------------- ------------
1 2 3
All music strings must be prefixed with ESC+"["+"MF" (or "MB") in
upper-case text, and final character must be a (music note).
1. Music strings are prefixed with the ESCape character followed
by a [ character (just like ansi escape control sequences),
and then followed by MF (for Music/Sound to be played in
Foreground) or MB (for Music to be played in Background).
*Or for a shortcut you may use ESC[M which will
be treated as ESC[MF.
*** Note that the ESC above actually resembles the ESCAPE
character (Decimal CHR$(27)) and not the actual letters
E S C. Refer to the section on "Using the ESC character
during editing".
2. The middle part of the string can be 1 of 2 types of
commands...
Music Codes
-----------
a) the actual <notes, octaves, etc> specification
(for musical tunes).
Spaces and carraige returns (CR-LF) are ignored.
This portion of the music string can be of any
size length.
-or-
Sound Codes
-----------
b) a <tone frequency; duration; cycles; delay; vari>
specification (for other sound tones and
repeated cycles of sound tones).
Parameters must be separated by semi-colons.
Details on these codes and command syntax will be discussed
shortly. There is also a reference listing of the codes in
the file MUSICODE.TXT (see section on "printing the manual").
3. The final(music note) (Decimal CHR$(14)) is a must.
This tells ANSIPLAY where the music string ends. The
(music note) character can be entered on most text editing
programs by holding down the [ALT] key, then typing the
number 14...similarly to entering the ESC character.
(See "Using the ESCape character during editing")
* Page 8 *
-------------------------------
USING MUSIC CODES
-------------------------------
ESC[MF <music notes and commands)> (music note)
(MB may be used in place of MF)
Example: ESC[MF CDEC CDEC EFG (music note)
MF will play the music in the foreground, or in other words will
stop displaying temporarily until the music string is played
completely.
MB will place the music string into a buffer, allowing the
program to execute while the music string is playing in the
background.
The number of notes that can be played in the background at
one time varies according to the particular machine. Maximum
number of notes that can be played in the background at one
time is 32.
When there are more notes to be played than the buffer will hold,
the display will temporarily pause until the remainder of the
music string is processed.
More than 1 MB statement in the music string will cause the
music to be played sequentially (NOT simultaneously.) In other
words, you cannot play 2 or 3 strings of music simultaneously.
If a carraige return (CR-LF) is needed within the music string,
ANSIPLAY will ignore it and just continue playing. This feature
was developed so that user's could use L-O-N-G strings of music
without interruption.
A breakdown of MUSIC CODES available are listed in the file
MUSICODE.TXT. (refer to section on "Printing the Manual").
You may also consult your DOS user's manual under the section
on BASIC's "PLAY" statement.
See the demonstration ANSI files included with this package
for some examples of how MUSIC CODES may be used.
-----------------------------------------------
USING SOUND CODES (IN PLACE OF MUSIC CODES)
-----------------------------------------------
In place of music codes, you may use numeric values for FREQENCY,
DURATION, CYCLES, DELAY and VARIATION to create sounds that are
not available with musical code syntax. Another way to use them
is to place them next to music strings that contain music codes
to add glissando, rythmatic sounds, tapping, beeping, or whatever
sounds you'de like to create. A music string containing SOUND
CODES would look like this:
ESC[MF <FREQ; DURA; CYCLES; DELAY; VARI> (music note)
* Page 9 *
Example: ESC[MF 100;5;5;10;-5 (music note)
The <> brackets are not to be typed. They are only there for
display purposes to you can see where the <SOUND CODES> are to be
placed.
Since SOUND CODES are processed differently from MUSIC CODES,
SOUND will always be played in foreground regardless of "MF"
or "MB" specification.
SOUND CODE Parameters must be separated by semicolons.
Minimum/Maximum values and descriptions are as follows:
FREQUENCY : a numeric value from 37 to 32,767
Frequency is the desired frequency in hertz.
This allows more control over the pitch of the
tone than what is available with music codes.
DURATION : an numberic value from 0 to 65,535
Duration is how long the tone should play, measured
in clock ticks. There are 18.2 clock ticks per second
regardless of CPU speed.
CYCLES (optional) : an integer from 0 to 9,999
Cycles is the number of times to repeat the
frequency/duration.
DELAY (optional) : an integer from 0 to 999,999,999
Delay is the length of pause between cycles.
ANSIPLAY will count from 0 to DELAY before proceeding.
The DELAY time lapse will vary among computer systems.
(My XT NEC V20 averages 723 counts per second)
If the [ENTER] key is hit during execution of a DELAY,
the delay will be ended.
VARIATION (optional): an numeric value from -9,999 to 9,999
Variation will change the FREQUENCY each time the tone
is repeated using the CYCLES variable. FREQUENCY will
use it's current value, add the VARIATION value to
itself (per cycle) to get a new FREQUENCY, then play
the new FREQUENCY.
A negative value used for VARIATION will make the
FREQUENCY decrease; a positive value will make the
FREQUENCY increase. If the new FREQUENCY is too low
or too high, exceeding its playable limits (minimum of
37 to maximum 32,767) then the VARIATION value will be
changed to reverse itself (from positive to negative,
or from negative to positive).
A "*" wildcard may be used in place of a value, which
will make the play function select a value at random
between -999 and 999.
* Page 10 *
Any non-integer numbers used for CYCLES or DELAY will be
converted to integers automatically.
SOUND CODES are interpreted and executed as they are read,
therefore requiring them to be played in the foreground.
The interpretation process is basically structured like this:
:START_OF_CYCLE
Play Frequency/Duration
Add DELAY if applicable
Change Frequency if VARIATION is used
Go to :START_OF_CYCLE (Loop for number of CYCLES specified)
See the demonstration ANSI files included with this package
for some examples of how SOUND CODES may be used.
VARIATION IN MUSIC STRING FORMATS
---------------------------------
Although there are several ANSI viewers on the market which
support music, there is currently no "standard" as to the format
used with the music strings.
Some viewers will not support music strings of a length longer
than 71 characters. Some viewers use a Prefix with ESC[M while
others use ESC[MF or ESC[MB. Some viewers will support music,
but only if it's the final text of the file, not if it's
integrated into the file.
Many viewers will not support one continuous music string thus
requiring the string to be broken into segments. This may cause
the music to sound choppy when it's played.
ANSIPLAY will support all of the above formats, along with
unlimited music string length and sound codes. Though if you
wish to use another viewer, you will need to consult the
documentation included with the program regarding the required
format for that program. Sound codes, however, will most likely
not be supported as they are a new concept just released by the
author of ANSIPLAY. Hopefully, they will soon be supported by
other ANSI viewers as well.
TUTORIAL FOR MUSIC STRINGS
-------------------------
Now that you are somewhat familiar with music code and sound
codes...you can see a more detailed explaination of some
of the more advanced way in which these codes can be used
by typing TUTOR at the DOS prompt. This will ansiplay the
file TUTOR.ANS which will give some examples and define how
they are used. Then it will bring you into ANSIAUTO to display
the demonstration ANSI files which are included with the program
package.
* Page 11 *
MAKING THE MUSIC STRINGS INVISIBLE
----------------------------------
Since the music strings are interpreted by ANSIPLAY while the
file is being read, the music string text is not displayed to
the screen. However, if you also wish to not display the strings
while using DOS's TYPE command to view the file, this may be done
by adding a few extra ANSI escape command sequences.
Before the music code, add:
---------------------------
ESC[0m ESC[s ESC[?;1H ESC[8m
(text is upper/lower-case sensitive)
Spaces should not be typed...they are only here to make the
codes easier to read.
Here is the breakdown:
ESC[0m Turns all attributes off. If the display is in
high intensity mode, this is required.
ESC[s Store the current cursor position.
ESC[?;1H Wherein ? would be the current row number. Any row from
1-24 may be used, however if the cursor has to move
all the way across the display, it may cause blinking.
"1" sets the cursor at column 1. Even though the text
will be invisible, it will still be printed to
screen. If the end of screen is reached, the text
will be wrapped around to the next row. If you are
using long music strings and it is causing the
display to eject upward, you may try using shorter
strings of about 75 characters or so at a time.
ESC[8m This will make the music string invisible when it is
written to screen. Otherwise it will be written to
screen in the current color attributes.
After the music code, add:
--------------------------
ESC[u ESC[0m
(text is upper/lower-case sensitive)
Spaces should not be typed...they are only here to make the
codes easier to read.
Here is the breakdown:
ESC[u Moves the cursor back to the location it was at
when the last ESC[s command (store cursor) was used.
ESC[0m Returns to normal mode. Turns off invisible
attribute.
* Page 12 *
The entire set of commands would look like this...
ESC[0m ESC[s ESC[?;1H ESC[8m ESC[MF<music string>
(music note) ESC[u ESC[0m
Remember, making the music codes invisible is only necessary if
you wish to use an ANSI display program other than ANSIPLAY.
USING THE ESCAPE CHARACTER DURING EDITING
-----------------------------------------
If you use DOS's edlin command for text editing, you will not be
able to enter an ESCape character (ASCII character CHR$(27)),
since hitting ESCape will type a \ character instead.
Most word/text editing programs will allow you to enter an ESCape
character by holding down the [ALT] key, then simultaneously
entering the number 27. Usually this is displayed as a left
arrow character. (Music note would be [ALT] + 14).
If you use a commercial word processor such as Word Perfect or
Word Star, the text must be saved as plain ASCII text format.
Otherwise there will be extra printer codes embedded into the
file which will mess up the whole thing.
If you do not have a text editor, I recommend a Shareware
program called QEDIT. It's very powerful and does allow extended
ASCII characters.
The (music note) character may be entered the same way as the
ESCape character by using the decimal 14 instead of 27.
GETTING FAMILIAR WITH ANSIPLAY
------------------------------
To see the demonstration files, at the DOS prompt type DEMO.
To get familiar with the program and included files, type GO.
RUNNING ANSIPLAY
----------------
Syntax from the DOS prompt is as follows:
ANSIPLAY [Path\FileName DelaySeconds] [/Option Flags]
(If no parameters/options are used, ANSIPLAY will default
to the /L option as described below, which will automatically
bring up a file(s) listing menu to work from.)
Parameters are:
[Path\Filename]
is the drive\directory\filename of the ansi file you wish to
display/play. Wildcard characters * and ? are not supported.
If no filetype is given, then ANSIPLAY will append the
filetype of ".ANS" to the filename.
* Page 13 *
If no drive\path is given, then ANSIPLAY will search the
currently logged (default) drive\path for the ANSI file.
If the /L option is used (as describes below), only use a
[Drive:\Directory\] Path specification. Any filename.type
specified will be ignored.
[ DelaySeconds]
is the number of seconds to delay program execution. This
option is used for ANSIAUTO (automatic slide show present-
ation of ansi files). If this option is used, the number of
seconds must be preceeded with a space ( ).
While using ANSIAUTO, there will be a pause of DelaySeconds
between displays of ANSI files.
[Options] are as follows:
<Multiple option flags may be used in any order>
/C (ClearScreen) clears the screen before displaying the
ANSI file.
/H (Help) Displays a brief help screen for ANSIPLAY syntax.
/Q (Quiet) Disables the music and sound during display
of the ANSI file. /Q option does NOT disable a
DELAY parameter (Sound Code) if one exists.
/D (Delete) Prompts user if ANSI file is to be deleted after
display.
This option was designed for those who use off-line mail
readers. The mail read can save the message to a temp-
orary file, and then Shell out to DOS to ANSIPLAY it.
Then the /D option will allow you to delete the temporary
file.
After the file display has been completed, if you decide
not to delete the file, ANSIPLAY will ask if you want to
rename the file. At this time, if you answer "Y" (yes),
you will be asked for the new filename. (Note: the option
to Delete/Rename will be bypassed if the display is
interrupted by hitting the ESCape key).
When asked to Delete or Rename, hitting the [ENTER] key
will assume the default of "[N]o".
/L (List) will create a listing of all files with the
extension of ".ANS" that are located in the specified
drive\directory. If no drive\directory is specified,
then the current drive\directory will be used.
When using the /L option, do NOT enter any file
specifications such as *.*, *.ANS, but rather
specify the drive\directory only, for example:
* Page 14 *
ANSIPLAY C:\ANSI /L
-or-
ANSIPLAY C:\ANSI\ /L
A listing will then be alphabetized into a box which you can
use page up/down to view. To select the file you want to
ANSIPLAY, simply type in the number which is found to the
left of the file name and hit [ENTER].
After the file is displayed/played, the file selection screen
will return for your next selection.
The /L option will support up to 475 file names. If more
than 475 records are found, they will not be acknowledged
and the message "475+ records found" will be displayed.
The "+" notates the overage.
Options Flags /C /D and /Q may be toggled on/off by
hitting...
C - for ClearScreen toggle
D - for Delete toggle
Q - for Quiet toggle
You may also use the [F1] function key to change
drive\directory of the files you want to view.
(This option is only available in registered versions
of ANSIPLAY). If you change to a drive\directory is
invalid, the program will be terminated.
The Delete option will allow you to view the file before
asking if you want to delete it. If you answer No, you
will then be given a chance to rename the file.
Note: the /L option will not work with ANSIAUTO, but
rather, it will be ignored.
If you want the freedom to use the ANSIPLAY command while logged
onto ANY drive\directory, just add the name of the directory in
which ANSIPLAY exists to DOS's search PATH. (Consult your DOS
user's manual for more information on how to do this).
This can also be done by using the installation program
(INSTALL.EXE).
To exit ANSIPLAY at any time, press the [ESC] key.
REINITIALIZING THE DISPLAY SCREEN (ANSIPLAY.CLS)
------------------------------------------------
Once ANSIPLAY has completed displaying/playing the ANSI file,
there may have been several changes made to the screen display
such as screen mode, color attributes, etc.
To reinitialize the display to your desired settings, simply
create a file called ANSIPLAY.CLS containing the desired
ANSI escape command sequences. ("CLS" for "Closing Screen")
* Page 15 *
This can be done with the installation program (INSTALL.EXE) or
by using your own text editor.
This file is optional. If ANSIPLAY.CLS file does not exist,
then the only reset code which is automatically executed is
ESC[0m which turns all attributes off and returns to normal
display.
If the file ANSIPLAY.CLS does exist, the ESC[0m will be
ignored regardless of whether the file contains escape command
sequences or is empty.
An example of how this file might be used is to:
ESC[=3l 'reset the screen mode to 80 x 25 color
ESC[0m 'all attributes off, normal display
ESC[44;1;33m 'set colors: bright yellow on blue background
ESC[2J 'clear screen
thus the contents of ANSIPLAY.CLS would actually be:
ESC[=3lESC[0mESC[44;1;33mESC[2J
(ESC resembles the actual ESCape character which must be used).
Refer to the files ANSIPLAY.DOC and ANSICODE.TXT for more details
on the actual ANSI codes to use.
It is recommended that no other text, music codes, etc. are
included in this file, since they will be displayed after
each ANSI file display.
REMOVING MUSIC STRINGS (MUSCSTRP.EXE)
-------------------------------------
If wish to remove all existing music strings from the ANSI file,
at the DOS prompt type MUSCSTRP FILENAME.ANS
MUSCSTRP (Music Strip) will create a new file using the same
filename, but with the file extension of .NEW
The MUSCSTRP program must be able to locate ANSIPLAY.EXE either
in the current directory, or in DOS's PATH setting.
HOW ANSIAUTO WORKS
------------------
ANSIAUTO will read the contents of the data file you specify
on the command line.
(See "RUNNING ANSIAUTO" regarding DataFile Structure)
Once the data is loaded into memory, ANSIAUTO will shell to DOS
and execute the ANSIPLAY command (with any optional parameters
which are specified) per file.
Each file will be displayed (played) in sequence. If a
DelaySeconds parameter was specified, the program will pause
* Page 16 *
after the file is displayed for the set number of seconds, and
then continue onto the next file.
Once all the files have been displayed, ANSIAUTO will start
the sequence over again (and again...).
RUNNING ANSIAUTO
----------------
Syntax is as follows: ANSIAUTO DRIVE\PATH\FILENAME.DAT
If no filetype is given, then ANSIAUTO will append the
filetype of ".DAT" to the filename.
To EXIT ANSIAUTO, hit the ESCape key on the keyboard. ANSIPLAY
will not respond until the file display/play is completed. At
that time, the program will exit and return to DOS.
Data file structure
-------------------
Each line of the file contains the same specifications as would
normally be entered on the DOS command line when executing
ANSIPLAY. An example datafile might look like this:
C:\ANSI\MERMAID.ANS,3 /C
D:\DRAW\CASTLE.ANS,2 /C
C:\UTILS\FIREMAN.ANS /C /Q
. . .
. . .
etc. etc. etc.
As mentioned before, unregistered versions of the program will
display the "ANSIPLAY [Unregistered Version] Copyright 1991, J.
Ibarra" message after each file is display/played. Registered
versions do not have this message.
Maximum number of files that can be used for slideshow is 30.
If the data file contains more than 30 filenames, they will be
ignored. If 30 is not enough, let me know and I can increase it.
USING PLAY.EXE (Music String Player/Editor)
-------------------------------------------
Syntax is: PLAY [options] <* MUSIC CODES or SOUND CODES>
*The prefix of ESC[ and suffix of (music note) are not
required on the DOS command line.
Wherein [options] are:
<* MUSIC/SOUND CODES> - plays the <music/sound codes>
/E - for music string editor
/E <* MUSIC/SOUND CODES> - loads <music/sound codes> into the editor
/R - to repeat last-played music string
/R /E - loads last string played into editor
[options] may be in any order
* Page 17 *
If you want to experiment with music/sound codes, PLAY.EXE is
the quickest way to do it. PLAY.EXE has two ways of working...
1: It will allow you to play music codes directly from
the DOS prompt.
2: It will allow you to edit, then play, the re-edit, etc.
music strings, and write to file.
If MF or MB is not specified, default is set for MF.
See sections on "Using Music Codes" and "Using Sound Codes"
for more information on Music String Syntax.
--- TO PLAY THE MUSIC CODES DIRECTLY FROM THE DOS PROMPT ---
Playing a music/sound codes directly from the DOS prompt is
easy. An example would be, to hear the beginning of Frere Jacques
(ESC[MF O2 CDEC CDEC EFG.... EFG....(music note)), at the DOS
prompt, you would type the command line:
PLAY O2 CDEC CDEC EFG.... EFG....
or to hear a bomb dropping, you might type:
PLAY 900;1;120;;-5
Note that the > and < characters cannot be used from the DOS
prompt because DOS will interpret these as piping character.
Optionally you can set the octave with On wherein n is the
value (0-6) of the Octave you desire. Default octave is 4.
Before playing the music string, PLAY.EXE will check for any
letters that are NOT valid music code characters. If an
invalid letter is found, you will receive the error message
"Illegal play string".
Play will then take you directly into the music string editor.
If the string has a length greater than 73 characters, the string
will be trimmed to 73 characters so that it will fit into the
editor. If this happens, a message will appear to notify you.
/Repeat option (from the DOS prompt):
-------------------------------------
PLAY will automatically store the last music string played ,if
one exists, to a temporary file named PLAY.##.
If no music string exists upon exiting PLAY, the last music
string will NOT be overwritten with a blank music string. This
way if you decide you don't want to keep your edited changes,
you can simply hit [CTRL]-[Backspace] to erase them, then upon
exiting PLAY there will be no changes made to the PLAY.## file.
The /R option will allow you to repeat the music string by either
using it at the DOS prompt, or loading it into the music string
editor (see below).
To repeat the last string from the DOS prompt, type PLAY /R.
If the /R option is used, any included <music string> on the
DOS command line will be ignored.
* Page 18 *
--- TO USE THE MUSIC STRING EDITOR ---
The music string editor is the more useful feature of PLAY.EXE.
It will allow you to play Music Codes or Sound Codes, then
edit them on the screen, replay them, etc.
Once you have the music/sound codes exactly as you want them, you
can then save them to file.
The /E option will activate the editor. At the DOS prompt, you
may optionally enter the music string you wish to edit .
Music String Editor commands are as follows:
Move Cursor: LEFT/RIGHT arrow keys
Delete Character above cursor: DEL key
Move cursor to 1st character: HOME key
Move cursor to end character: END key
Erase entire music string: CTRL+Backspace
Write music string to file: CTRL+W
Toggle prefix of "MF" or "MB": TAB key
Exit PLAY.EXE: ESC key
If the music string contains characters which cannot be
played, you will receive an error message "Illegal play string".
It will then return to the editor so you can make your changes.
The write option will write the music string to a file named
"PLAY.MUS". (Note this is a different file from the PLAY.##
temporary file). The ESC[MF prefix and (music note) character
suffix will automatically be added.
If there are pre-existing music strings, the new music string
will be appended (not overwritten).
/Repeat option (with the Editor):
---------------------------------
The /R option will allow you to (Repeat) load the last-played
music string into the editor by typing PLAY /R /E at the DOS
prompt.
If the last-played music string is longer than 73 characters in
length, PLAY will trim the string to 73 characters so it will fit
into the editor. (If the last character is an "M", it too will
be trimmed to avoid sending the PLAY function into oblivion).
If the /R option is used, any included <music string> on the
DOS command line will be ignored.
REGISTRATION OF ANSIPLAY
------------------------
User's who register their copy of ANSIPLAY will receive a new
copy of the most current version of the program and included
utilities.
* Page 19 *
Advantages of registration are:
1. Registered versions will NOT interrupt the ANSI display with
the copyright message at the bottom of the screen.
2. The [F1] function used to change Drive\Directory will be
fully functional from the file listings menu.
3. Registered users will automatically be notified when an updated
version is released.
4. Registered users may purchase future updated versions for
only $5.00 each (plus postage and handling).
If you wish to register your copy, you may print the registration
form by typing COPY ORDER.FRM PRN at the DOS prompt.
Fill out the registration form and enclose required payment in
check or money order (no cash please) and mail to:
Julie M. Ibarra
P.O. Box 710727
Santee, CA 92072-0727
To print the registration form, at the DOS prompt, type:
COPY ORDER.FRM PRN
---------------------------------------------------------------
========== APPENDIX I - TROUBLE SHOOTING (INSTALLATION) ===========
Problem:
When I entered the letter of the boot drive, the program
said "Logging onto boot drive..." and never returned.
Reason:
INSTALL will try to access the drive you specified. If
the drive is invalid or unaccessible, the program will be
sent into infinity.
Solution:
Reboot, and try again...this time being sure the drive is
valid and accessible.
Problem:
When INSTALL went to access my CONFIG.SYS, AUTOEXEC.BAT or
ANSIPLAY.CLS files, it returned an error message.
Solution(s):
- Be sure that the CONFIG.SYS and AUTOEXEC.BAT files are on
the drive\directory you specified.
* Page 20 *
- Be sure the drive\directory you specified is valid and
accessible. Files that are read-only are not accessible
and will return an error message.
- Be sure the specified drive has enough disk space to write
the updated data onto.
Problem:
When I reboot, there was an error in CONFIG.SYS file.
Reason:
INSTALL.EXE seaches the CONFIG.SYS file for an exact match
of drive\directory\filename in which the ANSI device driver
exists. The device driver may have already been installed
under a different drive\directory than the one you specified.
Since the path's do not match, INSTALL.EXE assumes that the
driver is NOT installed therefore installing it twice. When
the system is re-boot, the driver is installed twice thus
causing the error.
Solution:
Use your text editor to remove the incorrect text line.
Problem:
When entering the drive\directory to locate a file, the
program sometimes will not accept my keyboard input.
Reason:
The program has a built-in feature which checks for proper
pathname syntax during user-interaction. For example, if
during a "\" character creates a situation where two "\\"
characters are found, the program will not accept the
improper format.
Solution:
Turn off INSert mode if necessary (by hitting the INS key),
and type it in properly. The automatic syntax checking will
be removed in the next updated version to help simplify user
input.
Problem:
When the PATH setting is changed, the new PATH is displayed
on screen. Before INSTALL.EXE changes the PATH setting, it
tries to find an existing PATH in the AUTOEXEC.BAT file.
This is done by searching for the FIRST occurence of the
text "PATH " (PATH followed by a space), or "PATH=" (PATH
followed by an equal sign.
If by fluke chance there is another line of text in the
AUTOEXEC.BAT file, INSTALL.EXE will think this was the line
to be changed and alter it.
Solution:
Use your own text editor to fix the line of text which should
not have been altered. Then, if you're unsure how to change
* Page 21 *
the actual PATH setting, just move the line of text which
contains the PATH setting to the beginning of the file, and
re-run install.
========== APPENDIX II - TROUBLE SHOOTING (MUSIC STRINGS) ===========
Problem:
I keep getting the error message "Illegal string in
PLAY parameters".
Solution:
Consult the documentation to be sure the values used
in your MUSIC CODE's and/or SOUND CODE's are valid. If
the problem still persists, and the parameters are indeed
valid, contact the programmer.
Another Solution:
It's possible that the letter O was used in place of the
number 0 (zero), or visa-versa in the MUSIC CODE's and/or
SOUND CODE's. It's very easy to mix these up.
Another Solution:
It's possible that the music note characters, [CHR$(14)] was
not included in the music string. Consequently, the program
will read the entire file until it encounters the music note.
If no music note is found, it will append a music note at the
end and try to play the string.
Problem:
Why do I get an "Illegal play string" error?
Reason:
Something in the play string is not valid. This could be
caused by using a note that does not exist such as
B#, H, etc.; or using a value which is not within set limits
for octave, tempo, etc. such as O7; or using an invalid
character which is not a music code/sound code character.
Problem:
My text editor will not allow me to enter the ESCape char-
acter (or music string character) into the ANSI file.
Solution:
Some editors (though few) do not have this ability. Refer
to the section "Using the ESC character during editing".
If this still doesn't help...if your editor has a cut-and-paste
feature, you might try duplicating the ESC character this way.
If all else fails, try another editor. There is a fantastic
Shareware text editor that is very intelligent called "QEDIT".
========== APPENDIX III - TROUBLE SHOOTING (ANSIPLAY) ===========
Problem:
Lots of strange characters (garbage) on the screen.
* Page 22 *
Solution:
Be sure that the ANSI.SYS driver is installed into your
CONFIG.SYS file (See section on "About ANSI.SYS").
Problem:
The program ignores my efforts to escape during the
displaying of my ANSI file.
Reason:
ANSIPLAY reads and processes large portions of the ANSI file
at a time. The output of these portions may be as large as
the whole display screen. Since the printing of these portions
cannot be interrupted, ANSIPLAY and ANSIAUTO will not respond
to using the ESCape key until the entire portion has been
processed.
Problem:
When I use "MB" (Music Background) in the music string, there
isn't much difference from "MF".
Reason:
There are several things happening here...For one, ANSIPLAY
must pull out the music strings from the bulk of the file
which is being read at one time. The strings must then be
processed to produce music/sound/pause's.
Secondly, the computer's music buffer will only retain 32
characters at a time. If the music string is larger than 32
characters or if the music buffer is full when the new
music string is to be loaded into it, the program has to wait
for the buffer to process the characters which have already been
loaded to free up more space in the buffer for the remaining
characters to be loaded.
Thirdly, Sound codes that have parameters for CYCLES and/or
DELAY are processed counting from 0 to CYCLES (or 0 to DELAY).
The counting procedure is not loaded into the background buffer.
When the frequency/duration is played, however, it is then
placed into the buffer. The counting feature is extremely
fast, but if the set values for these parameters are high, it
will slow up the display process slightly.
Problem:
My file was fine until I edited it...now I get a bunch of
garbage when displaying it.
Solution:
Some word processing programs will add extra printer codes to
the file when you "save" the file. Most programs that do this
also have an option to "save" as "ASCII" or "DOS TEXT". If so,
re-save the file using this option. This will save the contents
of the file without adding any other embedded program codes.
* Page 23 *
========== APPENDIX IV - TROUBLE SHOOTING (PLAY.EXE) ===========
Problem:
When I tried to write the music string to file, I keep
getting an error..."Unable to save".
Reason:
There may be one of several causes for this: Disk media
format error, not enough disk space or disk write-protected
to name a few.
================ APPENDIX V - REFERENCES ===============
Programs referenced in ANSIPLAY documentation:
AnsiPlay (ShareWare) - by Julie M. Ibarra
ANSI viewing utility with music support.
QEdit (ShareWare) - by SemWare
Text editing program.
Silly Little Mail Reader (Shareware) - by Greg Hewgill
Off-line mail reader program.
TheDraw (ShareWare) - by Keith Miller and Cat Miller
ANSI screen drawing utility with animation support.
============== APPENDIX VI - NOTES FROM THE AUTHOR ==============
I developed ANSIPLAY to allow users to not only be able to view
their ANSI files and play music (which some programs already do),
but to also allow support of Sound codes which is not available
in any other ANSI viewer.
The program is a result of many, many hours and 3 a.m. sessions.
Time allowing, I have de-bugged it as much as possible, though bear
in mind that I am only ONE person. Should you happen to run
accross one of those pesty little "bugs" (even a minor one), please
be sure to notify me so that it can be fixed in the next released
version of ANSIPLAY.
If you have a modem, there is not a "home base" BBS for ANSIPLAY
as of yet, but if you have access to a BBS that uses the PC-Relay
network, you will be able to leave me a message in the ANSI/GALLERY
conference.
Or you can call my hang-out...The FileBank BBS in Fallbrook, CA
(619) 728-4318.
And of course, you can send any correspondence directly to me at:
Julie M. Ibarra
P.O. Box 710727
Santee, CA 92072-0727
Any comments regarding program features, documentation, present-
ation, etc. are always appreciated.
--end of documentation--
Comments
Post a Comment