home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / postroad.zip / addrutil.doc next >
Text File  |  1997-10-23  |  9KB  |  167 lines
  1.                     Post Road Mailer Address Book Utilities
  2.                     ---------------------------------------
  3.  
  4. The Post Road Mailer address books are kept in binary files that cannot be
  5. edited or easily changed except from within the program.  We have received
  6. inquiries from users for a way to create or change address books using external
  7. programs or editors, or change them in ways the Post Road Mailer wasn't designed
  8. to do.  These REXX utility programs are provided to facilitate such changes.
  9.  
  10. Each Post Road Mailer address book is kept in a file in the main Post Road
  11. Mailer directory and has an extension of .ADR.  These utilities do not modify an
  12. *.ADR file directly.  Instead, you use ADR2ASC.CMD to export an *.ADR file's
  13. contents to ASCII files which you can modify or add more entries to, and then
  14. use ASC2ADR.CMD to convert the ASCII files back to an *.ADR file.
  15.  
  16. Format of the ASCII Files
  17. =========================
  18. READ THESE FIRST FIVE TIPS WHETHER YOU CARE ABOUT THE FILE FORMAT OR NOT:
  19.  
  20. 1.  When you need to edit an *.ASC or *.GRP file, you must always use an editor,
  21. such as E.EXE, that does not convert Tab characters to spaces the way most
  22. editors do!
  23.  
  24. 2.  The part of the first line of the *.ASC file after the address book's title
  25. must not be changed, or the program will not recognize the file as a valid *.ASC
  26. file.
  27.  
  28. 3.  The fourth line of both the *.ASC file and the *.GRP file must be blank.
  29.  
  30. 4.  The address book entries begin on line five of the *.ASC file.  The address
  31. group entries begin on line five of the *.GRP file.
  32.  
  33. 5.  The format has totally changed from that used in previous versions of
  34. ADR2ASC.CMD and ASC2ADR.CMD, so if you have any sort of custom utilities which
  35. depend on that old format, you must not replace your old ADR2ASC.CMD and
  36. ASC2ADR.CMD files with these new ones.
  37.  
  38. The ASCII files created by ADR2ASC and FLDR2ASC and NOTE2ASC, and the ASCII
  39. files input to ASC2ADR have the same structure.  (The following description of
  40. the file format may be easier to understand if you run ADR2ASC against an
  41. existing Post Road Mailer address book and examine the resulting files.)
  42.  
  43. The first line of the *.ASC and *.GRP files must contain the title of the
  44. address book, followed by the string " (Post Road Mailer address book" (or
  45. "....address groups") and at least one more character after that.  The contents
  46. of the second and third lines are not important, except as information for the
  47. user.  The fourth line must be blank.  The rest of the lines in each file are
  48. the address entries, one entry per line.
  49.  
  50. In the *.GRP file, which is just the address group entries, the format of each
  51. line is quite simple:  The name of the group, a Tab character, the first address
  52. in the group, a Tab character, the second address, a Tab character, the third
  53. address, etc.  If you have more addresses than can fit on a line in your editor,
  54. break the line after a Tab character and continue on the next line.  On lines
  55. which are not be to interpreted as continuing, do not finish with a Tab
  56. character.  A line that ends with a Tab character will have the following line
  57. appended as if there had been no line break at all.  A line that does not end
  58. with a Tab character will be interpreted as the end of the entry.
  59.  
  60. In the *.ASC file, which is just the non-group entries, the format of each line
  61. is shown on the third line of the file.  The field data must be entered in that
  62. exact order, with each field separated from the next by a Tab character.  Fields
  63. which contain no data are represented by having nothing at all between one Tab
  64. character and the next.  Each entry (line) must contain exactly 16 Tab
  65. characters, unless there are multiple lines of Notes, in which case there is
  66. another Tab between each Note field and the next, at the end of the line.
  67. Further, each entry must contain either a non-blank Last Name field or a
  68. non-blank Organization field.
  69.  
  70. If you need to change the order in which ASC2ADR.CMD expects the fields and the
  71. order in which the other programs create them, the program lines you need to
  72. modify are:
  73.  
  74.    ADR2ASC    91 & 244
  75.    ASC2ADR    61
  76.    FLDR2ASC   95
  77.    NOTE2ASC   96
  78.  
  79. ADR2ASC
  80. =======
  81. ADR2ASC will convert an existing Post Road Mailer address book into a pair of
  82. ASCII files.  The only command line parameter of the ADR2ASC program is the name
  83. of the address book file to be converted.  For example,
  84.  
  85.    ADR2ASC C:\POSTROAD\FRIENDS
  86.  
  87. Address book files must have an .ADR extension, though you need not type the
  88. .ADR part of the filename as part of the command.
  89.  
  90. If a file by the same name as the *.ADR file, but with an *.ASC or *.GRP
  91. extension exists in the current directory, ADR2ASC.CMD will ask you whether you
  92. want to overwrite the existing output files, append all the *.ADR file's entries
  93. to the *.ASC and *.GRP files, append only the non-unique entries, or exit the
  94. program without doing any of those things.  A non-group entry is considered
  95. "unique" if none of the email addresses in the entry is exactly identical (case
  96. insensitive) to any of the entries which were in the original *.ASC file.  A
  97. group entry is considered "unique" if the group name is not exactly identical
  98. (case insensitive) to any of the entries which were in the original *.GRP file.
  99.  
  100. ASC2ADR
  101. =======
  102. This program takes the name of an *.ASC file (or *.TXT file or whatever, but the
  103. format of the file must be that of the *.ASC file described above, regardless of
  104. the filename you've given it) as a command line parameter.  (You must specify
  105. the filename's extension if it is not .ASC.)  It takes the *.ASC file and the
  106. *.GRP file by the same name, if it exists, in the current directory, and turns
  107. them into an *.ADR file by the same name, in the current directory.  The Post
  108. Road Mailer won't see the *.ADR file until you place it into that program's main
  109. directory.
  110.  
  111. FLDR2ASC
  112. ========
  113. This program creates an *.ASC file containing an entry for each note in the
  114. specified folder.  The entry will be the name (if known) and address on the
  115. Reply-to: line, From: line (if no Reply-to: line exists), or Sender: line (if no
  116. Reply-to: or From: line exists) of each note.  Duplicate entries (those with an
  117. address which matches [case insensitive] the address of another entry in that
  118. folder) will not be added.
  119.  
  120. Parameter:  Pathname of the directory which is the folder from which you want
  121. the *.ASC file entries made.  For example, the College subfolder of your Friends
  122. folder, in your address@wherever.com inbasket, is probably
  123. C:\POSTROAD\ADDRESS\FRIENDS\COLLEGE.
  124.  
  125. You will probably want to modify the title of the address book named in the
  126. *.ASC file, and rename the *.ASC file as well, before you create an *.ADR file
  127. from it.  Or, if you want to add this folder's addresses to an existing address
  128. book instead of creating a new one, you can do the following:
  129.  
  130. - Use ADR2ASC.CMD to create *.ASC and *.GRP files from the *.ADR file
  131. - Use FLDR2ASC.CMD to create an *.ASC file from the folder's notes
  132. - Move the entries from the latter *.ASC file to the former *.ASC file
  133. - Delete the latter *.ASC file
  134. - Use ASC2ADR.CMD to create the *.ADR file from the former *.ASC file
  135.  
  136. NOTE2ASC
  137. ========
  138. This program creates an *.ASC file, in the current directory, containing entries
  139. for any number of the internet addresses found in a particular *.POP file.  The
  140. *.POP file is specified as a command line parameter.  This means that you can
  141. run the program from the command line, or you can drag a note from your Post
  142. Road Mailer inbasket or from a folder, and drop it on a program object which
  143. executes NOTE2ASC (since a dragged file's full path/filename specification is
  144. always passed as a command line parameter to a program object on which it is
  145. dropped unless the creator of the program object has taken steps to avoid that).
  146.  
  147. When specifying the *.POP filename at the command line, you do not have to type
  148. the .POP extension.  The program will add ".POP" to the end of any filename
  149. which doesn't already end with that string.
  150.  
  151. For each internet address found in the note file, the program will display the
  152. address as well as the entire line of text in which it was found, and ask you
  153. for the name which should be associated with that address.  If you don't want an
  154. entry created for a particular address, just hit the Enter key instead of typing
  155. a name.
  156.  
  157. You will probably want to modify the title of the address book named in the
  158. *.ASC file, and rename the *.ASC file as well, before you create an *.ADR file
  159. from it.  Or, if you want to add the note's addresses to an existing address
  160. book instead of creating a new one, you can do the following:
  161.  
  162. - Use ADR2ASC.CMD to create *.ASC and *.GRP files from the *.ADR file
  163. - Use NOTE2ASC.CMD to create an *.ASC file from the note's addresses
  164. - Move the entries from the latter *.ASC file to the former *.ASC file
  165. - Delete the latter *.ASC file
  166. - Use ASC2ADR.CMD to create the *.ADR file from the former *.ASC file
  167.