home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Mega CD-ROM 1
/
megacd_rom_1.zip
/
megacd_rom_1
/
MUSIC
/
ANSIPL20.ZIP
/
ANSIPLAY.DOC
< prev
next >
Wrap
Text File
|
1991-06-14
|
47KB
|
1,160 lines
ANSIPLAY vs. 2.0 - Copyright 1991, J. Ibarra
ALL RIGHTS RESERVED
U S E R ' S M A N U A L
INDEX: PAGE NO.
------------------------------------------- --------
Copyright Notice and Regulations . . . . . . . . 2
Introduction . . . . . . . . . . . . . . . . . . 2
Files included with the program. . . . . . . . . 4
Printing the manual. . . . . . . . . . . . . . . 4
How ANSIPLAY works . . . . . . . . . . . . . . . 5
About ANSI.SYS (and installation). . . . . . . . 5
Editing your ANSI file . . . . . . . . . . . . . 6
Music string syntax. . . . . . . . . . . . . . . 6
Music string contents. . . . . . . . . . . . . . 7
Music codes / Sound codes definition . . . . . . 7
Using Music Codes. . . . . . . . . . . . . . . . 8
Using Sound Codes. . . . . . . . . . . . . . . . 8
Music string Tutorial (TUTOR.BAT). . . . . . . . 10
Making the music strings invisible . . . . . . . 10
Using ESC/Music Note characters during editing . 11
Getting familiar with ANSIPLAY . . . . . . . . . 12
ANSIPLAY command syntax (and options). . . . . . 12
Reinitializing the display screen (ANSIPLAY.CLS) 13
Removing music strings (MUSCSTRP.EXE). . . . . . 13
How ANSIAUTO works (slide-show). . . . . . . . . 14
Running ANSIAUTO . . . . . . . . . . . . . . . . 12
Using PLAY.EXE (music string player/editor). . . 15
Common problems. . . . . . . . . . . . . . . . . 16
Registering ANSIPLAY . . . . . . . . . . . . . . 18
-1-
First of all, let me get this over with...
COPYRIGHT NOTICE
----------------
All rights to ANSIPLAY and included files are reserved by the
author, Julie M. Ibarra, and are protected by United States
Copyright Laws. Violators 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 ANSIAUTO 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.
Any alterations to the program files or documentation may only be
made for the user's own personal usage of the program, provided
that you notify the author in writing of said alterations.
The program and documentation may NOT be distributed in altered
form. REGISTERED VERSIONS OR BACKUP COPIES THEREOF MAY NOT BE
DISTRIBUTED, COPIED, OR SHARED IN ANY WAY, OTHER THAN FOR
PERSONAL BACKUPS. You may not network the program, or otherwise
use it on more than one computer. If the program is to be used
on more than one computer a separate registration is required per
computer.
Otherwise, 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).
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.
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.
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.
-2-
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 Public Domain'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.
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 Public Domain 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
-3-
(such as "The Draw") with the music strings in it. The reason
being that the editor will try to interprete 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 interprete ALL characters as text
so there's no problem there.
FILES INCLUDED
--------------
Files included with this package are as follows:
---Program Files---
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.)
---Documentation---
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 codes available to be used
with ANSIPLAY.EXE. (Also see the section on
Sound Codes).
ORDER .FRM - Registration Form to purchase your registered
and most current version of ANSIPLAY.
---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
-------------------
If you wish to print the manual, log onto the same
drive/directory in which this file (ANSIPLAY.DOC) exists, and
type COPY ANSIPLAY.DOC PRN at the DOS prompt.
-4-
All other documentation files/order form may be printed the same
way by using different filenames.
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".)
Public Domain 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.
ABOUT ANSI.SYS (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.SYS device driver is included in your own DOS files.
If you're wondering weather or not your system has ANSI.SYS
already installed, 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, ANSI.SYS is NOT installed.
HOW TO INSTALL ANSI.SYS
-----------------------
DOS's ANSI.SYS device driver only needs to be installed once.
This is done by creating (or editing an existing file) a file
called CONFIG.SYS which must be in the root directory of the disk
from which your computer boots from.
If you want to create a new CONFIG.SYS file, use the following
commands, BEWARE however that if the CONFIG.SYS file already
exists and you use the following commands, the existing file will
be overwritten...
1. At the DOS Prompt type COPY CON C:\CONFIG.SYS (wherein
C: should be changed to the name of your bootable disk
drive)
-5-
2. You will not get a new DOS prompt after this command.
Now type DEVICE=C:\DOS\ANSI.SYS (followed by [ENTER]),
(wherein C:\DOS should be changed to the name of the disk
drive\directory in which the file ANSI.SYS exists.)
3. To exit the COPY CON command, type [CTRL]+[Z] and
[ENTER]. You should now be returned to the DOS prompt.
ANSI.SYS will now be installed automatically each time
your computer is booted.
4. To reboot, you can type [CTRL]+[ALT]+[DEL]. Hold down
the [CTRL] key, then hold down the [ALT] key, then hit
the [DEL] key and let go.
If you have an existing CONFIG.SYS file that must be edited, you
can use a word/text editor, or consult your DOS user's manual on
how to use DOS's text editor EDLIN.EXE.
EDITING YOUR ANSI FILE
----------------------
If you are starting from scratch, you may want to look into an
ANSI screen editor such as the Public Domain program "TheDraw".
Without such a program, ANSI file creation can be tackled, but it
would be extremely tedious and time-consuming at best.
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.
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)
-6-
MUSIC STRING CONTENTS
---------------------
The word "string" simply means a set of characters (including
spaces and ascii characters) strung together.
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")
-7-
-------------------------------
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. The music string would
look like this:
ESC[MF <FREQ; DURA; CYCLES; DELAY; VARI> (music note)
Example: ESC[MF 100;5;5;10;-5 (music note)
-8-
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.
Any non-integer numbers used for CYCLES or DELAY will be
converted to integers automatically.
-9-
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.
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.
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 ? is the current row. 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
-10-
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.
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 Public Domain
program called QEDIT. It's very powerful and does allow extended
ASCII characters.
-11-
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 [FileName DelaySeconds] [/Option Flags]
Parameters are:
[Filename]
is the drive\path\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.
If no drive\path is given, then ANSIPLAY will search the
currently logged (default) drive\path for the ANSI file.
[ 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.
/Q (Quiet) Disables the music during display of the ANSI
file.
/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.
If you want the freedom to use the ANSIPLAY command while logged
onto any drive\directory, just add the name of the directory in
-12-
which ANSIPLAY exists to DOS's search PATH. (Consult your DOS
user's manual for more information on how to do this).
Once the file is in process of displaying, hitting ESC will NOT
allow you to exit the display until to display is completely
processed. The purpose of this is two-fold. First, to allow a
bulk read/write of the file thus making the fastest display
possible. Second, to avoid stopping the display when the screen
may be set in the middle of some strange color combination.
(However, ANSIAUTO will exit after the display/play is completed.
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")
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
-13-
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
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.
-14-
USING PLAY.EXE (Music String Player/Editor)
-------------------------------------------
Syntax is: PLAY <* MUSIC STRING> (Plays Music Codes or Sound Codes)
or: PLAY /E <* MUSIC STRING> (To activate music string editor)
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.
* MUSIC STRING is a little different with PLAY.EXE:
The prefix of ESC[ and suffix of (music note) are not
required on the DOS command line.
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 interprete 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.
--- 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.
-15-
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". 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).
COMMON PROBLEMS WITH 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
-16-
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. Public Domain has
a fantastic and very intelligent text editor called "QEDIT".
COMMON PROBLEMS WITH USING ANSIPLAY
-----------------------------------
Problem:
Lots of strange characters (garbage) on the screen.
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 will not respond to using the
ESCape key.
ANSIAUTO, however, will respond AFTER the file display is
completed.
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
-17-
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.
COMMON PROBLEMS WITH USING 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.
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. In addition, registered versions will NOT interrupt
the ANSI display with the copyright message at the bottom of the
screen.
Registered users will automatically be notified when an updated
version is released. Registered users will receive a 25%
discount on the purchase of any updated version (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:
-18-
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
Any comments regarding program features, documentation,
presentation, etc. are also appreciated.
Any questions, comments, correspondence may also be directed to
the above address.
--end of documentation--