Scribe v1.01 Database/Rolodex for the HP48 S/Sx/G/Gx calculator written in 85% SysRPL, 15% ML (c) 1996 by Jack Levy 0.0 INDEX ========= 1.0 Description 2.0 Disclaimer 2.1 Email-Ware 3.0 Installing the Library 3.1 Library Information 3.2 Using the DataFile Conversion Programs 4.0 Usage Overview 4.1 Library Usage 4.2 Port Storage 4.3 Using the Interface 4.4 Interface Key Listing (Quick Reference) 4.5 Using the DataFile Selector 4.6 Using the DataFile Viewer 4.7 Using the ScratchPad 4.8 Configuring Scribe Options 4.9 Example 5.0 Error Messages 5.1 DataFile Structure 5.2 Organizer Hooks 5.3 Removing the Library 5.4 Credits 5.5 Version History 1.0 DESCRIPTION =============== Scribe is a library which will function as a Database or Rolodex. It is designed to hold a large amount of information in such a manner that it is easy to retrieve, quick to find, and transparent in usage. Scribe has the following highlights: * Perfect for keeping phone numbers, todo lists, addresses, databases of any size, or just keeping information in order. * The only database which stores datafiles in ports! This allows for incredible flexibility and much more storage capacity when dealing with RAM cards. * Versatility: Designed to handle (potentially) incredibly large datafiles (greater than 150K!) with little to no performance impact. * Browser/Full-screen Modes: View data either by their "headers" or in their entirety. DataFiles can hold an unlimited amount of entries, and each entry can be of an unlimited size. * Multiple DataFiles: Support for quick, easy changing between an unlimited number of datafiles. DataFiles can be named with true titles, not just single word labels. * High-speed Interface: Fast browser with ML display routines allow for quick access to the data you need. Full-screen view is displayed in a small 3x5 fixed-width font which contains 33 characters per line. This view can be scrolled to show longer entries with fast ML scrolling routines. Headers are displayed in the larger 5x7 font. Both fonts support lower case text. Utilizes Universal Font Library to save memory. * Automatic Compression: (Optional) seamless compression and decompression of all your data via BZ, with no speed loss. * Dynamic Port Lock/Unlocking: Change your RAM card's write protection switch at any time and Scribe will automatically adjust. * ScratchPad to quickly add common data (such as city/state names). * Quick Re-entry: Exit Scribe and return instantly to the exact position at which you left. Or, optionally, start each time in datafile selection mode. * Small Footprint: Scribe requires very little free memory to run and view datafiles, even extremely large ones! * No annoying parameter files: All parameters are stored in the hidden directory, away from the view of the user. * Direct importing/exporting of datafiles via Kermit and/or the stack. * Fast search routines which can be either case insensitive or case sensitive, toggled by the user. * Support for *any* external editor, such as StringWriter, ED, TED, or QED, or use the included accelerated editor replacement. * Special hooks which can be utilized by versions of Organizer after v1.0 to create a Todo Manager and/or Phone Database. * Many more intuitive features, including: Item reordering, uppercase conversions, automatic sorting of the database, automatic lower case data entry, and much much more! 2.0 DISCLAIMER ============== Scribe and its attached documentation are provided "as is", and are subject to change without prior notice. The author gives no warranty of any kind with regard to the software or documentation, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The author shall not be held liable for any damages, including any general, special, incidental, or consequential damages arising out of the use or inability to use any or all of the included programs. Use of any part of the Scribe library code is not allowed for any purpose, except, of course, when used directly from the Scribe library. You may not reproduce or modify any part of the Scribe library code without prior written permission from the author. Permission to copy the Scribe library as a whole, unmodified package is granted provided that the copies are not made or distributed for resale (excepting nominal copying fees). 2.1 EMAIL-WARE ============== The Scribe library is "Email-ware". What does this mean? If you like this program and use it regularly, you must send me an email message. (Not too steep, huh?) The idea is simple: If I know people are using this library, I will be more inclined to update it and write new programs. My internet address is levyj@engin.umich.edu. 3.0 INSTALLING THE LIBRARY ========================== To install Scribe in your HP48, follow these steps: 1. Transfer the library to your HP48 using Kermit/Xmodem/etc. 2. Press the soft-key associated with the library file (SCRIB101.LIB). "Library 1155: Scr..." should now be displayed on level1 of the stack. 3. Purge the SCRIB101.LIB variable, leaving the library on the stack. 4. Enter the port number you want to store the library into. Note: For S/G users, this number must be 0. For SX/GX users, the library can safely be stored in any port. However, for GX users, it is recommended that you store it in either port 0 or 1, as execution from a covered port is slower. 5. Press STO. 6. Turn the calculator off and then on again. Scribe also requires FNT1 from the Universal Font Library, also included in the Scribe archive. If you have no other applications loaded which require the UFL, you only need to load UFL1.LIB onto your calculator; If one of your current programs requires FNT2, you should load on UFL3.LIB instead. Scribe will work fine with either library loaded, but it will not run without one. For UFL installation instructions, see the enclosed UFL10.ZIP file. To access the library, press right-shift-library (2), and then NXT until you see "SCRIB". Press the corresponding soft-key to access the SCRIBE menu. It is suggested that you assign Scribe to the [RS]-[BACKSPACE] key, as this will allow for quick re-entry to your datafiles. You can do this by typing the following commands: { SCRIBE } HEAD 55.3 ASN To use this key assignment, you MUST be in USER mode (changed by pressing LS-Alpha). Then, to run Scribe, all you have to do is press [RS]-[BACKSPACE]. 3.1 LIBRARY INFORMATION ======================= Size : 14535.5 bytes Checksum : #2FB7h [#12215d] Version : 1.01 Library Number : 1155 You can check these numbers by putting the library on the stack and pressing LS-[VAR] [BYTES]. The above statistics correspond to the distributed version, and if they do not match your results, your copy of the library may have been modified. Scribe has been tested on a SX Revisions D/E/J, G Revision R, and GX Revisions M/P/R. However, as always, you should BACKUP YOUR MEMORY before running this application. 3.2 USING THE DATAFILE CONVERSION PROGRAMS ========================================== Due to the assortment of database and rolodex libraries out there, I have included two conversion programs (based on code by Jeoff Krontz) to transport your data into Scribe. CONVRLDX is provided to convert Rolodex databases. Simply recall the rolodex list to level1 of the stack and run CONVRLDX to convert. The program will leave a new, modified list on the stack. This list can then be imported into Scribe by using the [STK->] function in selector mode (see section 4.5). CONVGEN is provided to convert any database to Scribe's format. It will simply go through a list and save any string it finds into your new list. When it is complete, it will leave a new, modified list on the stack. This list can then be imported into Scribe as described above. If your datafiles already correspond to the format described in section 5.1 (basically, just a list of strings), then you need not worry about a conversion program. One example of this would be importing your Phones database from the Organizer v1.0 library, also by myself. To do so, simply run the following program: << DAT-> 4 GET >> This should leave your phones database on level1 of the stack. Similarly, using << DAT-> 3 GET >> should recall your TODO list to the stack. Again, to import this list into Scribe, follow the instructions above. 4.0 USAGE OVERVIEW ================== Scribe is essentially a browser and organizer for large amounts of data. Each entry in the database has a title and a body; entries of data are grouped into DataFiles; these datafiles are stored in user defined ports. There are two main "modes" in the database: The selector and the viewer. In the selector, you are viewing the datafiles in a specific port. By entering the viewer, you essentially "zoom" in on the selected datafile, and this is where you can view the specific data. This view can be changed to show either only the headers, or the entire entry using the whole screen. For example, you may wish to create a datafile titled "Phone Numbers". Inside this datafile, you might want to create one entry for each person; the title could be the name of the person (Last, First), with the body of the entry containing their address, phone number, etc. (In addition, turning on the AutoSort option would be useful if you wish to keep it alphabetically sorted. See section 4.8 for more information.) Alternatively, you could make all your phone numbers one entry, and simply scroll through this entry to find the phone numbers needed. Note that 99% of the features in Scribe can be accessed by selecting things with the selector bar (via [ENTER]) and using the keys in menuline. In order to avoid memorizing obscure key definitions, I have attempted to make all features accessible via the menuline as well. What follows is an explanation of each "mode" and how to use all of the features. 4.1 LIBRARY USAGE ================= There are only three commands in the Scribe library menu, as follows: [SCRIBE] - Load the Scribe application. [INFOSCRIBE] - Information screen with version number, author info and stats. The same screen which comes up when you press [EVAL] inside Scribe; however, when in Scribe, the screen will also show the size of the current DataFile. [SCLN] - After confirmation, purges hidden SCRIBEpar parameters file. Use this before you remove the Scribe library, or if you think your parameters file is corrupt. Essentially, all the functions of Scribe are contained within the actual interface. Therefore, rather than dealing with different library commands, all the user should need to do is load Scribe with the [RS]-[BACKSPACE] key, and all features should be available from there. 4.2 PORT STORAGE ================ One unique feature of Scribe is that datafiles are stored in Ports. The main memory of the 48 is used by Port 0. For GX users, if you have an unmerged RAM card in slot 1, this is port 1; the memory stored on cards in slot 2 is then designated to ports 2-32, each port being a maximum of 128k in size. For SX users, the maximum possible port is port 2. While other databases require you to store your data in directories, Scribe will take advantage of any RAM cards you have and allow you to store data on them as well. This is extremely useful when you want to leave unchanging databases in write protected/seldom used parts of a card. [NOTE: If your calculator has no RAM cards, you can only store data in port 0.] Scribe can only access one port at a time. This port is specified by the [PORT] command in the [OPT]ions menu. All ports can *always* be accessed and read from; but you obviously cannot modify data stored in write-protected ports. As a shortcut to the [PORT] key, you can press the [.] key anywhere and change the port on the fly. In addition, numerical keys [0]-[9] can be used as quick jumps to their corresponding ports (except in fullscreen view, where [2]/[8] and [1]/[3]/[7]/[9] are used to scroll the text). Scribe will handle dynamic port locking/unlocking. This means that you can change the write-protection switch on your RAM card at *any* time while using Scribe, without exiting or warm-booting. Scribe will automatically adjust for the change and there is no pause. Note, however, that the Selector Titlebar write-protection status will not be updated until the selector is reloaded; but the change takes effect immediately after the switch, and you can continue to use Scribe normally. On each load into the selector, the defined port is scanned for the deletion or addition of datafiles, and the proper adjustments are made to the list. (New datafiles will be appended to the end) Objects in ports can not be re-ordered, so the order you create in the selector is saved in SCRIBEpar. This order is retained until datafiles are added/removed from the port (in which case the list will be adjusted accordingly) or SCRIBEpar is purged. On each load into the viewer, *ALL* parameters are double checked for safety. It is therefore completely safe to modify your data outside of Scribe; if there is any inconsistency in reading the datafile when you reload Scribe (i.e. The viewer was viewing an entry which is now deleted), an error message will be displayed and you will be placed in the selector. NOTE: Datafiles are only permanently saved when you change datafiles or exit Scribe! If you edit a datafile stored in a write-protected port, Scribe will allow you to make the changes while still in the database. However, when you exit, an error message will be displayed and all changes lost! 4.3 USING THE INTERFACE ======================= The Scribe application is based around a browser-type interface which remains consistent in usage. This section will explain briefly how to use and take advantage of the many features this interface has to offer. A few words about notation: Any word in brackets [] denotes an actual key you would press on the HP48 keypad. [RS] means press the right-shift, and [LS] means press the left-shift. Selection of an item is always done with an inverse selection bar. This bar is easily controlled by the [UP] and [DOWN] arrow keys. Pressing either of the two keys alone will move the bar one item at a time. By pressing [LS]-[UP] or [LS]-[DOWN], the bar will move six items up or down, respectively. Pressing [RS]-[UP] or [RS]-[DOWN] will move the bar to the top or bottom of the file, respectively. These navigational keys follow standard HP conventions, and are consistent with the navigational keys in the built-in graphical browsers. ** NOTE: ALL NAVIGATIONAL KEYS REPEAT BY HOLDING THEM DOWN! The [RIGHT] and [LEFT] arrow keys can be used to go deeper into or out of the tree of data. For example, from the selector, using the right arrow will move you to the browser view of your datafile and then fullscreen. The left arrow will then follow this path backwards until you reach the selector. Throughout Scribe, you will see two arrows in the titlebar at the top of your screen (a down arrow on the left and an up arrow on the right). Whenever you are in a browsing mode with a selector bar, these arrows will appear when more entries are above or below the screen. When you are in a fullscreen view, these arrows will appear when there is more text to scroll above or below the screen. In general, pressing the [ENTER] key will "select" or "go into" the item the bar is over. In addition, the [ON] key will "abort" or "exit" the function or environment which you are in. In terms of list maintenance, logical operations have been assigned to logical keys as an alternative to the menuline functions. The [+] key will generally add an item to the current file. The unshifted version will always add in the current "location" of the bar, while the [RS]'d version adds the item after the bar, and the [LS]'d version adds the item at the top of the list. The [-] key will (after confirmation) generally delete the selected item. (This is also assigned to the [DEL] key) The [LS]-[+/-] key (EDIT) will generally edit the selected item. Scribe has a customized editor which is used for all input prompts instead of the customary InputLine. In the menuline, you will see two keys that allow you to jump out into the [OPT]ions menu or the Scratch[PAD] quickly (see section 4.7 for details). The [OPT] key may also be assigned to a different toggle. Pressing [ON] will provide an "Abort Edit?" menuline prompt for confirmation if the data has been modified. Note also that arrow key movement is accelerated. Finally, the [Alpha] key will generally search the selected list. When you are prompted for a string to find, FIND will show either "Ignore Case" or "Match Case" at the top of the screen. Pressing the [CASE] button in the menuline will toggle the case sensitive option ON or OFF, as in the OPTions menu. [LS]-[Alpha], when used from the interface, acts as a "FIND NEXT". 4.4 INTERFACE KEY LISTING (QUICK REFERENCE) =========================================== Here is a complete listing of keys for the Scribe interface. [LS] = Left Shift, [RS] = Right Shift [UP] Move selection bar to the previous item. [LS]-[UP] Move selection bar back six items. [RS]-[UP] Move selection bar to the top of the list. [DOWN] Move selection bar to the next item. [LS]-[DOWN] Move selection bar forward six items. [RS]-[DOWN] Move selection bar to the bottom of the list. [LEFT] Move up the tree of data (Fullscreen->Header->Selector). [RIGHT] Move down the tree of data (Selector->Header->Fullscreen). [8] Scroll the fullscreen view up a line. [LS]-[8] Move fullscreen view up 8 lines. Also [9]. [RS]-[8] Move fullscreen view to the top of the item. Also [7]. [2] Scroll the fullscreen view down a line. [LS]-[8] Move fullscreen view down 8 lines. Also [3]. [RS]-[2] Move fullscreen view to the bottom of the item. Also [1]. [9] (PgUp) Move fullscreen view up 8 lines. Also [LS]-[8]. [7] (Home) Move fullscreen view to the top of the item. Also [RS]-[8]. [3] (PgDn) Move fullscreen view down 8 lines. Also [LS]-[2]. [1] (End) Move fullscreen view to the bottom of the item. Also [RS]-[2]. ** NOTE: ALL NAVIGATIONAL KEYS REPEAT BY HOLDING THEM DOWN! [0]-[9] Jump to datafile selector in the corresponding port number. NOTE: These keys disabled in fullscreen view. SX Users: Keys [3-9] are disabled. [.] Prompt for a jump to any port and enter selector. [+] Insert a new item at the current position. [RS]-[+] Insert a new item after the current position. [LS]-[+] Insert a new item at the top of the list. [-], [DEL] Delete the selected item (prompts for confirmation). [LS]-[+/-] Edit or rename the selected item. [Alpha] Search for a string (case insensitive or sensitive). [LS]-[Alpha] Find next occurrence of the last string entered. [ENTER] "Select" or "go into" the selected item. Also [VIEW]. [ON] Abort the current function or exit the current interface. [RS]-[ON] Turn the calculator OFF. [NXT] View the next page of the menuline. ['] Load OPTions menu to quickly configure Scribe (see section 4.8). [STO] Load ScratchPad for quick editing (see section 4.7). [EVAL] Informational screen with version number, author info and stats. 4.5 USING THE DATAFILE SELECTOR =============================== When you load Scribe for the first time, you will be in DataFile Selection Mode, or the selector. This is an environment for handling multiple datafiles easily. The number of datafiles Scribe can handle is only limited by memory, and each datafile name can be any number of characters long. (Note, however, that the titlebar can only display a maximum of 26 characters, and the browser a maximum of 22.) On the top of the screen is a titlebar which should say "DATAFILES P0/NP [0/0]". This is a status indicator which will tell you how many datafiles exist and what location you are in the list. It also tells you two things about the selected port being read: The number after "P" represents the port currently being read; A trailing "WP" would mean the current port is Write Protected, and a "NP" would mean the current port is Not Write Protected. The rest of the screen should be blank, excluding the menuline at the bottom. Pressing [EVAL] will bring up the information screen, which will tell you how large the selected datafile is (if any exist), and how much room is free in the current port. The following commands appear in the selector mode menuline: [ADD] Create a new datafile. You are prompted for a name, and this name can be of any length with any characters (spaces are valid). Note, however, that the interface can not show anything longer than 22 characters. Pressing this in it's unshifted form will insert the database at the location of the selector bar (if it exists). Also [+]. [RS]-[ADD] Create a new datafile after the current position. Also [RS]-[+]. [LS]-[ADD] Create a new datafile at the top of the list. Also [LS]-[+]. [DEL] Delete the selected datafile (after confirmation). Also [DEL]. [REN] Rename the selected datafile. Also [LS]-[+/-]. [FIND] Search for a string. Also [Alpha]. [LS]-[FIND] Find next occurrence of the last string entered. [VIEW] Toggle between selector and viewer modes. Also [ENTER]. [EXIT] Exit Scribe. Also [ON]. [OPT] Enter the options menu (see section 4.8). [MOVE] Move the selected datafile to the top of the list. [LS]-[MOVE] Move the selected datafile up one entry (key repeats). [RS]-[MOVE] Move the selected datafile down one entry (key repeats). [SEND] Send selected datafile to wire via Kermit. [RECV] Receive a datafile into the selected name via Kermit. (prompts for confirmation) [LS]-[RECV] Prompts for a name and then receives a new datafile into this name via Kermit. (".DF" automatically appended) [->STK] Export the selected datafile to the stack. [STK->] Import a datafile from the stack at the current position. (prompts for a name) [LS]-[STK->] Import a datafile from the stack into the selected name. Very few of these items should need explanation. Just one note: You may have noticed that there is a "MOVE" function, but no "COPY". This is because you can easily copy a datafile by exporting it to the stack with [->STK] and then immediately importing it to another filename. 4.6 USING THE DATAFILE VIEWER ============================= When you press [ENTER] or [VIEW] in the selector mode, you will enter the datafile viewer. This is where all the functionality of Scribe comes in. In the datafile viewer, all of the actual data in each datafile can be viewed, moved, edited, etc. easily and quickly. Initially, there will be no items on your screen, as it is an empty datafile. A description of the menuline below will show how to create and handle data. After creating entries via the menuline keys, you will see the headers you entered in the slots of your browser mode. In the datafile viewer, the [ENTER] key will switch back and forth between browser and fullscreen views. Note that *ALL* keys and menuline options remain the same in both of these views; they are not different modes, simply different views of the same data. The browser view displays 22 characters of each heading in a 5x7 medium font, and movement is done with a selection bar. The datafile name is shown in the titlebar, and arrows in the title-line appear when there are more entries above or below the screen. The fullscreen view displays 33 characters per line of text in a small 3x5 font which supports lower case (!!). The header is shown in the titlebar along with your current line location in the current entry (i.e., what row number of the entry you are viewing, out of the total number of rows). The rest of the data is displayed in the small font with fast ML display routines. The arrows in the title-line appear when there are more lines above or below the screen. Pressing the [8] key will scroll this display up, while pressing the [2] key will scroll this display down. Pressing [LS]-[8] or [9] will act as a page-up; pressing [LS]-[2] or [3] will act as a page-down; pressing [RS]-[8] or [7] will move you to the top (home); pressing [RS]-[2] or [1] will move you to the bottom (end). The scrolling routines are designed to handle (potentially) very large entries (it has been tested with entries over 1000 lines long!). The page-up and page-down routines will repeat and make quick movement to different parts of the entry very easy. Also, note that all these navigational keys only work in fullscreen view. The location in the screen is saved when you exit Scribe in fullscreen view; however, this location is reset whenever you return to the browser view. In addition, port changing keys [0]-[9] are disabled in the fullscreen view, to prevent confusion or accidental port changing. The following is a description of each menukey: [EDIT] Edit the selected entry. Also [LS]-[+/-] (edit). [ADD] Insert a new entry at the current position. You are first prompted for a "header", which is to appear in the browsing view and as a title in the fullscreen view. After that, you are prompted for the data which will go into this entry. Pressing [ON] at any time aborts creation. Also [+]. [RS]-[ADD] Insert a new entry after the current position. Also [RS]-[+]. [LS]-[ADD] Insert a new entry at the top of the current datafile. [LS]-[+]. [DEL] Delete the selected entry (after confirmation). Also [DEL]. [FIND] Search for a string. Also [Alpha]. [LS]-[FIND] Find next occurrence of the last string entered. [DSEL] Toggle between selector and viewer modes. [EXIT] Exit Scribe. Also [ON]. [OPT] Enter the options menu (see section 4.8). [MOVE] Move the selected entry to the top of the list. [LS]-[MOVE] Move the selected entry up one position (key repeats). [RS]-[MOVE] Move the selected entry down one position (key repeats). [SORT] Sort the current datafile alphabetically (after confirmation). [->UCS] Convert the current entry to uppercase text. [->STK] Export the current entry to the stack. [STK->] Import an item from the stack at the current position. As with the selector mode, very little explanation should be needed for these functions. However, a few notes: Only the editing of the data part of an entry uses the external editor. The rest of the prompts are done with my own custom input routines. While editing this data, use the NEWLINE key [RS]-[.] to create more lines. If you enter all the data in one long line, it will simply be truncated when viewing. 4.7 USING THE SCRATCHPAD ======================== When entering data into Scribe, sometimes you want to enter a certain phrase or group of words more than once. To save time while doing this, there is a "ScratchPad" available in all input prompts. For example, let's say you are creating a phone book, and you want to include "Los Angelos, California" in all your friends' addresses. This would be a bit laborious to type, but if you store the string in the ScratchPad, you can insert it in any prompt with two key presses. Other uses may include frequently searched for items, or strange character combinations you don't want to have to look up in the character browser. The ScratchPad can be edited from the Scribe browser by pressing the [STO] key. During an edit (while using the supplied editor), you can jump to the ScratchPad by using the [PAD] key in the menuline. When you view the ScratchPad, it will list six rows of text (which will be initially blank). These rows are labeled [A-F], and the six [A-F] menukeys correspond to each row. To create a string, use the left-shift and any menukey. A normal prompt will come up, and you can enter anything you want, including spaces, newlines, etc. To blank a string from the ScratchPad, you can use right-shift and the menukey. Pressing a menukey by itself will insert the text in the corresponding slot right into the current cursor position, leaving the cursor one character after. Finally, pressing [ENTER] or [ON] will return you to the editing prompt unchanged. Note that the ScratchPad entries are stored in SCRIBEpar, and will remain there until you blank them or rebuild SCRIBEpar. Here's a quick list of key definitions in the ScratchPad: [A-F] Insert the corresponding string at the current cursor position. [LS]-[A-F] Create/edit the corresponding string. [RS]-[A-F] Erase the corresponding string. [ENTER] Return to the editing prompt unchanged. [ON] Return to the editing prompt unchanged. [RS]-[ON] Turn the calculator OFF. 4.8 CONFIGURING SCRIBE OPTIONS ============================== Options in Scribe can be setup at any time by pressing the "OPT" key in the menuline, or by pressing the ['] key when in the browser. The screen will display the status of all six options and allow you to quickly edit them. The menuline will change to display the following: [EXTED] [ALPH] [SORT] [SEL] [BZ] [PORT] Pressing any of these keys will configure the option. (When a small box appears in the menukey, the option is considered to be toggled "ON") Pressing [ENTER] or [ON] will save the options and return to the previous screen. The following is a description of what each option is: [EXTED] Define an external editor. When you press this to toggle the option on, you are prompted for an editor name. You may enter any valid editor name here. The major popular editors (StringWriter, ED, TED, and QED) are assigned keys in the menuline. Simply press any of them and they will replace your editor command with the proper command to load the respective editor. If an external editor is already selected, this key will change the editor to "Normal", meaning the custom editor already in Scribe. NOTE: The external editor *must* take a string from level1 and leave the same upon exit. If there is any change in the stack (i.e. More/less items, different items, etc), Scribe will abort the edit and changes will not be saved. Therefore, if your editor leaves more than just a string (i.e. also a cursor location), you must write a short program to change the stack and define that as your editor instead. (For example, << EDITOR DROP >> to get rid of a cursor location left over) [ALPH] Toggles the InputLine default Alpha status. If [ALPH] is set to "Lower", when you enter any inputline, the alpha key will default to lowercase first. Useful for those who enter mostly lowercase text. [SORT] Toggles auto-sorting of the database. If toggled [ON], the database will be automatically sorted after any modification is made to it. Good for phone books and other sorted databases. [SEL] Toggles auto-loading of the selector. If toggled [ON], Scribe will automatically put you in the selector on *every* load, regardless of its previous state. If [OFF], you will return to the *exact* position you were in when you left. [BZ] Toggles automatic BZ compression/decompression of the datafiles. When toggled [ON], Scribe will automatically compress your data with BZ before it is saved. If you wish to compress or decompress already existing datafiles, simply change the BZ setting and then open/close the datafile; Scribe will automatically update the status of the datafile. Also note that Scribe will always try to decompress a compressed datafile, even if the [BZ] option is toggled off. You can therefore view compressed datafiles without using the [BZ] option, as long as BZ can be found. NOTE: Scribe can find BZ if it is in any port, the HOME directory, or the current directory of usage. However, it must be named "BZ", as that is all Scribe will look for. If BZ is not found, Scribe will return an error message stating so. Also, it is significant to point out that Scribe's speed is not affected by the compression of datafiles. Compression/decompression only happens when a datafile is "opened" or "closed", and therefore all viewing/modifications are just as fast as with an uncompressed datafile. [PORT] Define the port Scribe is currently accessing. For GX users, this can be any number between 0 and 32; for SX users, this can be any number between 0 and 2. Nonexisting ports are allowed, you will simply not be able to create any data. The port can be modified at any time except while changing options from an editing prompt. Whenever a change is made, the selector is reloaded to show the datafiles in the specified port. Pressing [ON] aborts the modification. One other configurable option is available, but not from the [OPT]ions menu; the following toggle key is displayed whenever using the [FIND] mode: [CASE] Toggles the case sensitive find. If this setting is set to "Match", then Scribe will attempt to match case exactly in your search. Otherwise, case is ignored. [Note that the status of this option is shown when you perform a search, and you are given the option of toggling it on the fly] 4.9 EXAMPLE =========== Some users have not been sure exactly how to enter, import, export, and view data in Scribe, and need a simple example to get them started. You can enter data into Scribe in any number of ways, but what follows is one possible method you may use to keep a phone book. First, save the lines of data between the two [CUT]'s to a file: ---------------------------[CUT] %%HP: T(3)A(R)F(.); { "Blake, Alex 45 Ethel Road Somerset, ZA (777) 777-7777" "Smith, Michael 14 Drake Court Las Vegas, ZA (111) 111-1111" "Tilley, John 92 Salaam Drive Smalltown, ZA (222) 222-2222" } ---------------------------[CUT] Use Kermit to send the file to Scribe via [LS]-[RECV] in the selector (make sure to do an ascii send). Name the datafile "Phone List". Once it is imported, press [ENTER] to view the database. It is now showing you headings view--the first lines of each string (in this case, names). Move to the entry you want to view in full detail and press [ENTER] to zoom in/out of the view. No fields are designated, but the structure is obvious: 1 entry per person, name on line 1, street on line 2, city/state on line 3, and phone number on line 4. Optionally, turn on Scribe's AutoSort function, so the list is always alphabetized. 5.0 ERROR MESSAGES ================== All errors in Scribe are trapped and handled cleanly. What follows is an explanation of the some of the more common messages, in case you are not sure of their exact meaning. "Invalid Parameters!" The information in SCRIBEpar does not correspond to the actual information in the datafile. [This could mean the datafile was modified outside of Scribe] The selector will now be loaded. "Invalid Port!" Appears while editing the port in [OPT] [PORT]. Quite simply, it means that what you entered can not be used (i.e. Out of the 0-32 range, not a number, etc). "Invalid DataFile!" Appears when attempting to open a datafile from the selector; This error message will be shown if the content of the stored datafile is not a list, or a compressed list. (i.e. something other than a datafile has been stored under a datafile's name) "Editor Not Found!" There was a problem loading the defined external editor. Edit has been aborted. "Insufficient Memory!" Memory was too low to perform the specified task. "No Room in Port!" The DataFile you have created is too big to be stored in the designated port. (Note that a copy will be left on the stack) To check the size of working datafile vs. the available port memory, press the [EVAL] key at any time in Scribe. "Object In Use!" Most commonly appears when dealing with saving datafiles; it means that some other function has "locked" the old datafile from being purged before the new one is saved. "Port Not Available!" Most commonly appears when dealing with saving datafiles; this usually means that the defined port is write-protected or does not exist. "Undefined Name!" Most commonly appears when viewing datafiles; this usually means that the defined datafile does not exist, or can not be found. "BZ Not Found!" Appears when Scribe attempts to compress or decompress a datafile, and is unable to find a copy of BZ either in HOME, the current directory, or in an active library. If Scribe was attempting to compress the datafile, it will simply be stored as a list. If Scribe was attempting to decompress a datafile, you will not be able to access it until BZ is installed. 5.1 DATAFILE STRUCTURE ====================== As described in section 4.2, Scribe stores its datafiles in user defined ports. The options and previous locations are saved in the 'SCRIBEpar' variable, safely encoded as Library Data and stored in the hidden directory. You should never attempt to modify this parameter file directly, as doing so could cause Scribe to crash. However, if you suspect that your parameters file somehow became corrupt, feel free to delete it and reload Scribe. Scribe will automatically detect the absence of SCRIBEpar and create a new one with the default settings. The structure of each database is incredibly simple, as to make it easier for the user to edit on the calculator, as well as modify and create on a computer. Each datafile name *must* end with a ".DF" (for DataFile) in the name, or Scribe will not be able to detect it upon loading. DataFiles should correspond to the following structure: { $ $ $ ... $ } Where $ denotes a string. The first line of each string is assumed to be the "Header", and the rest is displayed as the actual "Data". ** WARNING: Putting anything in a datafile other than strings of text may cause Scribe to crash and/or lock up! If you are editing your datafiles directly, please make sure that you do not accidentally leave a non-string object in the list! 5.2 ORGANIZER HOOKS =================== As of versions of the Organizer PIM library after v1.0, ORG will use Scribe for its TODO/PHONE managers. To accomplish this, special hooks have been put in place. These hooks will save the previous SCRIBEpar settings, modify settings to suit the set mode, execute Scribe, and then restore settings when complete. The hooks should not interfere with normal operation of Scribe outside of ORG. Note, however, that the TODO/PHONE manager datafiles must now be stored as regular datafiles outside of OrgDATA in Port 0 (which means they will appear in the selector). The TODO hook performs the following actions: - Save SCRIBEpar settings in memory - Check for Todo Manager datafile in Port 0, creating if not present - Modify browser view and location settings - Load Scribe with the TODO datafile - Restore all previous settings - Return to Organizer The PHONE hook will do all of the above, except it will use the Phone Manager datafile and also turn the AutoSort option ON. 5.3 REMOVING THE LIBRARY ======================== To remove Scribe from your HP48, do the following: 1. Use Scribe to remove all old datafiles; optionally save a copy of them first with [->STK] in the selector mode. 2. Delete the hidden parameters file by running [SCLN] and answering [YES]. 3. Enter the port ID in the form :PORT:1155 and press ENTER *TWICE* Example: If Scribe is stored in port 0, enter :0:1155 DUP The port ID should now be on levels 1 and 2 of your stack. 4. Press the DETACH button (either by typing in by hand, or pressing left-shift-library, DETACH). 5. Press the PURGE key. Scribe should now be removed from your calculator. If you still get an "Object in Use" error, try turning off USER mode and switching to the HOME directory. Occasionally, if you have used Scribe extensively, you may have to do a warmboot (ON-C) before it will allow you to PURGE the library. 5.4 CREDITS =========== Many thanks go out to Arnold Moy, who wrote the original code that the display routines in the viewer are based on. In addition, Arnold has been a tremendous help in my learning assembly, which has in turn benefited Scribe in many ways. Thanks Arnold! Others who deserve thanks (in alphabetical order): Alex Chiang : Beta testing, name suggestions. Mika Heiskanen : Jazz, hacklib, and many of his other excellent programs which made much of the coding possible. Rodney Hess : Invaluable beta testing; many suggestions and stats. Joe Horn : List sorting routines. Othniel Rawlins : Sample browser code, which inspired me to write much of this library; beta testing, port switching ideas. Andre Schoorl : Beta testing, dynamic port [un]locking routines. Richard Steventon : Beta testing, row inversing sample code, ML help, newline counter optimizations. 5.5 VERSION HISTORY =================== [ v1.01 09/08/96 ] - Updated library to use and require Universal Font Libraries #1 or #3. - Key definitions added for fullscreen view to imitate a number pad: [7]/[1] act as Home/End, and [9]/[3] act as PgUp/PgDn. - Added section 4.9, "Example" database to documentation. [ v1.00 08/12/96 ] - Initial release to the public. scrib101.lib [1155] code by jack levy [levyj@engin.umich.edu], 09/08/96, 3:37p