HYMN HUNTER DOCUMENTATION TEXT FILE HOW TO USE THE HYMN HUNTER (You may want to print out this file for ready reference.) I. Preliminaries A. Here is a statement of the program objectives: 1. It allows you to display records of hymns in the 1982 Episcopal Hymnal. A record consists of: a. an excerpt of the first line b. the composer c. the title d. the hymn number e. a schematic of the first sixteen notes of the hymn tune f. the first sixteen notes of the hymn tune audibly played through the speaker of the computer. 2. It allows you to find records rapidly through automated searches by: a. first line b. composer c. title d. hymn number e. hymn tune. This capability was a major impetus for the program, since audible cues could be employed, thus allowing non-musicians to find hymns by whatever tune happened to pass through their minds. B. Requirements. You will need an IBM PC or compatible computer (IBM is a trademark of International Business Machines, Inc.) with a monochrome screen for best results. I've found only one computer so far (an Eagle compatible) where the ESCAPE key failed to abort a search-in-progress. C. Use of " " (quotes) in this document. Quotes are used only to clarify text, and are not to be taken literally. For example, if I tell you to enter a "Q", do not type QUOTE-Q-QUOTE, just type a Q . If you must take everything literally, ignore the quotes. D. Use of { } (braces) in this document and in the program. Braces are meant for asides to clarify points to those who have some musical knowledge. If these asides make no sense to you, they may be safely ignored. {What did Beethoven say to his wife when he went out for groceries? "I'll be Bach in a Minuet!"} E. RETURN, ESC, CTRL, and P 1. When I refer to the RETURN key, this is the (usually backward-L-shaped) key located where the carriage return key would be on a standard typewriter keyboard. On most computers, it has a bent arrow on it; on some the word "RETURN" or "Return" is marked on it, and on others, the word "ENTER" or "Enter" is marked on it. Some keyboards have both a RETURN key and a separate ENTER key which can be used interchangeably. When I mention RETURN, I usually mean you should strike the RETURN key. 2. When I refer to the ESC or Esc key, this is known as the ESCAPE key, and is a small key marked with the letters "ESC" or "Esc" which is generally located either on the top row of the keyboard to the left of the number keys, or on the upper-left-hand corner of the numeric keypad. The ESC key is used to get out of jams in the program. 3. CTRL refers to the Control key, which is the key marked with the letters "CTRL" or "Ctrl". I have reserved the use of this key in the program to give you the convenience of word processing functions which you will see on screen from time to time. Admittedly, these functions were far more useful to me as I was entering and editing the hymns than they ever will be to you as you search (in fact, you may never have cause to use them), but I left them in anyway. When you see something like "CTRL-V", for instance, it means hold down the Control key with your left little finger, and while you do this, type the letter "v". (In entering text, this would allow you to insert text between already typed text.) 4. P refers to (surprise!) the letter "p". This key is always used to play or replay a tune through the speaker when this option appears on the screen. If you choose to search by tune, I strongly recommend you check your search tune audibly by entering "p" before searching. F. A word about maximum search times. (If you don't understand some of the terms in this section, don't worry, they're not important.) You can expect to wait for the maximum search time if you are looking for a hymn which is not in the 1982 Hymnal. I have good news and bad news. First the bad: 1. This program does not use any fancy hash tables, B-trees, sorted indexes, etc., etc. It simply slogs through the entire hymnal looking for a match on the key you provide. This means you can expect the following approximate search times for most types of searches (I've discovered these timings can vary quite a bit depending on the degree of file fragmentation): a. If you are using a floppy drive, expect to wait a maximum of about fifty-five seconds. b. If you have a hard drive, wait a maximum of twenty seconds. c. If you use a RAM (or Virtual) drive, wait a maximum of ten seconds. If you use a "turbo"-speed PC, wait only five seconds. As you can see from the above, it pays to run this program from a RAM drive if you can spare the memory and you know how to set one up. If you have a DOS of version 3 or higher, there is a utility called VDISK.SYS which lets you do this. You will need about 160 kilobytes of free RAM in addition to the 128 kb needed to run the program. Now for the good news: 2. By far the most common type of search that I would anticipate is by hymn number. Fortunately, the hymn file just happens to be in hymn number order! This means the computer can go right to the hymn you specify while passing by all the rest, just as you would if you looked it up in the hymnal. What this means is a maximum search time of about two seconds regardless of the type of drive you use. G. Make backup copies of all the files on your distribution diskette! Both the program and the database files are covered by copyright (mine covers the program; others cover the database), which means you may not distribute them yourself, but as a very wise precaution, you should make at least one backup copy of the distribution diskette just in case something should go wrong. This protects your investment in the program. There are three files you should be concerned with: 1. HM.COM This is the program file you will be running. 2. HYMN.DBF This is the database file of all the hymns. The program will not run without both HM.COM and HYMN.DBF residing in the same directory (usually, floppy diskettes and RAM drives have only one directory, so as long as both are on the same floppy or RAM drive, there should be no problem). 3. HYMN.TXT This is the documentation text file that gives instructions on how to use the program which you are hopefully reading now. You may use the DOS COPY command to copy all these files to other discs. For example, if your distribution diskette is in the A drive and you want to copy all the files to the hard disc on drive C, you would get to the DOS "A>" prompt and type copy *.* c: after which you would RETURN. II. Getting Started. Depending which drive you intend to run the program from, you should get to the prompt which indicates that drive. For simplicity, I'll assume you're running it from the A drive, so if you don't see the "A>" prompt or something similar, enter "A:" and RETURN to get to it. When you are sure the program and database files are available in that drive (by insuring a copy of the distribution diskette is inserted into it), enter "hm" and RETURN. This should bring up the program insignia which has at the top of the screen the name of the program: HYMN HUNTER ( The 1982 Episcopal Hymnal on disc. ) along with the copyright information: (c) Copyright 1988 by Spencer Hunter and at the bottom of the screen should be this message: Strike any key to begin... which means you should find a key and strike it! Usually, when someone tells me to strike any key, I select the space bar because it's so easy to find. If you do this, you should see the Main Menu: HYMN HUNTER Menus respond to lower-case commands. MAIN MENU Enter choice from below: Esc ) Escape and leave program. 1 ) Find hymn by number. 2 ) Find hymn by tune. 3 ) Find hymn by first line. 4 ) Find hymn by composer. 5 ) Find hymn by title. A computer menu like this one is somewhat like a menu at a restaurant; only instead of giving you a choice of different foods to eat, it gives you a choice of different actions to take. The remainder of this document will guide you through the various choices on this menu, but first note the phrase "Menus respond to lower-case commands". This tells you that if you are entering capital letters or have the CAPS LOCK key set, you probably won't get very far. III. How to get out. Whenever I get into an unfamiliar program, the first thing I want to know is how to get back out of it. I mentioned earlier that the Esc (ESCAPE) key would get you out of most jams, and certainly, being stuck in the Main Menu could be considered a jam. If you want to escape the program, strike the Esc key! (You could also read the menu to see that this is one of your options.) ESCAPE will only leave the program when it is entered from the Main Menu; in other cases, it simply returns you to the Main Menu. IV. How to find a hymn by the hymn number. On the Main Menu, the second choice listed is finding a hymn by its number. The character listed to the left of this choice is "1". Therefore, enter a "1" to find a hymn by number. This will clear the screen and give you a prompt: Enter hymn number, then RETURN. Below this prompt you will see which hymn the program is currently pointing at. When you first go into the program, the current hymn pointed to will be hymn number 1. If that's the hymn you want to look at, just RETURN; otherwise, type the hymn number you want before striking RETURN (If you want to abort and return to the Main Menu at this point, you could hit ESC). This should bring up the record of the hymn you requested, along with the following sub-menu: Enter choice from below: Esc) EXIT p) Play again. f) Forwards browse. b) Backwards browse. You should respond to this menu just as you would the Main Menu--by reading the choices and entering the appropriate single-keystroke response. Here is a more detailed description of each choice: A. Esc. To exit back out to the Main Menu, strike the ESCAPE (Esc) key. Remember, ESCAPE only leaves the program from the Main Menu. B. p. To replay the hymn, strike the "p" key. You may replay the first sixteen notes as often as you wish. C. f. To go one hymn forward in the hymnal, strike the "f" key. Thus, if you were just looking at hymn 597 and you struck the "f" key, you would then be looking at hymn 598. D. b. To move back one hymn from where you are, strike the "b" key. If you were just at hymn 598, for instance, and you struck the "b" key, you would then be at hymn 597. Keep in mind that there are only 720 hymns in the hymnal, none of which have negative numbers. Hence, you cannot browse backwards from hymn 1 nor forwards from hymn 720. V. How to find a hymn by the hymn tune. Finding a hymn by its tune is the most advanced feature of this program. {This is because you may enter the tune in any key, with all notes being the same duration (they're all eighth notes), in any octave, and even with erroneous rests, and the program will still be able to find a match on your tune!} At first try, it may also seem the most daunting feature, but with a little practice, it really is quite easy. From the Main Menu, you will want to enter a "2", which represents the choice "Find hymn by tune.". This will bring up a rather involved screen which I will describe step-by-step, from top to bottom. A. At the top of the screen is the heading: CONSTRUCT A SEARCH TUNE OF FROM 2 TO 16 NOTES. This is not a terribly helpful statement, since we don't as yet know how to construct such a tune. However, it does bring up a couple of important points you should know at this time: 1. A search tune which has less than two notes in it will only pull up every hymn in the hymnal! Obviously, this is not such a useful way to search for something, so it makes good sense to have at least two notes in the tune you will be entering. 2. Although you can enter up to 16 notes into your tune, it's wise not to do so, because some of the hymns are not specific to all sixteen notes. Why is this? It happens that many hymns have gaps known as "rests" or "pauses" in them. While these rests or pauses are irrelevant to the tune search, they do take up the space a note would occupy. This means that a hymn that has three rests somewhere in the first sixteen places is really only specific to 13 notes, and if you tried to search by all 16 notes with no rests, your search tune would be too specific and the program would fail to find the hymn you know is in there somewhere! Also, entering all sixteen notes increases the risk of entering a note which was remembered incorrectly, causing the search to fail. Generally speaking, five to ten notes are sufficient to pin down the hymn you want to find. B. The next line prompts you to audibly select your note from the keyboard: Test-strike the following keys to select notes BY EAR: Q W E R T Y U {low major scale} A S D F G H J {middle} Z X C V B N M {high} Notice that all these keys lie more or less on the left side of the keyboard. If you are new to the program, strike the keys "Q" through "U" on the top row of keys, then strike keys "A" through "J" on the middle row, and finally, strike "Z" through "M" on the bottom row. Note that each row of keys plays the same notes, only at a higher-sounding pitch {that is, the C major scale you hear will be an octave higher} on each successive row. Don't be afraid to play with these keys as much as you want! Try to become accustomed to how they all sound. C. You will find there are many notes that you can't get {in the Western 12-note chromatic scale} just by striking these keys alone. The next statement explains how to play these additional notes: If the note you want is between two keys, SHIFT and enter the lower key as a CAPITAL letter. {SHIFT raises the pitch by one semitone.} Let's say the note you want to play is between the "F" and the "G" keys. {"F" and "G" in this instance actually play the notes F and G. But what if you wanted an F-sharp/G-flat?} The way to do this is to press the SHIFT key, and at the same time, strike the lower key, which in this case is the "F" key. In other words, enter a capital "F", not a lower-case "f", to play the note in between the "F" and "G" keys. {Using the SHIFT key always sharps the pitch you will hear, even in those cases where striking two successive keys play pitches already one half step apart. For example, the keys "D" and "F" play notes which are already one half step apart (notes E and F in this case). If you enter SHIFT-"D", (an upper-case "D"), you will hear the same note you would've heard had you simply struck the "F" key (a lower- case "f"). Capital "D" and lower-case "f" play the same note.} D. You've now learned how to play notes on the keyboard, even those notes that "fall in the cracks". So now how do you enter them into your search tune? The next statement explains: When you find the note you want, RETURN to advance to the next note. Just as RETURN advances you to the next line on a typewriter, the RETURN key advances you to the next note of your search tune. The usual sequence for entering a tune, then, is to find the note you want by trial and error, and when it is found, RETURN to advance to the next note (which will also be found by trial and error). If you try to RETURN past the end of the tune, or if you try to enter more than the maximum of sixteen notes, you will receive an "end of tune" message. E. Other options exist for those times when you make mistakes or when you wish to review how your search tune sounds so far. These are outlined next: Other options: Space bar) Backup 1 note. p) Play entire tune so far. o) Omit note with rest. Esc) Abort tune search. Here is what they basically are: 1. Strike the space bar if you wish to back up and fix a wrong note. If the note you want to correct is the one you've just entered (and you've already RETURNed to the next one), you only need to hit the space bar once to back up to it. You will see the current note pointer on the screen actually back up to the note you want to correct. You may back up as many notes as you wish, but you will get a "beginning of tune" message at the beginning of the tune, naturally. When you've finished correcting the note (by playing the one you really wanted from the keyboard), simply RETURN as many times as it takes to get back to the end of the tune. You will see the note pointer advance down the screen as you do this. Space bar and RETURN move the note pointer in opposite directions. 2. Once again, we encounter the ubiquitous "p"! By entering "p", you can review how your search tune sounds, which, as I mentioned earlier, is highly recommended; if you're using a floppy drive, a failed search due to an incorrect search tune can cost you nearly a minute of your precious time. You will notice that the tune may not sound exactly like the tune you want to find, because it is always made up of equal-duration {eighth} notes, so the important thing to listen for is to make sure that at least all of the PITCHES are correct relative to each other. This is much easier to do with a short tune than a long tune, which again stresses my point of using search tunes of less than all sixteen notes. "p" will replay your search tune. 3. "o", the lower-case "O", is frankly an option you will rarely have need for. But supposing after you had entered your tune, you noticed when you audibly checked it (with "p", remember?) that there was an extra note near the beginning you did not intend to put in. Does this mean you must start over? No. You can back up to the offending note by striking the space bar the requisite number of times, and actually obliterate it with choice "o". Now when you replay your search tune, you will notice a gap {rest} in the tune where the wrong note once was. This gap is ignored during the tune search. "o" is also useful for shortening a long search tune, which has the effect of broadening the tune search criteria. Simply omit the last few notes with "o" to do this. 4. It goes without saying that "Esc", or the ESCAPE key, will abort the tune search and send you back to the Main Menu, but I mentioned it here anyway. F. We've now covered how to play notes on the keyboard, how to use SHIFT-key combinations to get additional notes, how to RETURN to enter a note into the search tune, and we've covered extra options like using the space bar to back up and fix mistakes, "p" to review what the search tune sounds like, "o" to omit wrong notes, and ESCAPE in the case where the tune-searching function was chosen by mistake (or, perhaps, just for practice) to begin with and needs to be aborted. But how do we commence a search on our tune? The final statement on the tune-search screen explains how: F1 (function key) will begin a search on your tune. The ten function keys on a PC are either arranged horizontally above the keyboard or vertically to the left of the keyboard. Striking ANY of these keys will begin the tune search. For the horizontal arrangement, the function key marked "F1" is probably the easiest to reach, and that's the one recommended on the screen. However, I find F10 is the easiest to reach with the vertical arrangement. The program will now go through each hymn in the file looking for a match on your tune. See the section on "Searching" to find out what happens next. It might prove useful to go through an example. Let's look up "Joy to the World" by tune. From the Main Menu, the key-sequence is as follows: 2 this selects the tune-search option from the Main Menu. z RETURN j RETURN Enter each note into the search tune by h RETURN RETURNing after playing each note. g RETURN f RETURN d RETURN s RETURN a p We audibly check the tune for relative pitch. At this point, all we hear is a downward major scale, but that's exactly how "Joy to the World" starts, only with different note- durations. F1 Any one of the function keys begins the search on our tune. VI. How to find a hymn by first line, or by composer, or by title. Since searching for a hymn by first line (choice "3" on the Main Menu) or by composer (choice "4") or by title (choice "5") are exactly similar, all three options will be discussed in this section. If you wanted to search by first line, you should enter "3" when you are at the Main Menu. You will then be prompted to enter a 48- character line of text: Enter first line of hymn, then RETURN: For the same reasons why you ought not specify all 16 notes of a search tune, it is highly recommended that you do NOT specify all 48 characters of search text. Searching on a line of text is forgiving in that leading blanks and punctuation are ignored, as well as whether you use lower-case or capital letters. However, if you should miss some punctuation in the middle of the text (say, a period instead of an exclamation point), or add an extra space (how are you supposed to know my convention of putting only one space between sentences unless I tell you?), your text search will fail, and on floppy drives, once again, that means wasting about a minute of your time. Keeping your text strings short is one reason I will not explain the word- processing functions (which use CONTROL-key combinations and will probably be useful only to a small minority of users--they are mainly hold-overs from the hymn-entry phase of the program) except for the backspace key, which causes one character to the left to be deleted. A length of from 5 to 10 characters should be enough for a successful search. For instance, at the above prompt, if you were to type in "god is work" (without the quotes) and RETURNed, the program would find the hymn which has the first line "God is working his purpose out...". If you were to select a text search by title (choice "5" from the Main Menu), you would get an almost identical prompt: Enter title, then RETURN: At this point, if you typed in "gener" and RETURNed, the program would find the hymn with the title "General Seminary". Finding a hymn by composer works the same way. You would select choice "4" from the Main Menu, and would get the prompt: Enter Composer name, then RETURN: My convention is to name a composer only if the hymnal mentions him/her by name; otherwise, the arranger or adapter is mentioned, and failing that, then the source is mentioned. If, in the above instance, you were to type "vaugh" and RETURNed, the program would find the hymns written, and in many cases arranged, by Ralph Vaughan Williams. After each text entry, the program sequentially searches through the entire hymnal looking for a match. This is covered in the next section, "Searching". VII. Searching. Choices "2" through "5" from the Main Menu cause the program to scan the hymn file in sequence looking for a match. You will see the following message on the screen after you've entered your tune or text: Searching... (Esc to quit search) If you are growing impatient because of the time the search is taking, you can always abort by striking the ESCAPE key. Otherwise, the search will either succeed or fail. If a match is found, you will see a record come up on the screen (and hear the tune), along with the following sub-menu: Enter choice from below: Space bar) continue search p) play again Esc) Quit search Again, this menu is self-describing, but I will elaborate: A. Space bar. Striking the space bar (or just about any other key besides ESCAPE or "p") will leave the hymn you are looking at and will continue a further search through the hymnal seeking any more matches. If no more are found, the Main Menu will reappear; otherwise, the next match will appear with the same sub-menu (and the same three choices) shown above. B. p. Here's that ubiquitous "p" again! And striking it does the same thing: it replays the sixteen notes you just heard. You may replay these as often as you wish by re-striking the "p" key. C. Esc. The ESCAPE key also works the same as it has: any further searching is aborted and the Main Menu reappears. If the search fails and a match is not found at all, the Main Menu will reappear after the maximum search time. Now you know all you need to know about finding hymns with the Hymn Hunter. Remember, if you don't find the hymn you're looking for, try shorter and broader search criteria. For instance, if you don't find the hymn using a six-note search, try searching with only four notes (you may have remembered one of the notes incorrectly). Or perhaps you forgot that the first note repeats; try, try again! It's very easy when searching by text to put in or leave out some unforseen punctuation, so try searching on a shorter string of text where you won't have to be quite so concerned about the precise punctuation. Finally, if you happen to be an old-time Episcopalian, you may recall a good many haunting melodies and hymn-texts which just cannot be found, even with this program. Well, that's because they were in the "old" 1948 hymnal and weren't carried over to the 1982 version. However, there are just as many fine new hymns added which you may be as yet unfamiliar with. Happy Hymn Hunting! VIII. Hymn Hunter Trivia. This section contains non-vital information insofar as operating the program, but may be of interest to the user. A. Musical Notation. Since I did not use graphics to notate music, I came up with a system of my own. On a small microcomputer speaker, just about the only qualities of a note which one can control are duration and pitch. These two qualities are what I tried to describe. When you see a note represented on the screen, you will see two numbers and the name of the note. The first number represents its duration, the second represents which octave it falls into, and the note-name will sometimes include its enharmonic name as well. I will analyze the following example: 8 3 E#/F 1. Duration. To describe how long a note should be held, I imagined a "generic" whole note divided up into sixteenth notes. The actual durations of these notes would later be determined (in a rough and subjective kind of way; I made no attempt to follow precise metronome markings) when I selected a tempo for the hymn. The first number represents the number of these sixteenth notes that the note is equal to. If the number is 1, the note is equivalent to a sixteenth note. If it is 16, the note is a whole note. In the above example, the note described is a half note, which is equivalent to eight sixteenth notes, hence the number 8 is displayed. The most common duration is the quarter note, displayed as a 4, represented by four sixteenth notes. 2. Pitch. The second number listed ("3" in the above example), known as the octave number, and the note-name ("E#/F" above) indicate what pitch the note will sound at. a. The octave number. This number is necessary for specifying which octave a given note falls into. In devising these numbers, I divided the great staff (which includes both treble and bass staves) into five possible octaves, numbered 1-5; 1 is the lowest octave starting on the great C below the bass clef, and 5 is the highest, ending on the B an octave above the C just above the treble clef. In more conventional notation, this might be listed as follows: 5= c'''-b''' (above the treble clef) 4= c''-b'' (treble clef and above) 3= c'-b' (middle C to the treble clef) 2= c-b (bass clef to B just below middle C) 1= C-B (bass clef and below) Most of the notes in the hymnal seem to fall within the lower half of the treble clef, or octave number 3, as in the example above. None fell into octaves 1 nor 5. b. Note-names. These describe the twelve pitch classes or octave divisions common to most Western music, and certainly to the 1982 Hymnal! Because most terminals cannot display the sharp or flat signs, I've adopted the following conventions: # = sharp b = flat (because they look sort of the same) Using a piano-style keyboard as my model, I would only list the enharmonic sharp or flat note-name if it either happened to fall on a black key or on one of two adjacent white keys. The twelve pitch classes, then, are: B#/C C#/Db D D#/Eb E/Fb E#/F F#/Gb G G#/Ab A A#/Bb B/Cb My example is a half-note third octave F, and since it falls on one of two adjacent white keys, the enharmonic name, E#, is also listed: 8 3 E#/F B. Record sizes. The HYMN.DBF database file is a fixed-field format file of 720 records, corresponding to 720 hymns. Each record consists of 172 bytes, with a field breakdown as follows: # of bytes description 2 hymn tempo 48 composer 48 title 48 first line 2 note-or-rest bit array 8 melodic interval array 8 octave number array 8 note duration array