Sound Sensations!

home *** CD-ROM | disk | FTP | other *** search

/ Sound Sensations! / sound_sensations.iso / misc / ansip22b / manuals.doc < prev next >

Wrap

Text File | 1992-02-01 | 52KB | 1,236 lines

U S E R ' S M A N U A L S for ANSIPLAY, ANSIAUTO, MUSCSTRP and PLAY. (updated 02/01/92) INDEX: PAGE NO. ------------------------------------------- -------- License Agreement. . . . . . . . . . . . . . . . . 2 Disclaimer . . . . . . . . . . . . . . . . . . . . 3 Files included with the program. . . . . . . . . . 3 Printing the manual. . . . . . . . . . . . . . . . 4 USER'S MANUAL FOR ANSIPLAY . . . . . . . . . . . . 5 System Requirements for ANSIPLAY . . . . . . . . 5 Introduction . . . . . . . . . . . . . . . . . . 5 How ANSIPLAY works . . . . . . . . . . . . . . . 6 INSTALLATION of ANSIPLAY . . . . . . . . . . . . 7 INSTALLATION of your ANSI device driver. . . . . 7 Editing your ANSI file . . . . . . . . . . . . . 8 Using alternate characters in place of ESC . . . 8 Music string Tutorial (TUTOR.BAT). . . . . . . . 9 Using ESC/Music Note characters during editing . 9 Making the music strings invisible . . . . . . . 9 Getting familiar with ANSIPLAY . . . . . . . . . 10 ANSIPLAY command syntax (and options). . . . . . 11 File viewing with /L option. . . . . . . . . . . 11 Reinitializing the display screen (ANSIPLAY.CLS) 13 REMOVING MUSIC STRINGS WITH MUSCSTRP . . . . . . . 14 USER'S MANUAL FOR ANSIAUTO . . . . . . . . . . . . 15 System requirements for ANSIAUTO . . . . . . . . 15 How ANSIAUTO works . . . . . . . . . . . . . . . 15 ANSIAUTO command syntax (and options). . . . . . 16 ANSIAUTO data file structure . . . . . . . . . . 16 USER'S MANUAL FOR PLAY . . . . . . . . . . . . . . 17 System requirements for PLAY . . . . . . . . . . 17 PLAY command syntax (and options). . . . . . . . 17 PLAY's music string editor . . . . . . . . . . . 18 APPENDICES . . . . . . . . . . . . . . . . . . . . 20 Appendix I (Trouble shooting Music Strings). . . 20 Appendix II (Trouble shooting ANSIPLAY). . . . . 21 Appendix III (Trouble shooting PLAY) . . . . . . 22 Appendix IV (References) . . . . . . . . . . . . 22 Advantages of Registering ANSIPLAY . . . . . . . . 23 How to contact the author. . . . . . . . . . . . . 23 * Page 1 * LICENSE AGREEMENT -- Please read !!! ------------------------------- THIS CONDITION STATEMENT SUPERSEDES ALL PREVIOUS AGREEMENTS. If you are a registered user, this licence agreement does not apply to you. Different conditions and agreements pertain to the REGISTERED version of this program, and are included with all registration orders. This program package is NOT FREE. It is distributed under the ShareWare concept which means that you are hereby granted a limited 30 day license to use the program. If you intend to use the program after that time, you must register your copy by sending the required payment to the author (see the file ORDER.FRM for more information). In return for registering, you will receive a new copy of the most current REGISTERED which includes the following... 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. Additionally, your registration will contribute to the future development and quality enhancements of this program. All copyrights to this program and included files are reserved by the author, Julie M. Ibarra, and are protected by United States Copyright Laws. Neither the program nor any of the included files nor documentation may be altered in any way. REGISTERED versions of this program may NOT be distributed in any way. ShareWare versions of this program package 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 this program available for download only if the above conditions are met. Use of this program by non-registered users 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. If you are a ShareWare distributor and wish to include this program in your library, please fill out the file "VENDORS.DOC" and mail it at your earliest convenience. * Page 2 * DISCLAIMER ------------------------------- 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. FILES INCLUDED -------------- Files included with this program package are as follows: DISK ONE OF TWO: (Programs and ANSI files) [Compressed Filename: ANSIP22a.ZIP] ------------------------------------------ ANSIAUTO.DAT - Sample Data file used with ANSIAUTO.EXE. ANSIAUTO.EXE - Slide show automation utility program. ANSIPLAY.EXE - Program to read/display/play ANSI files. FAUCET .ANS - Demonstration ANSI file (using sound codes). GO .BAT - An Introduction to the entire program package. INTRO .ANS - ANSI Data file used with GO.BAT. MUSCSTRP.EXE - Removes music strings from your ANSI files. PLAY .EXE - On screen music string editor/player. SEA .ANS - Demo ANSI file (using music and sound codes). TUTOR .ANS - ANSI file used with TUTOR.BAT. TUTOR .BAT - A brief tutorial on some of ANSIPLAY's more advanced features. (Read this manual first.) XMASTREE.ANS - Demonstration ANSI file (using music codes). DISK TWO OF TWO: (Installation and Documentation) [Compressed Filename: ANSIP22b.ZIP] ------------------------------------------ ANSICODE.REF - Listing of ANSI control sequences available. BBS .TXT - Some pointers for BBS user's. INSTALL .DOC - Documentation for INSTALL.EXE. INSTALL .EXE - Executable installation program. MANUALS .DOC - This documentation (Manuals for ANSIPLAY, ANSIAUTO, MUSCSTRP and PLAY) MSTRINGS.DOC - Details on Music String Syntax. MUSICODE.REF - Listing of Music and Sound codes available to be used with ANSIPLAY.EXE. ORDER .FRM - Registration/Order form. OVERVIEW.DOC - A brief overview of this and other ShareWare products used with ANSIPLAY. QWKSETUP.DOC - Installation short-cuts for familiar DOS users. VENDORS .DOC - Documentation for ShareWare distributors. WHATSNEW.DOC - Notes of new features included with this version. * Page 3 * PRINTING THE MANUAL AND DOCUMENTATION ------------------------------------- All manuals and documentation may be printed from installation program by typing INSTALL at the DOS prompt. Or to do it manually from DOS, log onto the drive/directory in which the program files exists. Any text file may then be printed by typing at the DOS prompt... COPY FILENAME.TYP PRN wherein FILENAME.TYP is the name of the file you wish to print. Form-feeds are included at the end of each text file. * Page 4 * ANSIPLAY vs. 2.2 - Copyright 1991-1992, J. Ibarra ALL RIGHTS RESERVED U S E R ' S M A N U A L ANSIPLAY is an ANSI viewing utility with music and sound support. All you need to add music/sound to your ANSI files is your own text editor. SYSTEM REQUIREMENTS FOR ANSIPLAY: --------------------------------- DOS version: 3.2 or above CPU: 8088, 8086, 80286 or 80386 Video: Monochrome, CGA or above Disk: Single floppy or Hard disk Memory: 155k minimum free memory ANSI device driver: ANSI.SYS or compatible installed into CONFIG.SYS file of your root directory. ANSIPLAY may or may not run on other systems not listed above. 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. * Page 5 * 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 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. 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. * Page 6 * 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".) 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 OF ANSIPLAY ------------------------ If you are familiar with editing your CONFIG.SYS and AUTOEXEC.BAT files, all information necessary for installation if found in the file QWKSETUP.DOC. Otherwise, run the installation program included with this program package by typing the DOS command: INSTALL. The installation program automates the following procedures... 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). INSTALLING YOUR ANSI DEVICE DRIVER ---------------------------------- ANSI control sequences are simply sets of characters which are placed in a text file. The characters must be interpreted by an ANSI device driver. The device driver which is included with your DOS files is a file names ANSI.SYS. Unless this driver is installed into memory, the ANSI characters will not be interpreted, but rather they will display to the screen as a bunch of strange garbage. To install the device driver, there must be a line of text included in your CONFIG.SYS file which reads... DEVICE=C:\DOS\ANSI.SYS wherein C:\DOS would be the drive\directory in which the file ANSI.SYS would be located when your computer boots up. If you already have a CONFIG.SYS file created, you can edit it by using your own text editing program or the text editor provided * Page 7 * with DOS names EDLIN. Or you can create the file by logging onto the drive\directory where CONFIG.SYS is to be created and type the following from the DOS prompt... COPY CON CONFIG.SYS [enter] DEVICE=C:\DOS\ANSI.SYS [enter] ^Z [this is created by hitting the F6 function key] [enter] If all goes well, you should receive a message which states "1 file(s) copied." Once the ANSI device driver is installed into your CONFIG.SYS, it will be loaded automatically each time you boot up. For additional information regarding ANSI.SYS, CONFIG.SYS or the EDLIN text editor, please consult your DOS user's manual. 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. 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.REF (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. * Page 8 * 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. To first get familiar with Music Codes, Sound Codes, and Music String syntax, you should read the file MSTRINGS.DOC. Once you are familiar with them, continue with this documentation... 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. To insert a Music String into you ANSI file, just load your ANSI file into your text editor, type (or import) the music string where desired then save the file. Now ANSIPLAY it and...listen! 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) * Page 9 * 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. 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. 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. * Page 10 * 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. 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) or for those who use off-line mail readers. 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. (This option is automatically set to ON for monochrome monitors) /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. /S# (Slower) Slows down the display rate. Wherein # is a number 1-9. 9 is the slowest. If no # is used, the default is 1. /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- * Page 11 * 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: 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 (Color monitors only) /D - for Delete toggle /S - slows down the display rate (display rate will increase 1 each time "S" is hit. /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. * Page 12 * 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") 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 other parts of this manual and the file ANSICODE.REF 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. * Page 13 * 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. SYNTAX: MUSCSTRP [Filename] Wherein: [Filename] is the drive\path\filename of the ansi file you wish to strip. If no filetype is specified, the extension of .ANS will be appended. Output filename will be [Filename] with the extension of .NEW * Page 14 * ANSIAUTO vs. 2.2 - Copyright 1991-1992, J. Ibarra ALL RIGHTS RESERVED U S E R ' S M A N U A L ANSIAUTO is a utility program which integrates with ANSIPLAY version 2.2 to automate the display/playing of your ANSI files into a slide-show type of presentation. Files to be displayed may be arranged in your preference. There is also an option to insert a time-delay to pause between file displays. Additional options provided with ANSIPLAY are the ability to turn the sound off during display, and/or clear screen before display. SYSTEM REQUIREMENTS FOR ANSIAUTO: --------------------------------- Program File: ANSIPLAY.EXE (ANSI file viewing utility with music and sound support) DOS version: 3.2 or above CPU: 8088, 8086, 80286 or 80386 Video: Monochrome, CGA or above Disk: Single floppy or Hard disk Memory: ANSIAUTO requires 73k plus an additional 155k for ANSIPLAY equaling a total minimum requirement of 228k free memory ANSI device driver: ANSI.SYS or compatible installed into CONFIG.SYS file of your root directory. Other: You MUST have ANSIPLAY.EXE in the same directory as ANSIAUTO.EXE -or- in DOS's PATH environment setting. ANSIAUTO may or may not run on other systems not listed above. 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...). * Page 15 * 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 1992, 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. * Page 16 * PLAY.EXE vs. 2.2 - Copyright 1991-1992, J. Ibarra ALL RIGHTS RESERVED U S E R ' S M A N U A L PLAY.EXE is a utility which allows you to create strings of music 73 characters at a time, edit them, play them, and eventually save them to file. This utility was designed to be used with the ANSIPLAY ShareWare program, but can have several uses ranging from BASIC programmers who want to experiment with the PLAY statement to ANSIPLAY users who want to experiment with Music codes and Sound codes that can later be inserted into their ANSI files. PLAY.EXE can play Music/Sound codes directly from the DOS prompt, or from the on-screen Editor which will allow you to edit, then play, the re-edit, etc. music strings, and if so desired, write them to file. When the string is written to a file (saved), it is saved in a format which is compatible with ANSIPLAY which includes the Foreground/Background music specifier and the CHR$(14) suffix. SYSTEM REQUIREMENTS FOR PLAY.EXE: --------------------------------- DOS version: 3.2 or above CPU: 8088, 8086, 80286 or 80386 Video: Monochrome, CGA or above Disk: Single floppy or Hard disk Memory: 131k minimum free memory PLAY may or may not run on other systems not listed above. 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 For more information on Music String Syntax, please read the file MSTRINGS.DOC. If MF or MB is not specified, default is set for MF. * Page 17 * --- 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. --- 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 . * Page 18 * 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. * Page 19 * ========== APPENDIX I - TROUBLE SHOOTING (MUSIC STRINGS) =========== Problem: I keep getting the error message "Illegal string in PLAY parameters". Solution: Consult the documentation (MUSICODE.REF) 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. 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. * Page 20 * ========== APPENDIX II - TROUBLE SHOOTING (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 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 21 * ========== APPENDIX III - 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 IV - REFERENCES =============== Programs referenced in this documentation: AnsiAuto (Included) - by Julie M. Ibarra Slide-show automation utility for AnsiPlay vs 2.2. * AnsiPlay (Included) - by Julie M. Ibarra ANSI viewing utility with music support. Install (Included) - by Julie M. Ibarra Automated installation procedures for AnsiPlay vs 2.2. Play (Included) - by Julie M. Ibarra Music string editing utility (supports music and sound codes). 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. * Page 22 * ADVANTAGES OF REGISTERING ANSIPLAY ---------------------------------- 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. Additionally, your registration will contribute to the future development and quality enhancements of this program. HOW TO CONTACT THE AUTHOR ------------------------- 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 "J)oin" the "GALLERY" conference. And of course, you can mail 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-- * Page 23 *