[2"z ************************************ * Butler James V2.4 from 02.Feb.93 * * 1992 by C&h Special-Soft * ************************************  1) Introduction Gives you a brief overview of the basic functions and the intended use as well as some special aspects of using the program. 1.1) Recommended machine-configuration Butler should run on almost any machine without problems, that is all functions are available with 512 KB RAM, one drive and KS 1.2 . As soon as your database has about 1000 entries, it is recommended to use a hard- drive though, because floppy-disks always have a very poor performance as far as data access is concerned. This is a well-known problem, which can not be solved by the software, although the disk-access of Butler is highly optimized for maximum speed. Running butler will need about 32K of RAM for every 100 entries in addition to the size of the program itself as the highest expected value. This will only be used during delete or insert operation and goes down to 6K for 100 entries if butler is resident and waits for the defined hotkey. So if you have to run other applications that need much RAM, you should have at least 1 MB to be safe of getting those ugly messages like: Your machine is out of memory... 1.2) Basic Function After starting butler, the program keeps resident in RAM until you press the hotkey defined in the config-file "s:butler.cfg". (Most likely the Help key) Now butler wakes up (until now he was asleep and did not use the CPU, except the small input-handler that watches the input-stream.) and tries to open a window on the foremost screen. If the screen is to small, that is the width does not match, he tries to use the WB-Screen. If he fails for low memory, you´ll get the appropriate error-message. When you are done with your work, you can reset butler to his resident state, or you can quit completely. Pressing the hotkey while butler has his window open on any screen will make him close the window and re-open it on the foremost screen again. It is safe to close the screen that butler uses for his window, if the regular system functions are used by the owner of the screen, for butler can detect calls to CloseScreen and therefore closes his window first. Butler was designed for address-management, but can be used for other purposes, if the number of bytes per entry and the given number of input-fields are sufficient. A detailed description of each field is given below. +---------------+ | Field 1: 9 ch.| to +---------------+--+-----------------+ | Field 2: 29 ch. | Field 3: 29 ch. | firstname | lastname +------------------+-----------------+ | Field 4: 39 chars | extensions +------------------------------------+ | Field 5: 39 chars | street +------------------------------------+ | Field 6: 39 chars | place +------------------------------------+ | Field 7: 29 chars | telephone +------------------------------------+ | Field 8: 37 chars | comment +------------------------------------+ Further there are four input-fields for special purposes which will be named IF1 to IF4 in the following. Their position is shown below: Top left: New | IF1 | IF2 | Send Bottom right: UseFunc | IF3 | Select UseJok | IF4 | DeSlct Data is sorted in alphabetical order using the text in field 3 (lastname) and displayed in a very handy scrollfield. Each entry has a specification, given by the user when adding new data, that relates each entry to one or more of 8 groups. By the use of 8 switches, positioned directly under the scrollfield, the user can select a specific combination of groups for being displayed. This function works in realtime, that is there are no delays between selecting groups and getting the result (even if there are 1000 or more entries). As Butler has a little function-parser, you can give your own very special display-function in IF3, which will replace the normally used switches, for ex.: (1 and 3) or (2 and not (6 and 7))... or something like that. In addition to that, you can provide a joker-text in IF4 to reduce the display to all entries which have a field 3 (lastname), that matches the joker. 1.3) Special aspects of the user-interface As there are no pulldown menus, the right mousebutton can be used for other purposes, that make the program easy-to-use. The following actions are available: 1) Pressing the right button when the pointer is above or below the scroll- field: Leaf through the contents of the scrollfield (pagewise). 2) Pressing the left button when the pointer is upon an entry of the scroll- field: ACTIVATES this entry, that means: ·) The complete contents of it are shown in the input-fields. ·) It changes the color. ·) Further operations like save, send, prtlab ect. take effect on this entry, if they were selected with the left button. Certainly only one entry can be active. Activating another will therefore deactivate the previous activated entry. 3) Keeping the left button pressed, moving up and down the scrollfield: Butler keeps track of the pointer-position and activates the desired entry for you. If you move out of the scrollfield (over the top or the bottom border, the contents are scrolled up or down. 4) Pressing the right button when the pointer is upon an entry of the scrollfield: SELECTS this entry, that means: ·) The display changes to inverse.(like a bar over the text) ·) Further actions (see 2) take effect on all selected entr. if they are invoked with the right button. All entries can be selected at the same time and in 4 independent levels. (See 2.2.1 Specification gadgets, for details). The "selected"-state of an entry in any level does not depend on its display-state, that is if some entries are hidden by selecting new group-combinations, they keep their "selected"-state until they are displayed again and deselected. The actual state of all entries in all 4 levels can be saved using "store" if you need this state to appear the next time you run butler. Read chapter 2.3) for a detailed description of the available group- and display-functions. 5) As 4, but moving up and down: If the first entry (the one you clicked on) was deselected up to now, this and all following entries you move on,will be selected. If the first entry was previously selected,this and all following entries you move on, will be deselected. Moving out of the scrollfield causes butler to scroll up/down, selecting/deselecting all new displayed entries. 6) Security-checks (for ex. before delete), often use a different kind of communication than a requester. They print their message directly in the windows titlebar, waiting for the user to select the action again, or to cancel it by pressing the right button. This is very practical, because you don´t have to move your pointer to the O.K. gadget of the requester. Instead you select the function again, which leads into a kind of double- click. 2) Function description Gives you a detailed description of each gadget in the main window of butler, which functions are invoked through their selection and how to use them. l.M. stands before the function, invoked with the left mousebutton, r.M. stands before the function, called when the gadget is selected with the right button. 2.1) Input fields 2.1.1) Field 1 to 8 in the left part of the window: Are used to create new entries and to edit the existing data. There are 2 independent levels to store information, which are selected by the switch "Change". The jokers for "Select/Deselect" are also entered in this 8 fields. After pressing , the cursor moves to the next field. If AUTOINSERT is set ON in the configuration, data will be inserted automatical when is hit in the last field. 2.1.2) IF1: (Position, see 1.2) This value defines the minimum number of lines used by the "send"- command. This allows you to send all selected entries at once with a fixed number of lines (ex. 10 lines per entry), without adding line- feeds manually after each entry. 2.1.3) IF2: (Position, see 1.2) This is a block-number, which is used by "send" and "circular". Output is stopped after a given number of entries and continued after the hotkey was hit.This gives you the possibility to change the active window (to be typed in) or to feed new paper on your printer. A value of zero disables the wait-function. 2.1.4) IF3: (Position, see 1.2) Input-field for a boolean function, to be activated instead of the regular display-gadgets (USEFUNC). The syntax allows numbers from one to eight (representing the eight groups), & to AND two expressions, | to OR expressions, ! to NEGATE an operand, brackets in up to 20 levels and blanks. 2.1.5) IF4: (Position, see 1.2) Input-field for a joker-text ("*" is used as joker) which reduces the displayed data to all entries, that have a matching field 3 (index). The joker can be activated/deactivated by the switch USEJOKR. 2.2) Simple datamanagement 2.2.1) Tiny gadgets (numbered 1 to 8) l.M.: The on/off-state of the 8 switches define, in which of the 8 groups the data should be placed, when a save / insert is done. If you activate an existing entry, the switches show you which groups this entry is currently assigned to. r.M.: With the switches 1 to 4, you can easily switch to one of four independent selection-levels. This means that you can select various entries, then switch to another level and select other entries without having to destroy your previous selections. 2.2.2) Change l.M.: Changes the level of the 8 input-fields. There are two indep. levels to store data in the input-fields, so you can activate an entry, switch to the other level and activate another. Now you can compare both entries by switching Change on / off. The second level can also be used in conjunction with "select". r.M.: Lets you select a new configfile. That way you can change the naming of groups as well as the datafile and -directory. (see Ch. 4, DEVICE, FILENAME ect.) 2.2.3) Delete l.M.: Deletes (after security check) the activated entry. r.M.: As l.M., but all selected entries are deleted. As butler actually creates a smaller file when deleting something, this routine is not as fast as in other programs (SuperBase), where the entry is only internally marked as deleted and the file keeps the same size !!! Anyway the routines are highly optimized for maximum performance, so that only the speed of your hard-drive (and that of AmigaDOS) is essential. By using a drive with about 1 MB per second read/write speed (under AmigaDOS), it will take one second to delete 1 out of 2000 entries. The more entries are deleted at the same time, the faster AmigaDOS can do its task, for less data has to be moved. 2.2.4) Insert l.M.: Inserts the data of the 8 input-fields as a new entry, which will appear in all groups that are switched on at the moment. Before that, the program checks for entries with the same index (field 3) in the main-file. r.M.: As l.M., but the layoff-file is checked too. This can cause a delay, as data of the layoff-file is not present in memory, so it has to be loaded directly from disk. 2.2.5) New Deletes the contents of the 8 input-fields and activates field one. 2.2.6) Save l.M.: Overwrites the active entry with the contents of the input- fields and the current state of the 8 tiny group-gadgets. r.M.: Calls the automatic backup-function, which is done normally when you start butler. Here you can call it anytime you want butler to look for the defined backup-device and make a backup of the currently used file. (see BAKDEVICE) 2.3) Group-related functions 2.3.1) Group-gadgets below scrollfield Decide which entries are allowed to appear in the scrollfield. The kind of connection between the groups can be selected as AND or as OR connection. (see 2.3.4, &) 2.3.2) Select / DeSlct This serves to reduce (or expand) the regular displayed entries to the set of all selected /not selected ones. The connection between Select and DeSlct is always OR, the further connection of this with the state of the group-gadgets can be defined as AND or as OR. (see 2.3.5, | for details) 2.3.3) Set / Clear l.M.: Sets/clears all groups switched on at the tiny gadgets, in all currently displayed entries. The state of the other groups (on or off) of the entries are not affected. r.M.: As l.M., but all selected entries are processed. 2.3.4) & Determines the connection-mode between the single group-gadgets: OFF: All entries that are at least in one of the selected groups are displayed. -> OR-connection ON: All entries that are at least in all of the selected groups are displayed. -> AND-connection Entries that are assigned to no group, appear if no group is selected and "&" is set ON (as can be seen from the above), for every entry is in at least no group. 2.3.5) | Defines the connection-mode between the result of the group-gadgets and the result of Select/DeSlct. OFF: restrictive. That is, all of the entries defined by the group- gadgets, if they are Select/DeSlct too. Used to switch off all selected / not selected entries. ON: extending. That is, all of the entries defined by the group- gadgets and additionally all Select/DeSlct ones. This can be used to display all selected entries, no matter which groups they are in. 2.3.6) UseFunc Activates the function in IF3 instead of the regular group-gadgets. If there is a syntax - error, butler gives an error - message and reactivates the gadgets. Own functions are used, if the unique type of connection (1 AND 3 AND 7) is not sufficient and/or if negations have to be used (1 AND NOT (4 OR 5)). 2.4) Special functions 2.4.1) Circlr (circular) l.M.: After selecting a formtext and an output-device (or a file), the contents of the active entry are sent to the output-device, according to the rules of the formtext. The correct syntax of the formtext-commands is described in chap. 6, Using formtexts. r.M.: As l.M., but all selected entries are processed. 2.4.2) Select / Deslct l.M.: Selects/deselects all displayed entries. r.M.: Selects/deselects all entries (of the displayed ones), that match the joker-texts in the 8 input-fields. 2.4.3) Off / Inc Is used to transfer data between the currently used file and the alternate file (named .dat and .off). If you work with the main-file, this function will move entries to the layoff-file and vice versa. l.M.: The activated entry is moved. r.M.: All selected entries are moved. 2.4.4) PrtLab l.M.: After selecting a formtext, an output-device and a label from a label-sheet, the contents of the active entry are formatted, according to the rules of the formtext and the label-position and then sent to the output. (p.e. printer) r.M.: As l.M., but all selected labels are processed and distributed among the labels, (beginning with the selected one) in left-to- right and top-to-bottom order. If all labels are full, the next sheet is processed from the first label. 2.4.5) ReView l.M.: Switches to the alternate file. (p.e. from .dat to .off) r.M.: Display is scrolled to the activated entry. 2.4.6) Send Data is keyed in by butler, using the keyboard. After selecting Send, butler closes his window and the wait-symbol appears. Now you can switch to the program, where data should be imprinted and position the cursor correctly. To start off butler, the hotkey has to be pressed once. Pressing the hotkey a second time while butler is typing aborts the command. l.M.: The active entry is keyed in. r.M.: All selected entries are imprinted , using the block-number and the fix-lines (IF1 and IF2) 2.4.7) Sort Allows you to sort the entries of the database subsequently. If the contents of field 3 (lastname,index) are identical, field 2 is used. 2.4.8) Store The current state of all entries (selected/deselected) is saved to disk, that is you can quit butler completely without loosing your selections. After starting butler again, you can continue with your work at the point, where you called Store. 2.4.9) UseJokr Restricts the display to all entries with an index, that matches the joker in IF4 (in addition to the group-selections or the function in IF3). 2.4.10) F l.M.: Enables/disables fast-mode. r.M.: Used to initialise the printer. (Performs a pseudo-print). 2.4.11) C l.M.: Switches to the label-sheet editor. (see chapter 7) r.M.: Shows a requester with the current version and serial-number of the program. The version-number can also be displayed with the cli command "version", if you use KS2.0 or later. 3) Providing your own config file The config-file has to be in the current s: drawer and must have the name "butler.cfg", if no filename is given using the -c command when starting butler. (p.e. butler -c dh0:s/PrivatConfig.cfg). The config-file contains very important information for butler like the group-names, data-filenames and paths, hotkey, priority, and so on. Through the use of keywords, you can define everything to fit your demands. The following syntax is necessary for keywords to be recognized by butler: 1) Keywords must be written in capital-letters. 2) Every keyword must be followed by ´=´ and the appropriate arguments. Behind and in front of the ´=´ you can insert as many blanks as you like. 3) Keywords don´t have to begin at column 1, but all characters between ´=´ and end-of-line are taken as argument in most cases, so you should write your comments in front of the keyword or in a seperate line. 4) Keywords, that define the state of a switch (p.e. FASTMODE), take either ON or OFF (written in capital letters) as an argument. 5) Numeric values must be written in one,that is without any blanks (2 000). 6) Text is allowed to contain blanks and is taken from the first letter to the end of line, or as far as the text-length is valid. 4) Valid keywords for Butler.cfg ANDMODE: Defines ´&´-switch after starting of butler. AUTOINSERT: Activates the automatic insert function. (insert is called when is pressed in the last input-field (field 8, comments). This has no corresponding switch in the program and therefore can only be set by this keyword in the config-file. BAKDEVICE: Defines the device, at which an automatic backup of the current files (.dat and .off) should be made, if the device is found in the systems device-list. It has to be a real device (with : at the end), to be in that list, such as disk-names, drive-names or any logical device (created with assign).The backup is performed seperately for .dat and .off files and only those, where the archive-bit is not set, are backed up. If the procedure was successful, the archive-bit is set again. BLOCK: Defines the block-number to be used (IF2). DELAY: Changes the speed of the auto - scrolling (see chapter 1.3). The value defines a waiting-time after each new line (in 1/50 sec.). DEVICE: This defines the device (or drawer), where the data-files should be placed (or searched). If DEVICE is not defined, s: is used. DISPLAY: Defines, which groups (group-gadgets) are ON by default. You get this value by adding all 2^x (where x is a groupnumber from 0 to 7) of the required groups. (p.e. 2^0+2^3+2^7 for groups 1, 4, 8). FASTMODE: Defines the default-state of the ´F´-switch. FILENAME: Defines the basename of the data-files (--.dat, --.bak, --.off). p.e. FILENAME = Private --> using Private.dat and Private.off... FIXLINES: Initial value of IF1 (see chapter 2.1.2). FORMAT: Defines the way, butler types entries via the keyboard. You can use F1 to F8 for the 8 input-fields and RT for a . The symbols are seperated by ´,´ (p.e. FORMAT=F1,RT,F2,F3,RT,F6,RT). FORMDIR: Only for OS2.0-Users. Defines the default-drawer for formtexts. The asl-requester appears with this drawer, if a formtext has to be chosen. (see also PATTERN) FUNCTION: Default contents of the IF3, user-function (see chapter 2.1.4). GR1NAME: Behind the ´=´ stands the group-name , that is written into the - GR8NAME corresponding group-gadget (display). This text can only be 7 chars long and will be cut by butler, if more characters are used. Therefore, you should try to find good shortcuts, if the original text would not fit in the gadget. HANDLERPRI: Value for the priority of the inputhandler (scanning of hotkey). This should be between 52 and 60.If the hotkey is not recognized by butler, this value has to be further increased. HOTKEY: Defines the key-code of the required hotkey (see chapter 5). HOTQUAL: Here you can give the additional qualifiers for your hotkey. INITPRT: Lets butler initialise the printer twice, if set to ON. JOKER: Default-contents of IF4 (Joker). (see chapter 2.1.5) LEFTOFF: Tells butler, at which column of the page your printer begins to print (how many chars free space there are on the left side). ORMODE: Defines the default-state of the ´|´-switch. PATTERN: Only for OS2.0-Users.This is an AmigaDOS-pattern (#?.form) which is used by the asl-request that asks for a formtext, to restrict its file-display. SPEC: Defines the state of the 8 tiny group-gadgets below the input- fields. This value is calculated in the same way as for DISPLAY. TASKPRI: Defines the task-priority after pop-up (hotkey pressed). This value can range from -127 to 128, but should be around ±10, for too high values can cause deadlocks (-=> a hang-up of the whole system) and therefore are not recommended. A value of 1 or 2 is a good choice to get the best results. TOPOFF: Tells butler, at which line of a page your printer can begin to print (how many lines are left emty at the top of the page). USEFUNC: Defines the default-state of the UseFunc-switch. USEJOKR: Defines the default-state of the UseJokr-switch. WAITX: X-coordinate of the waiting-symbol on the screen (0-620). WAITY: Y-coordinate of the waiting-symbol on the screen (0-240/0-184). 5) Table of keycodes (Rawkey number for hotkey) To get a combination of several qualifiers, you have to ADD the single values together. p.e. r-Alt + r-Shift: 32+2 = 34. CAUTION: l-Alt+l-Amiga or r-Alt+r-Amiga may not function correctly, as this are combinations reserved by the system. The caps-lock qualifier is ignored by butler, so you don´t have to switch it off/on, everytime you call butler. Keycode | Qualifier ----------------+------------------------------- Help: 95 | l-Shift: 1 l-Amiga: 64 F1-F10: 80-89 | r-Shift: 2 r-Amiga: 128 Tab: 66 | l-Alt: 16 l-Mouse: 4096 Enter: 67 | r-Alt: 32 r-Mouse: 8192 Esc: 69 | Ctrl: 8 m-Mouse: 16384 ----------------+------------------------------- 6) Using formtexts The formtext must be a raw ASCII-text (no IFF-format with informations about font, style ect.) to be processed correctly by butler. If you need to have text-passages underlined, bold, italics or printed with another pitch, you can either insert the appropriate ANSI-sequences directly in the formtext (a list of the ANSI-commands can be found in the AmigaDOS-Manual), or you redirect the output to a file (select a filename in the output - requester instead of PRT:) and import this into your favorite layout-program later. Syntax of the form-commands: where x is a number between 1 and 8 Stands for the contents of the input-field x, which is substituted in insert mode. The 4 characters of the command are deleted and the text of the input- field is inserted instead. where x is a number between 1 and 8 Stands for the contents of the input-field x, which is substituted in over- write mode. The 4 characters of the command and all following chars are overwritten by the contents of the input-field. If there are less than 4 chars available, the rest of the command-chars are overwritten with blanks, so that the line keeps its original length. where x betw. 1 and 8 y is a joker-text (G*mbH*) z is the text to be inserted. The text z is inserted, if the contents of field x matches the joker y. If y is left out (p.e. ) only an empty field x matches. If only an asterix is given (p.e. ), everything but an empty field is sufficient. The text to be inserted (z) is allowed to contain any chars, so you can even insert a linefeed () or ANSI-commands depending on the contents of field x. The text z is inserted the same way as with . Formtexts are also used in conjunction with the lable-print function, where they determine the text to be printed on the labels. This formtexts are not allowed to contain ANY control-characters (that are not printed out later), such as ANSI-sequences, as they garble the calculating of columns. As an effect, the labels are not printed correctly, because the calculated columns don´t match the real ones. Formtexts, that are not used for label-print are allowed to contain control-characters without limitations. 7) Label-Sheets To be able to print data onto labels, the size and position of each label of the page must be defined. The arrangement of the labels and the management of the allready defined pages is done in a seperate window. Pages can be created, deleted, loaded, saved, and the pitch and linespace can be defined. For the smallest pitch (fine), there are two possibilities: 15 or 16.66 cpi. You have to select the pitch, your printer uses for fine-print. Usually this is 15 cpi on a matrix- and 16.66 cpi on a laser- or inkjet-printer. This can be found in your printer-manual, or you can test it empirical: If you get a horizontal shifting, select the other pitch. 7.1) Sheet management 7.1.1) + / - Leaf through the defined pages. l.M.: Next page r.M.: Previous page. 7.1.2) Lpi/Pit l.M.: Changes linespace (1/6" or 1/8"). r.M.: Changes pitch (10, 12, 15 or 16.66 cpi). 7.1.3) Name Input-field for the Name of the current page. Newly created pages get the name "New Sheet".Caution: Always press when you are done with typing the new name, to let the system recognize the changes. To keep the new name select save (7.1.5). 7.1.4) New/Del l.M.: Creates a new page. r.M.: Deletes the current page from the list of defined pages. 7.1.5) Save l.M.: Saves the current definitions in Butler.labels. r.M.: Removes the current definitions and reloads the last saved. 7.1.6) Use Return to main-window. 7.1.7) -Wait- Must be set on,if this page has to be fed manually. In this case, butler waits after each page until you (and the printer) are ready to go and the hotkey is pressed. If the page can be fed automatically by the printer (A4, Letter ect.), you should leave this switch off. 7.2) Label management When arranging labels , the current screen-coordinates and the column / line are displayed. If useful, the width and height of the current label are also shown. This makes it easy to select the correct dimension of the labels. 7.2.1) Moving labels Press the l.M. inside the label you want to move,hold down the button and move it to the new position. 7.2.2) Clone a label Press the r.M. inside the label you want to clone, hold down the r.M. and move the new copy of the label to its place. 7.2.3) DelLab Deletes a label. After selecting DelLab, klick with the crosshair inside the label you want to delete. 7.2.4) NewLab Create a new Label: *) Select NewLab with l.M. *) Move crosshair to the upper-lefthand corner. *) Hold down l.M. and stretch box as needed, then release button. 7.2.5) SizeLab Adjusting width and height of a label: *) Select SizeLab with l.M. *) Hold down l.M. inside the label you want to change and move cursor to adjust width and height, then release button. 7.2.6) Grid Creates a stencil for the design of symetrical label-sheets. *) Select Grid with l.M. *) As in 7.2.4) NewLab, but the whole page is filled out with boxes. *) The grid remains until you select Grid with the r.M. or you create a new stencil (l.M.). 8) Registration If you like the program and use it frequently you should register, to obtain a complete version and your private serial-number. Just send me your adress and about $20 US (or something in your own currency) to: Christoph ZENS Carabelligasse 5/91 1210 W i e n AUSTRIA In return you´ll get a disk with the latest software, containing your serial number and no more limits (like the maximum of 64 entries). You will also be informed about later software - updates , to take full advantage of the registration. Though you are allowed to copy the registered version for your friends, the update-service keeps bounded to your adress that is, updates with your serial-number are only sent to you. If you have ideas, how to make the program even better or you don´t want to register because some important features are missing, write to the same adress. I will take it over in the next program-version,if possible. A real 2.0-Version with that fancy 3D-Look and other 2.0-advantages (written as a commodity) and much less program-code as a side-effect is coming up soon.