home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / windows / addrbk.zip / AB_DOC.DCM next >
Text File  |  1990-04-10  |  24KB  |  449 lines
  1. This document describes the design and operation of the DynaComm "Address 
  2. Book" script for managing VAX Mail addresses.
  3.  
  4. Introduction
  5. ------------- 
  6. Electronic mail can be a very powerful communications tool for corporate PC, 
  7. minicomputer and mainframe computer users.  Unfortunately, a lot of the 
  8. popular mini- and mainframe-based E-Mail systems are user-hostile when it 
  9. comes to assisting with mundane chores like addressing messages to other users 
  10. with arcane "nodename::username" codes.    DEC's VAX Mail is a classic 
  11. example: to locate another person's VAX Mail address, users are required to 
  12. exit VAX Mail, access DEC's "ECD Find" address database program, input the 
  13. name of their addressee, write down the address when (and if) it appears on 
  14. the screen, exit ECD Find, re-enter MAIL and then transcribe the address at 
  15. the VAXMail "To:" prompt.
  16.  
  17. DEC has made some attempt to provide better addressing functionality in their 
  18. office automation software (All-in-One), but this solution is very costly 
  19. (additional licensing fees for the All-in-One software and additional VAX CPU 
  20. power to drive the resource-hungry All-in-One menu interface) and it still 
  21. lacks basic functionality (eg, the user can't save frequently-used addresses 
  22. for quick entry; he must still enter the user's last name, invoke an E-Mail 
  23. address database search with an arcane keystroke combination, and type a 
  24. number corresponding to the match that appears in a list on the screen.)
  25.  
  26. I have written a DynaComm script which solves this problem and gives VAXMail a 
  27. much friendlier face.  This document describes the DynaComm "Address Book" and 
  28. explains how to use it.
  29.  
  30.  
  31. What The Address Book Does
  32. -------------------------- 
  33. The DynaComm "Address Book" provides the following capabilities: 
  34.  
  35. o    automatic ECD lookup of VAX MAIL addresses (Local or Corporate) based on 
  36.      the entry of the addressee's last name and, optionally, any part of their 
  37.      first name 
  38.  
  39. o    point-and-shoot selection of ECD matches and one-button copying to an      
  40.      on-screen "Send to:" list
  41.  
  42. o    an on-screen address list, arranged alphabetically by last name, for      
  43.      recall of frequently-used addresses; each name in the list has an           
  44.      associated address which can be copied to the "Send to" list with a      
  45.      single mouse click 
  46.  
  47. o    the ability to copy ECD matches to the address book list with a single      
  48.      mouse click 
  49.  
  50. o    the ability to enter names and addresses in the Address Book manually (if 
  51.      you already know them and don't want to look them up) 
  52.  
  53. o    the ability to enter VAX distribution list names and descriptions in the 
  54.      Address Book manually (if they already exist on the VAX and you don't      
  55.      want to recreate them) 
  56.  
  57. o    the ability to save a "Send to" list to a file and automatically upload      
  58.      it to the VAX for future use as a .DIS file; a description of the list      
  59.      and the name of VAX .DIS file are automatically copied to the Address      
  60.      Book for future reference 
  61.  
  62. o    automatic copying of the "Send to" list to the VAX Mail "To:" prompt upon 
  63.      exit from the Address Book 
  64.  
  65.  
  66.  
  67.                HOW TO INSTALL THE DYNACOMM ADDRESS BOOK SCRIPT
  68.                ===============================================
  69.  
  70.  
  71. Where to put the files
  72. ---------------------- 
  73. The zip package you downloaded contains two DynaComm files: ADD_BOOK.DCP (the 
  74. script source file) and ADD_BOOK.DCM (the address book "database" file).  For 
  75. proper script operation, these files need to be placed, respectively, into the 
  76. "script" and "memo" subdirectories defined in the [DYNACOMM] section of your 
  77. WIN.INI file.
  78.  
  79. Editing the Script Source file (ADD_BOOK.DCP)
  80. ---------------------------------------------
  81. The Address Book script source file is named ADD_BOOK.DCP.  Before compiling 
  82. it for use, you will probably need to change several hard disk path 
  83. references.  These references tell the script where to find (and save) the 
  84. Address Book database file ADD_BOOK.DCM.  The path *must* match the location 
  85. of the ADD_BOOK.DCP file in order for the script to fill the address book 
  86. table.
  87.  
  88. It is recommended that you use the DynaComm script editor to open ADD_BOOK.DCP 
  89. and perform a global "search and replace" to replace 
  90.  
  91.  "C:\WIN386\DYNACOMM\MEMOS"    with your "Memo" pathname.
  92.  
  93.  
  94. Compiling the Script Source file (ADD_BOOK.DCP)
  95. -----------------------------------------------
  96. Once the path references have been corrected, save and compile the script 
  97. using the "Script" "Compile..." menuitem.  The script compiler will create 
  98. ADD_BOOK.DCT and place it in your "Script" path.  At this point, the script is 
  99. ready for use.
  100.  
  101.  
  102.               HOW TO RUN THE ADDRESS BOOK SCRIPT WITHOUT A VAX!
  103.               =================================================
  104.  
  105. This script is written for use with "VAX Mail" on a DEC VAX minicomputer.  
  106. With a few minor modifications, the script can probably be adapted to other 
  107. mini- and mainframe-based Electronic Mail systems that lack an "address book" 
  108. type feature.  
  109.  
  110. If you would like to *see* the main Address Book dialog box to help you decide 
  111. if this script would be useful to you, (eg, before you attempt to use it in a 
  112. live VAX Mail session), follow these directions.
  113.  
  114. 1) Copy the files, change the path and compile the script as described above. 
  115.  
  116. 2) Access the DynaComm "Settings" menu and define a new "Function Key" called 
  117.    "Test".  
  118.  
  119. 3) In the "Command" editbox adjacent to the "Test" function key label, enter      
  120.    this string:
  121.  
  122.    ^$e"add_book*start"
  123.  
  124. 4) Click the "Ok" button in the Function Key dialog box to close it.
  125.  
  126. 5) Click the newly-defined "Test" button below DynaComm's terminal window.  
  127.    (This assumes you have used the "Window Show Function Keys" menuitem and
  128.    that the function keys are visible!)  This will launch the script at the      
  129.    "Start" label in the *middle* of the script file.  This effectively           
  130.    bypasses the first part of the script which is designed to converse with
  131.    your VAX, access VAX Mail and leave your session at the "MAIL>" prompt. 
  132.  
  133.    The main Address Book dialog box will then be displayed and you can
  134.    interact with the Address Book entries to get a feel for how the interface
  135.    works.
  136.  
  137. 6) To leave the dialog, simply click the "Cancel" button.  
  138.  
  139.  
  140.                  USING THE ADDRESS BOOK SCRIPT WITH VAX MAIL
  141.                  ===========================================
  142.  
  143.  
  144. Executing the Script
  145. --------------------
  146. To use the Address Book script, you need only to "Execute" it from inside a 
  147. "live" VAX session (ie, at the DCL prompt, usually "$").  Script execution can 
  148. be performed in one of two ways: 1) by using the "Script Execute" menuitem or 
  149. 2) by assigning the script to one of DynaComm's "function buttons" and then 
  150. activating the button.
  151.  
  152. The Address Book script is probably best accessed via a function button at the 
  153. bottom of DynaComm's terminal window.  To program the button, access the 
  154. "Settings..." "Function Keys" menuitem, enter the words "Address Book" in any 
  155. unused F-key "Key Name" area and enter ^$E"ADD_BOOK.DCT" in the corresponding 
  156. "Command" box.  (If you want to make this key assignment permanent, save the 
  157. DynaComm settings (.DCS) file you use for VAX access after making the entry.) 
  158.  
  159.  
  160. When to use the Address Book script
  161. -----------------------------------
  162. When you need to send a MAIL message and want some help with addressing, you 
  163. simply execute the script.  It doesn't matter where you are in a VAX session 
  164. (the DCL ("$") prompt, the MAIL> prompt, the To: prompt, the Subj: prompt, 
  165. etc.), because the script includes a routine to "move" your session to the 
  166. MAIL> prompt without taking you out of an open MAIL session.  
  167.  
  168. When accessed, the script "hides" your VAX terminal window and displays a 
  169. dialog box in the middle of your screen.
  170.  
  171. The "Address Book" Dialog Box
  172. -----------------------------
  173. There are four major components of the DynaComm Address Book dialog: an 
  174. "Address Book Entries" listbox in the upper left corner of the dialog; a "Send 
  175. Message to:" listbox in the upper right corner of the dialog; a group of five 
  176. "action" buttons between the listboxes; and an ECD Find toolbox in the bottom 
  177. half of the dialog.  The use of each component is explained below.
  178.  
  179.  
  180. Using the "Address Book Entries" Listbox
  181. ---------------------------------------- 
  182. This listbox contains all the names and MAIL addresses the user has chosen to 
  183. "store" since the installation of the Address Book script.  To use the list, 
  184. one simply points to the name of the person to whom he wishes to address a 
  185. message and either double-clicks the mouse on it or clicks once on it and 
  186. activates the "Add" button (either with a mouse click or by depressing Alt-A).  
  187. This will cause the VAX Mail address associated with the person's name to be 
  188. "copied" to the "Send Message to:" list.  Additional addresses can be copied 
  189. to the "Send to:" list by repeating this process.
  190.  
  191. If the name of the person is not currently visible in the list box, the user 
  192. can use the vertical scroll bar to review all the names in the Address Book.  
  193. Alternatively, the user can highlight any name in the list and then press the 
  194. letter key corresponding to the desired addressee's last name (eg, "S" for 
  195. Singleton) or use PageUp and PageDn or the up and down arrow keys. 
  196.  
  197. Distribution list names may also be accessed from the Address Book.  These 
  198. will always appear in alphabetical order at the end of the personal entries.  
  199. Distribution list entries can be distinguished by the square brackets on 
  200. either side of the Distribution list name.  When copied, the Address Book 
  201. script appends the "@" character in front of the name to advise the VAX that 
  202. the entry is a stored distribution list file, not an individual's address.
  203.  
  204. Names and addresses are added to the "Address Book" using one of several 
  205. methods described below.  When an entry is added, the script automatically 
  206. re-sorts the list alphabetically by last name and saves the sorted file to 
  207. disk.
  208.  
  209. ***To delete an entry from the Address Book, simply highlight the unwanted 
  210. entry in the listbox then invoke the "Alt-Minus Sign" key combination.*** 
  211. (Note: I have purposely not defined a "Delete" button to prevent accidental 
  212. erasure of Address Book entries.  If you wish to display such a button, open 
  213. the script source file, insert width and height coordinates for the "Delete" 
  214. button in the DIALOG DEFINITION section, save and recompile.)
  215.  
  216.  
  217. Using the "Send Message to:" Listbox 
  218. -------------------------------------
  219. The "Send Message to:" listbox contains the VAX Mail addresses of all the 
  220. people (and distribution lists) to whom the user has chosen to send his 
  221. message.  This listbox is really a passive element of the Address Book dialog 
  222. since the user doesn't have to "do" anything with the entries there.  The only 
  223. control which the user may activate is the vertical scroll bar (to review more 
  224. than nine addresses in the listbox).  As with all other Windows listboxes, 
  225. either the mouse or the direction keys may be used to invoke scrolling.
  226.  
  227. Entries in this listbox are made by copying from either the Address Book 
  228. listbox (discussed above) or the ECD Match listbox (discussed below). 
  229.  
  230. To clear all entries from the listbox, simply click on the "Clear" button to 
  231. the left of the box or use the Alt-L key combination.
  232.  
  233. When the "Send to" list is complete, the user simply clicks the "Ok" button 
  234. (or presses Alt-O).  The dialog will then disappear and be replaced by the VAX 
  235. terminal screen.  The script will automatically enter the "Send" command and 
  236. copy the addresses to MAIL when the "To:" prompt appears.  At this point, the 
  237. script stops and the user is free to complete the message-sending process. 
  238.  
  239.  
  240. Using the Action Buttons
  241. ------------------------ 
  242. Add:    Copies the address corresponding to the currently selected Address Book 
  243. name to the "Send Message to:" listbox
  244.  
  245. Ok:    Returns the VAX terminal window to the screen and copies the contents of 
  246. the "Send to" listbox to the VAX Mail "To:" prompt. 
  247.  
  248. Clear:    Clears all user-fillable dialog elements ("Send to" listbox, ECD 
  249. Match listbox, Name and Address edittext boxes) and any error message that 
  250. appears above the "Copy to Address Book" button in the ECD Find toolbox.
  251.  
  252. Save List:    Enables the user to save the entries in the "Send to" listbox 
  253. as a VAX Mail distribution list (*.DIS) file.  See the "Saving Distribution 
  254. Lists" section below. 
  255.  
  256. Cancel:    Cancels script execution, redisplays the VAX terminal window and 
  257. leaves the user at the "MAIL>" prompt.
  258.  
  259.  
  260. Using the "ECD Find" Toolbox 
  261. ----------------------------
  262.  
  263. ***"ECDFIND" is a VAX utility program supplied by DEC with VAXMail.  This 
  264. stand-alone program enables users to search a database file for electronic 
  265. mail addresses by entering an addressee's name.  ECDFIND *must* be resident on 
  266. your VAX in order for this script to work.***
  267.  
  268. The ECD Find toolbox enables the user to access his LOCAL and Corporate ECD 
  269. (Electronic Corporate Directory) databases and copy selected ECD matches to 
  270. either the "Send to" listbox or the "Address Book" listbox.  The toolbox also 
  271. permits the user to manually enter Names and Addresses (or Distribution List 
  272. names) and copy them to the "Address Book" or "Send to:" listboxes. 
  273.  
  274. To access ECD, the user simply clicks the mouse cursor inside the "Last Name:" 
  275. edit box, types the last name for which to search and clicks the "Search 
  276. Database" button at the bottom of the dialog.  This will invoke an invisible 
  277. LOCAL search (the default database) for the last name entered and cause the 
  278. message "Searching ECD Database..." to appear below the "Address:" label in 
  279. the toolbox.  After a short period of time, a list of all names matching the 
  280. entered criteria  (with corresponding addresses) will be displayed in the "ECD 
  281. Matches" listbox.  The user may then highlight a listbox item with the mouse 
  282. cursor and copy it to either the "Send to" listbox or the "Address Book" 
  283. listbox using the corresponding buttons at the bottom of the dialog.  If the 
  284. desired address is not displayed in the listbox, the user may scroll it as he 
  285. does the other listboxes to find it. 
  286.  
  287. Searches may be narrowed by entering any part of the search target's first 
  288. name in the "First Name:" edit box prior to the initiation of a database 
  289. search. 
  290.  
  291. Searches of the corporate ECD database may be invoked by clicking on the 
  292. "Corporate Search" radio button below the ECD Match listbox, then clicking the 
  293. "Search Database" button. 
  294.  
  295. If no matches are found in the ECD database, the script will beep and display 
  296. the message "No matches found!" in the message area of the dialog.
  297.  
  298. Note that the user must highlight the match he wishes to copy before using 
  299. either of the "Copy" buttons. Failure to do so will cause an appropriate 
  300. message to appear in the message area of the dialog. 
  301.  
  302. Activation of the "Copy to Send List" button will cause the address of the 
  303. selected listbox match to be copied to the "Send to" listbox.  Activation of 
  304. the "Copy to Address Book" button will cause both the name and address to be 
  305. copied to the Address Book list.  The script will then automatically re-sort 
  306. the list alphabetically and save it to disk for future use.  (The user can 
  307. easily check the new Address Book entry by highlighting it with the mouse and 
  308. clicking on the "Add" button.) 
  309.  
  310.  
  311. Manual Entries
  312. -------------- 
  313. If the user already knows an address that he wants to place in the "Send to:" 
  314. listbox, he may simply type it in the "Address" edit box and click on the 
  315. "Copy to Send List" button.  No ECD Matches need be displayed to permit this 
  316. action. 
  317.  
  318. Similarly, if the user already knows a name and address that he wants to place 
  319. in the Address Book, he may type first and last names and the address in the 
  320. corresponding edit boxes and click on the "Copy to Address Book" button.  The 
  321. entry will automatically be converted to all upper case letters and placed in 
  322. alphabetical order in the list box. 
  323.  
  324. This entry method applies to stored distribution lists as well.  For example, 
  325. if the user already has a file called MYGROUP.DIS stored on the VAX, he may 
  326. enter @MYGROUP.DIS in the "Address:" edit box and copy it to the "Send to:" 
  327. listbox by clicking on the "Copy to Send List" button.  Likewise, the user can 
  328. store a distribution list entry in the Address Book by entering a description 
  329. of the file in the "Last Name:" edit box, and then entering the name of the 
  330. .DIS file in the "Address" edit box.  For the MYGROUP.DIS example, the user 
  331. would enter an appropriate descriptor like "My Work Group" in the Last Name 
  332. box and then enter MYGROUP.DIS in the address box.  [Note: The .DIS filename 
  333. extension must be included in the Address edit box in order for the script to 
  334. recognize the entry as a distribution list.]
  335.  
  336. Caution:  Since the DynaComm script currently has no way to know if a manually 
  337. -entered.DIS file exists on the VAX, the user must ensure that manual entries 
  338. are made correctly.  Mistakes will generate a VAX Mail error message when the 
  339. user clicks the "Ok" button to return to the terminal window. 
  340.  
  341. Saving "Send to:" Lists as VAX Distribution List files 
  342. ------------------------------------------------------
  343. If a user wants to save a list of addresses as a VAX distribution list file, 
  344. he simply copies all the addresses to the "Send to:" listbox then clicks the 
  345. "Save List..." button.  The Address Book dialog box will then be replaced by a 
  346. new dialog box requesting a (VAX) filename and a filename descriptor.
  347.  
  348. To save the list, the user must provide an 8 character (or less) filename in 
  349. the first edit box and then provide an 18 character (or less) description of 
  350. the filename in the second edit box.  Failure to make either entry will result 
  351. in the display of error messages below the two buttons in the dialog. 
  352.  
  353. When both entries have been made, the user clicks the "Ok" button.  The script 
  354. will then save the list to the PC's hard disk and automatically upload it to 
  355. the VAX.  A message to this effect will appear immediately below the two 
  356. buttons in the listbox.  When the upload is complete, the Address Book dialog 
  357. will return with the new information.  Note that the original list of 
  358. addressees in the "Send to:" list will be replaced by the name of the .DIS 
  359. file just uploaded and that the Address Book will contain the name of the new 
  360. distribution list.  To use the list in future messages, the user need only 
  361. select it from the Address Book and "Add" it to the "Send to:" list. 
  362. If the user does not wish to save the distribution list after entering the 
  363. "Save List..." dialog, he simply clicks the "Cancel" button to return to the 
  364. Address Book dialog.
  365.  
  366.  
  367. Assumptions Made by the Script
  368. ------------------------------
  369. The Address Book script *assumes*:
  370.  
  371.      - the user's VAX system permits the use of the SPAWN command from
  372.        within the VAXMail program (some VAX sysops disable this capability).
  373.        If the SPAWN command is *not* available, the script must be modified to 
  374.        EXIT VAXMail before performing the ECDFIND searches.  [Note: the
  375.        SPAWN command enables the user to perform ECD searches *while* in his      
  376.        *current* VAXMail session.  In this way, messages filed to the           
  377.        WASTEBASKET folder (by deleting them) are still accessible.  Otherwise,
  378.        the WASTEBASKET will be emptied upon exit from a VAXMail session.]
  379.  
  380.      - the user has the ECDFIND electronic mail directory database program
  381.        installed on his VAX.
  382.  
  383.       
  384. Comments about the Address Book Database File
  385. ---------------------------------------------
  386. ADD_BOOK.DCM is simply an ASCII text file which contains a column of users 
  387. (alphabetized by last name) and a corresponding column of addresses (eg, 
  388. nodename::username).  There is nothing remarkable about this file *except* 
  389. that it contains a tab stop set at column position 20.  This tab stop is vital 
  390. to the proper functioning of the "Address Book Entries" Listbox table.  
  391.  
  392. If you choose to edit this file using the DynaComm Memo editor, you must "Edit 
  393. Select All" all of the text, then "Edit Set Tab Width" to 20 and uncheck 
  394. "Expand Tabs" to reset the tab position before editting.  If you fail to do 
  395. this, DynaComm will replace the tab characters with spaces (hence the term 
  396. "expand tabs") and royally muck up the ability of the file to be used as a 
  397. "table" by DynaComm.
  398.  
  399.  
  400. Nifty DynaComm Features employed by this script
  401. -----------------------------------------------
  402.  
  403. 1) Without DynaComm's powerful "TABLE" functions, this script would NOT be 
  404. possible.  All three listboxes in the Address Book dialog box are DynaComm 
  405. tables.  Equally important to the script is DynaComm's ability to 
  406. automatically re-sort an updated address list by using the TABLE SORT 
  407. ASCENDING command and its ability to store a changed address listing to disk 
  408. using the TABLE SAVE command.  The TABLE COPY command also makes it possible 
  409. to delete entries from the listbox!  
  410.  
  411. 2) The entries in the "ECD Matches" listbox are "grabbed" by using the RECORD 
  412. FORMAT and TABLE SCAN commands to "mask and copy" certain portions of data as 
  413. it appears in the terminal window.  The TABLE SCAN command is a great tool 
  414. for automating the capture of "organized" data from any terminal session.  
  415. Also, because you can CLEAR the terminal window after each TABLE SCAN command, 
  416. you can *guarantee* the position of scrolled entries on the screen.  
  417.  
  418. 3) The ability to "hide" the Terminal window enables the ECD Search process to 
  419. be conducted in a totally invisible fashion so the user is not distracted by 
  420. the proceedings.
  421.  
  422. 4) DynaComm's script language enables the script writer to "update" previously 
  423. defined dialog boxes with new information *without* destroying the original 
  424. dialog box.  [This is in contrast with Excel's dialog boxes which *cannot* be 
  425. updated without first destroying them and then recreating them.]  All of the 
  426. error messages are placed in the dialog using DIALOG UPDATE MESSAGE... 
  427. commands.  Also, the display of information in the "ECD Matches" listbox is 
  428. performed with a DIALOG UPDATE LISTBOX TABLE command.
  429.  
  430. 5) DynaComm's powerful string manipulation functions (POS, PARSE, UPPER, TRIM, 
  431. etc.) enable the "clean up" of manual Address Book entries to maintain a 
  432. consistent look in the listbox (eg, convert each entry to all uppercase, place 
  433. square brackets around .DIS filenames, parse ECD Matches into the "LastName, 
  434. Firstname" format, etc.)
  435.  
  436.  
  437. Roll the Credits...
  438. -------------------
  439. I would like to thank Kim Pavey and Bill Buckley of Future Soft Engineering, 
  440. Inc. for their invaluable assistance in the development of this script.  They 
  441. were always there when I had a question and they always had the right answer.  
  442. Thanks again, folks!
  443.  
  444.  
  445. Bill Bailey
  446. Wilmington, DE
  447. CIS: 76666,2023
  448.  
  449.