home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 3 Comm / 03-Comm.zip / tlcadr03.zip / address.doc next >
Text File  |  1996-01-26  |  11KB  |  230 lines
  1.  
  2.  
  3. Description:    (Address.Exe - v 1.07 - built 1/1/96 (TLCADR03.ZIP))
  4.  
  5.     This program maintains up to 300, 60 byte address lines (actually
  6.     they could be any group of text lines you need to copy and paste
  7.     often!) in a plain ASCII text file.  The text file can be one you
  8.     started, or have maintained manually, with an editor.  --[More about
  9.     the file's format, later]--  It's name is (arbitrarily) ADDRESS.DAT
  10.     and it resides in the directory from which you launch ADDRESS.EXE.
  11.     If such a file does not exist, the first time you execute the
  12.     program, an empty one will be created.
  13.  
  14.     The first time you execute the program it will position itself at
  15.     the upper right-hand corner of the screen.  You can move it from
  16.     there if you wish.  If you move the window, the program will
  17.     remember where you positioned it and will return to that position
  18.     for future executions.  The guts of the program are controlled via a
  19.     dialog box that pops up when you double click on the client window
  20.     with mouse button #1.
  21.  
  22.  
  23. Installation:
  24.  
  25.     Unzip the file (oh, you already did that or you wouldn't be reading
  26.     this).  Copy Address.EXE and Address.ICO to any directory you
  27.     choose. It doesn't care where you put it.
  28.  
  29.  
  30. Execution:
  31.  
  32.     Type [  Start /f {d:\path\}Address.Exe  ]  at any command line, or
  33.     create a desktop program object to start the program.  The '{}'
  34.     indicate that the drive and path are optional depending on where you
  35.     put the program, what's in your path statement and what the current
  36.     drive and directory are when you issue the 'Start' command.
  37.  
  38.     The program will create a file named 'ADDRESS.DAT' in the same
  39.     directory you executed it from, unless a file of that name already
  40.     exists.  It will also create a file named ADDRTLC.INI, in the same
  41.     directory.  This file holds any setup instructions the program
  42.     needs, like where the window is to be presented.  When you double
  43.     click the client area of the program's window, a dialog box will pop
  44.     up.  It has a drop-down combo- box, 7 push-buttons, 3 radio-buttons,
  45.     2 edit fields and an automatically updated use count field in it.
  46.  
  47.     Let's start by putting a new line into the file.  Just type the name
  48.     into the combo-box's edit line and press the Add button.  The line
  49.     will be added to the combo-box and written immediately to the file.
  50.  
  51.     If the name was in the clipboard (you copied it from some other
  52.     program) just press Shft+Ins or press the Paste button and the line
  53.     is pasted into the edit line. 
  54.  
  55.     You will notice, at the bottom of the dialog, an edit field labeled
  56.     "Name" and another labeled "Comment".  These fields are directly
  57.     linked with the line in the combo-box's edit field (BUT, only if
  58.     that line is actually in the file).  They may be directly edited at
  59.     any time and the changes will be saved in ADDRESS.DAT. However,
  60.     these changes are not saved in the file immediately.  They are saved
  61.     with the next Add or Delete, or when the program is ended.
  62.  
  63.     You'll notice that as you scroll, vertically, thru the combo-box,
  64.     these fields will change showing the values associated with each
  65.     address.
  66.  
  67.     If you type a new entry into the combo-box's edit field, enter text
  68.     into the Name and/or Comment field and then scroll thru the
  69.     combo-box BEFORE you have Added the entry, what was in Name and/or
  70.     Comment is lost!  However, you may enter Address, Name and Text and
  71.     then press the Add button.  In this case, all three are added at
  72.     once.
  73.  
  74.     To delete a line from the list, select the line from the drop-down
  75.     list so that it's in the edit line, and press the Delete button.  It
  76.     is deleted from the list and the file, immediately, but is left in
  77.     the edit line, just in case you made a mistake and want to re-add
  78.     it!
  79.  
  80.     To change a line, select it, do a Delete, change the edit field, and
  81.     do an Add.  You may want to do this in reverse sequence, if you
  82.     worry that something could get lost through a finger-fault<g>.  Just
  83.     remember that the value in the combo-box's edit field is treated
  84.     just like the key field in a database.  All the other fields are
  85.     dependent on the key.
  86.  
  87.     To select a line to be pasted into another program, select the line
  88.     from the drop-down list and press the Copy button.  A copy will be
  89.     put in the clipboard and the dialog is dismissed.  You will notice a
  90.     heavier border around the Copy button, indicating that it is the
  91.     default.  When you press the Enter key, the Copy button is pressed
  92.     automatically.  Also, you don't have to open the drop-down list.
  93.     You can use the Up and Down arrows to scroll the list thru the edit
  94.     line.
  95.  
  96.     The Cancel button dismisses the dialog without making any changes to
  97.     the list, file or clipboard.  HOWEVER, it is not an Undo button. If
  98.     you have made previous changes, they remain made.
  99.  
  100.     The radio buttons (Name, Address and Count), in the 'Sorted by'
  101.     group box, immediately control the sequence in which the addresses
  102.     are presented in the combo-box. When you click one of the buttons,
  103.     the program first remembers which record was displayed in the
  104.     combo-box edit line and then sorts and reloads the combo-box's
  105.     dropdown list.  It DOES NOT rewrite the file with the new sequence.
  106.     That will be done when the program ends, to avoid additional
  107.     overhead.  Finally, it redisplays the original record in the
  108.     combo-box's edit line, so that even though the sequence has been
  109.     changed, you are still positioned on the same record. 
  110.  
  111.     There is a slight twist to the sorting in Name and Count sequences.
  112.     I hope this is acceptable to you<g>.  In Name sequence sorting, the
  113.     records are also sorted, secondarily, in Address sequence.  Thus, if
  114.     a record has no Name field, or if two records have the same Name
  115.     field value, they are ordered by Address.  In Count sequence
  116.     sorting, the records are sorted in reverse Count value (largest
  117.     number, first) then in Name and finally in Address sequence.
  118.  
  119.     The program opens, processes and closes the file for each change
  120.     made. It does not lock the file 'Open'.  So, you can make changes to
  121.     the file with an external editor, if you want, while the program is
  122.     executing.  To make those changes current, open the dialog and press
  123.     the Refresh button.  The program will flush the list, open the file,
  124.     re-build the list and close the file.
  125.  
  126.     A side benefit, in some circumstances, of the Refresh button, is the
  127.     ability to recover from changes made to the Name or Comment fields
  128.     before they have been physically saved to the file.  Another subtle
  129.     "save yourself" will be discussed under the Merge button topic<g>.
  130.  
  131.     As a (partial) safeguard to data loss, any time the program rewrites
  132.     the file, it follows these steps:
  133.  
  134.         Write the new file, named ADDRESS.TMP
  135.         Delete a file named ADDRESS.BAK
  136.         Rename ADDRESS.DAT to ADDRESS.BAK
  137.         Rename ADDRESS.TMP to ADDRESS.DAT
  138.  
  139.     If you should get a sudden 'black-spot' in power while all this is
  140.     occurring, when you finally get back alive, there should be at least
  141.     one of these files remaining!  So, you have some chance of getting
  142.     back alive with as little loss as possible.  Also, you normally have
  143.     the current copy of the file and one backup copy.
  144.  
  145.     A final nicety; since the drop-down list is maintained in sequence,
  146.     the first time you make a change to the list, your file will be
  147.     re-created in sequence.  So, if you have an existing file, in random
  148.     sequence, it will wind up in sequence the first time you make a
  149.     change!
  150.  
  151.     The Merge button pops up a filename dialog, lets you select a
  152.     filename and merges all non-duplicates from that input file into the
  153.     current list.  It then updates the ADDRESS.DAT file, using the same
  154.     write method outlined above.  This gives you an easy way to keep two
  155.     address files (like at home and at work) in synchronization.
  156.  
  157.     If you should accidentally delete a record from the file (and
  158.     immediately realize what you did<g>), you can "Merge" the
  159.     ADDRESS.BAK file back into the current file.  That will restore the
  160.     deleted record! 
  161.  
  162.  
  163. Window position remembering:
  164.  
  165.     The .INI file is only updated when the program is closed (you close
  166.     it, or shut the system down while the program is active). However,
  167.     that introduces a problem if the window is minimized when the
  168.     program is closed.
  169.  
  170.     So, it remembers where the window was positioned the last time it
  171.     was 'painted' before it was minimized.  'Painting' only occurs when
  172.     some portion of the window was 'covered' and is now 'uncovered', not
  173.     when it's 'on top' and you move it.  To make a long story short, if
  174.     you put the window in a new place, be sure to close the program with
  175.     the window visible, not minimized.  That way, it can remember
  176.     exactly where it was.
  177.  
  178.  
  179. File Format:
  180.  
  181.     The Address.Dat file is a plain ASCII text file that you can change
  182.     or create with any text editor.  Each line in the file is a record.
  183.     The fields are positional, variable in length and separated with a
  184.     single tilde (~) character.  Missing/vacant fields are held by a
  185.     single blank.  The fields' positions are:
  186.  
  187.         1. Address
  188.         2. Name
  189.         3. Comment
  190.         4. Count
  191.  
  192.     Following are some examples:
  193.  
  194.         zeichick@acm.org~Alan Zeichick~OS/2 Magazine Editor-in-Chief~1
  195.         Iain Allen~Iain Allen~ ~2
  196.         aimgames@xmission.com~ ~ ~0
  197.  
  198.     Notice how missing fields are treated.  If you create/change a file
  199.     incorrectly with an editor, the program will attempt to use every
  200.     record.  However, fields following the Address may not be
  201.     interpreted correctly.  Each of the first three fields can be up to
  202.     60 characters long. 
  203.  
  204.  
  205. Cost:
  206.  
  207.     This program is Freeware.  It is 32-bit, thus requires OS/2 2.0+. It
  208.     was created with CASE:PM and the IBM C Set++ compiler and Toolset
  209.     (it's a tiny bit smaller than the previous version, a plug for
  210.     the optimization ability of C Set++ <g>).
  211.  
  212.     Please try it, pass it along to your friends and upload it to your
  213.     favorite BBS.  Its predecessors have traveled all around the globe
  214.     and I hope this iteration will, as well.
  215.  
  216.     If you like it, or even if you don't, drop me a note at one of the
  217.     following addresses to let me know. I love mail.  Who knows, if you
  218.     have a suggestion, I may even change the program, yet again!
  219.  
  220.  
  221.     US Mail:                    Tom Carr
  222.                                 5403 Pearce Way
  223.                                 Crestwood, KY  40014
  224.  
  225.     ILink OS/2 conference:      Tom Carr
  226.  
  227.     Internet:                   tom.carr@tfd.org
  228.  
  229.  
  230.