Club Amiga de Montreal

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

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 565a.lha / CDCat_v1.0 / CDCat.doc.pp / CDCat.doc

Wrap

Text File | 1991-11-01 | 20.2 KB | 436 lines

CDCat Version 1.0 Documentation CDCat, the compact disc database, is Copyright 1991 John M. Meyers. It is freely distributable through various telecommunication sources as long is this archive is kept intact. This means that the following files must be included, and unaltered: Name Size Description CDCat 26796 bytes Program file CDCat.info 1140 bytes Icon for Workbench CDCat.doc 20707 bytes This documentation file cddata 4697 bytes Abridged copy of my data file to let you try CDCat without having to enter all your data. Permission is given to services that distribute disks of public domain, shareware, and freely distributable software provided that 1) all of the four files above are included in unaltered form, and 2) those services charge only for media, duplication, and shipping costs. This program MAY NOT be included with any commercial product without the expressed written permission of the author, John M. Meyers. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - "BEFORE I BOTHER RUNNING IT, WHAT DOES IT DO?" CDCat is a simple database with many features including : * 999 entry capability. * Eight datafields per entry 1) Artist 2) Album 3) Year 4) Tracks 5) Label 6) Catalog Number 7) Number of discs in set 8) Comment * Search capability by field with wildcard support. * Comprehensive sorting function sorts the list TWICE by two user-chosen criteria. * Built in view window allows user to see many entries at once. View window also supports non-proportional fonts of all [reasonable] sizes. * Output mode to dump list of entries to file (or printer) * User-definable formatting for output and view window functions. * Preferences feature to change settings, and save them. * Smaller than 27K. (Can be compressed to fewer than 15 kilobytes) * Of course, CDCat is 2.0 compatible. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - > > DISCLAIMER < < I WROTE THIS PROGRAM WITH MY NEEDS IN MIND. I am releasing it because others may find it useful. If they don't, I'll shed no tears. But, don't let this scare you. If you feel a feature is missing, feel free to suggest it. Who knows? I may like it and decide that an upgrade is worthwhile. CDCat is NOT shareware, so if you like it, you are under no obligation to contribute anything. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - CREDIT WHERE IT'S DUE... Special thanks goes out to... Steve Hoult - for his suggestions, and exhaustive testing (including under AmigaDOS 2.0) Dave Timmer - for his suggestions and testing - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - PROGRAM DESCRIPTION I've been looking for a small database program that would allow me to catalog my compact disc collection for some time now. I've found plenty of fine address-book programs, but not a program that would easily (and reliably) let me keep track of my albums, so I decided I would change things. CDCat was written to fill this gap. Not only will it allow you to quickly enter your albums, but it has some fairly comprehensive sort and search capabilites, as well as flexible view/output modes. There is also a small preferences feature to allow you to save your options. All this, in a program under 27K. Don't let the name scare you into thinking this program will only be useful for compact disc collections. Cassette and LP collectors may benefit equally as well. Steve Hoult suggested that there be a method to include all media types in the same data file, with some way of differentiating them. I decided to include a general-purpose "comment" field, which may be used for this purpose. (So, the tapes in your collection could be commented as "Cassette", or whatever) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - RUNNING THE PROGRAM CDCat takes no arguments, so simply entering the program name from the CLI is sufficient to start the program. Because CDCat detaches itself from the CLI, there is no need to use RUN or RUNBACK. Workbench users...[drum roll]... just double click the icon. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - OVERVIEW OF GADGETS This overview is just to familiarize you with the gadgets. The functions activated by them are detailed later on in the document. o Field string gadgets - these eight gadgets are where you enter (and view) your entries. o "-", index, and "+" gadgets - flip through your entries with these o ADD - toggle the ADD mode o UPDATE - replace the current entry with the information currently in the fields o CLEAR - Either wipe the data from the fields, or abort certain operations o DELETE - remove the current entry from the list o SEARCH - enter SEARCH mode, with the fields determining the search criteria o SORT - SORT the list based on the criteria set in CDCat's preferences o NEW - wipe out the whole list and start over o VIEW - open the VIEW window o PREFS - open CDCat's preferences window o filename string gadgets - holds filenames used in I/O operations o LOAD - load data file from file specified in Load/Save gadget o SAVE - save data file to file specified in Load/Save gadget o OUTPUT - dump data in formatted text to file specified in Output Name gadget - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - QUICK DESCRIPTION OF ENTRY FIELDS The artist,album, and year fields are obvious, so I won't bother. Tracks - the number of songs on the disc. Label - the company the disc came from. Catalog - catalog number of the compact disc. (Usually on end of jewel box) (Thanks to Steve Hoult for this suggestion) Discs - number of discs in the album Comment - Fifty characters of anything you want. Dave Timmer suggested that you can use the discs field to also store the album medium. So perhaps "D1" could mean compact disc with 1 disc, or "C1" could mean one cassette. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - HOW DO I ADD ENTRIES? To begin entering your albums, hit CLEAR to clean the fields. Then, hit ADD and start entering your albums starting with the Artist field. Note that when you press [RETURN] in one field, the cursor goes to the next. (EXCEPTION - if Artist or Album fields are empty, the cursor will stay. (Thanks to Steve Hoult for that suggestion.)) When you press [RETURN] in the Comment field, the entry will be saved in the list, the fields will be cleared, and you will start fresh in the Artist field. Please note that the only way to actually save the entry is to press [RETURN] in the Comment field. If you exit ADD MODE without saving the current field, the list will NOT be updated. In fact, you will also lose the current field, because when ADD MODE is exited, the last entry in the list is displayed. If you want to change the current entry, simply change the desired field(s) and hit UPDATE. This will change the current entry to reflect the information in the fields. Note that the list is not changed until you hit UPDATE. Changing fields in itself doesn't update anything. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - HOW 'BOUT DELETING ENTRIES? Double-clicking DELETE will remove the current entry from the list. If you hit DELETE and have second thoughts, click CLEAR to abort. DELETE will not work in ADD or SEARCH modes. If you want to erase ALL entries, double-click NEW. You again have the option of aborting by clicking CLEAR. And, NEW will not work in ADD or SEARCH modes, either. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - MANEUVERING AROUND The "-" and "+" gadgets will move backward or forward, respectively, through the list. Entering a number in the gadget between those two will allow you to specify which entry to go to. If you enter a number that is greater than the maximum entry in your list, it will leave you at that last entry. In SEARCH mode, the two direction gadgets go through the list of matching fields. The center gadget is inoperative. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - FINDING STUFF To find entries with common fields, use the SEARCH mode. To enter it, put your search criteria in the desired fields and click SEARCH. (Blank fields will match all.) So if I wanted to find every album from 1968, I would leave every field blank except year (1968) and hit SEARCH. If there are any, they will come up. If you want a very specific search, use more than one field to specify criteria. Entries will match only if all fields match the criteria. (Again, with blank criteria fields matching anything) Sorry, but searching is CASE SENSITIVE. So, "Marillion" is NOT THE same as "MARILLION." But, there are wildcards. "?" will match any one character, while "?*" will match any number of characters. (These are SAS's choices, not mine.) So, 197? in the year field will match any album in the Seventies, etc. Grammatical articles "a", "an", and "the" are ignored. So "The Cars" will match "Cars". But because of the method I use of discarding articles, searching for an album such as "The ?*" will match every album on the list. If you really need to search for all the "The" albums, use "Th?*" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - SEEING YOUT ENTRIES If you want to see more than one entry at once, try opening the view window by clicking VIEW. Use the horizontal and vertical proportional gadgets to move through the list. The format of the output depends on the settings in CDCat preferences. The view window will automatically open to the size of the screen. AmigaDOS 2.0 users will find this most useful (annoying?) if they have a large virtual Workbench, but interlaced (400+ line) Workbenches will work, also. The view window will also handle different size fonts. The default font (Third setting on 2.0) is used. (1.3 users can use NEWFONT) Warning to 2.0 users - If your system text font is not Topaz-sized, things will look VERY messy. The reason I didn't request TOPAZ specifically is that NEWFONT would then override them and put the new font THERE, too. Go figure. If you would rather save the formatted text to disk, use the OUTPUT function. The text will be formatted in the exact same way as with the view window. (To print your list on a line printer, specify "PRT:" as your Output Filename) * NOTE - in search mode, only the matching entries will seen! - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - SORTING THE LIST First of all, sorting criteria are set in CDCat preferences. There are two choices you have to make about how you want the list sorted. The first is the type of sort for the primary (first) sort. There are four options: 1 - Alphabetically by artist. 2 - Alphabetically by album. 3 - Chronological order 4 - Reverse-chronological order What sets CDCat apart from other programs is that there is a SECOND sort available. So, if you have more than one album from a particular artist (and most of us do,) you can sort THOSE albums again, by different criteria. And they are: 0 - no secondary sort. 1 - Chronological order 2 - Reverse-chronological order 3 - Alphabetically by album. Don't worry about memorizing them. They are listed in the preferences window. (Thanks to Dave Timmer for this suggestion) Grammatical arguments are ignored, so "The Cars" will sort between "Camel" and "Chicago". "A" and "An" are also ignored. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - THAT'S THE WAY I LIKE IT In CDCat's preferences, you can save many of the user-definable settings. It is here where you set the sort methods. There are two places where you can save the preferences. One is the current directory ("CD" gadget), which is where CDCat first looks for its preferences. You can also save them in your "S:" directory with the corresponding button. The filename is always called "CDCat.prefs". If you don't want to save your preferences but wish to keep them, click on "USE", and they will remain in memory. To forget them altogether, click CANCEL. The Load/Save and Output filenames are also saved with the preferences. The format CDCat uses for its VIEW and OUTPUT features can be set by you. This is the place to do it. There are eight string gadgets, and ten choices of output. The choices are: 0 - No output 1 - Index number 2 - Artist 3 - Album 4 - Year 5 - Tracks 6 - Label 7 - Catalog 8 - Discs 9 - Comment You can mix them in any order you like. If you like to stress the artist, use an order of 1,2,3,4,5,6,7,8,9. This will put the output in the order of the items listed above. But, if you have your albums sorted alphabetically by album title, you may prefer 1,3,2,4,5,6,7,8,9 which will switch the artist and album fields. If you want to drop a certain item, say, index number, fill in a 0 either there, or at the end of the list. (Which gadget a number is in isn't important - but the order of those numbers is.) If you only wanted to list artists, you could do 2,0,0,0,0,0,0,0,0, or 0,0,0,2,0,0,0,0,0 or 0,0,0,0,0,0,0,0,2. They all have the same effect. * Special thanks to Dave Timmer for suggesting that the output choices be listed on the preferences menu. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ERROR AND WARNING MESSAGES Errors are displayed in the CDCat Window title bar. * Can't open data file! * The data file was either not found (incorrect file name perhaps) or its read permission bit is not set. Double check the name or file attributes. * Not a data file! * The data file you specified was either not CDCat data file, or was perhaps from a more recent version of CDCat. (The first line of the file should read "CD10".) This line was added to allow for radical changes in CDCat, and yet allow it to be backwards compatible. * Couldn't save file! * Some disk error occured on save. Some reasons could be an invalid filename, the disk was full, or perhaps the file existed and was protected from deletion. Check the destination directory. * > LOW MEMORY < * CDCat tried to allocate some memory, and it couldn't get it. If the view window is open, it will close to try to free up some memory. CDCat will attempt to allow you to save your data, but it is strongly suggested that you try to free up some other memory before attempting this. * Couldn't save output file * An error occured while writing your output file. There was either a disk error, or your printer isn't turned on (for "PRT:" output files) (DELETE pending...) Lets you know that you have selected DELETE once. Were you sure about this? * Data has not been saved. Confirm * This message appears when you have modified your data and have selected a function that may erase it. Click CLEAR to abort, or reselect the function to confirm your choice. (For more details, see the MISCELLANEOUS section) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - MISCELLANEOUS STUFF Field sizes : Artist 35 characters Album 35 characters Tracks 2 characters Year 4 characters Label 20 characers Catalog 15 characters Discs 2 characters Comment 50 characters * Clicking VIEW or PREFS while the respective window is open will push it to the front. * When the fields are cleared in ADD mode, a "1" will be put in the discs field. This is a feature, not a bug! It saves typing when entering your collection, since most albums will probably contain 1 disc. * Pressing CLEAR kind of puts you at an "undefined" index in the list. In other words, a limbo. (Think of it as being number 0 in a list from 1 to whatever) Thus, when you have CLEARed the fields, you will not be able to DELETE or UPDATE that entry. To get back in the list, either enter the desired index or click "+". Originally, CLEAR just wiped out the fields, but really left you at the entry where you were. Then, by accidentally hitting UPDATE, you would wipe out the current entry, and not even know it. * As mentioned before, there are some safeguards put in to certain features. DELETE requires a double click before erasing the current record. Both LOAD and the CLOSEWINDOW gadget require a double click if the current data has been modified but not saved. (*NOTE* Because of the cheap way I implimented this check, if you press LOAD, get the warning message, and press the CLOSE gadget, the program will not warn you again, but rather quit. If you press CLOSE, get the message, then press LOAD, the program will load in the data without warning. Sorry about this, but I put it in to catch casual mistakes.) * If you LOAD in a file, and that file doesn't exist, not only will you get a message, but your current data will still be in memory. But if the file DOES exist, but is not a CDCat data file, you will get a warning message, but lose the current list. (If you LOAD in a corrupted CDCat data file, watch out! I don't do error checking on that stuff.) * You can hold down the plus and minus gadgets. * The format of the data file is in a simple text format. Here it is: NOTE - The comments here are for documentation. Comments are not allowed in the data file! CD10 /* header for CDCat 1.0 data files */ 1 /* the number of albums in the list */ Album Title /* Then for each album, the following eight */ Artist Name /* lines. Be sure that the number of characters*/ Year /* per item is not greater than the above */ Tracks /* limits! For empty entries, a period (.) is */ Label /* used. */ Catalog # /* Blank lines are ignored. */ Discs Comment /* Since only 1 album in this file, this is it!*/ Not hard at all... - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Are there any features you'd like to see in this program? Feel free to let me know - I might like them as well. I don't promise any upgrades, but that doesn't mean I won't release a new version, if there is enough demand for one. If you have any comments or questions, feel free to pass them on as well; I'd love to hear them. If you'd like to contact me and are lucky enough to have net access, you can reach me at: jmmeyers@mtus5.cts.mtu.edu or jmmeyers@symmetry.cs.mtu.edu Or, I make quarterly appearences on Steve Hoult's DUNE BBS in Grand Rapids, Michigan (User name - "John M. Meyers") Its number is (616) 451-4965. Thanks for trying CDCat, John M. Meyers