home *** CD-ROM | disk | FTP | other *** search
/ Beijing Paradise BBS Backup / PARADISE.ISO / software / OPENDOOR / WRITEJAM.ZIP / WRITEJAM.DOC < prev    next >
Encoding:
Text File  |  1994-03-01  |  8.3 KB  |  207 lines
  1.              ─╥─ ╓──╖ ╥╖ ╓╥      ╥   ╥ ╥──╖ ─╥─ ╓─╥─╖ ╥──╖                
  2.               ║  ║  ║ ║╙╥╜║      ║   ║ ║  ║  ║    ║   ║                   
  3.               ║  ╟──╢ ║   ║      ║   ║ ╟╥─╜  ║    ║   ╟──                 
  4.               ║  ║  ║ ║   ║      ║╓╨╖║ ║╙╖   ║    ║   ║                   
  5.            ╙──╨  ╨  ╨ ╨   ╨      ╨╜ ╙╨ ╨ ╙─ ─╨─   ╨   ╨──╨                
  6.  
  7.  
  8.                                 V 1.2
  9.  
  10.  
  11.                THE "WRITE MESSAGE TO JAM BASE" FUNCTION
  12.  
  13.  
  14.                    Copyright 1993 Michael Lecuyer.
  15.                          ALL RIGHTS RESERVED.
  16.  
  17.               FidoNet: 1:2600/140, Internet: mjl@acm.org
  18.  
  19.  
  20.     Note from the JAM authors:
  21.  
  22.     All applications that support JAM must include one of the following
  23.     notices in their documentation and somewhere in the product's credit
  24.     section:
  25.  
  26.     "JAM(mbp) - Copyright 1993 Joaquim Homrighausen, Andrew Milner,
  27.                                Mats Birch, Mats Wallin.
  28.                                ALL RIGHTS RESERVED."
  29.  
  30.     or
  31.  
  32.     "This product uses the JAM(mbp) API -
  33.      Copyright 1993 Joaquim Homrighausen, Andrew Milner, Mats Birch,
  34.                     Mats Wallin. ALL RIGHTS RESERVED."
  35.  
  36.     No organization, company, person, entity, or other being may impose
  37.     any fees for any reason for providing this document or the
  38.     accompanying API. This document and the accompanying API may not be
  39.     sold or otherwise transferred for personal or company gain under any
  40.     circumstances.
  41.  
  42. This version is for the JAMAPI 1.001.
  43.  
  44. There is another version of the JAMAPI due out in the first quarter
  45. of 1994.  At that time an update of JAMwrite will be issued if
  46. necessary.
  47.  
  48. My reasons for presenting this function to the door writing world are
  49. both to promote the JAM base and for barter.  If you find this code
  50. has helped your door support the JAM message base I would appreciate
  51. a registered copy of your programme sent to 1:2600/140 in return.
  52.  
  53. The JAM message base provides an important step out of the dark ages
  54. of previous message bases, such as the Hudson Message Base.  Although
  55. the finest features of the JAM base may escape most non-programmers
  56. and possibly some software authors you may find yourself in need of
  57. JAM support. Probably you only need to be able to send a message or
  58. two to a BBS caller or the sysop and you don't give a damn about the
  59. new upstart format.
  60.  
  61. True believer or curmudgeon, this function can save you time while
  62. lining your pockets with gold as the registration fees pour in, all
  63. because your product supports the JAM message base format :)
  64.  
  65. A sample programme will show how easy it is to send a JAM message.
  66. You need to capture one piece of information from either the BBS
  67. itself or from the sysop installing your product.  The path to the
  68. JAM message base is the only externally supplied information needed
  69. by this function.  The rest of the information is up to you.
  70.  
  71. Included in the archive are libraries in small and large model of the
  72. JAMAPI for both Borland 3.00 C/C++ and the MicroSoft V7.00
  73. compilers.  You must work with the JAMAPI to produce libraries for
  74. other compilers.  The Borland V3.0 libraries are in the file
  75. BORLAND.ZIP and the Microsoft V7 libraries are in MSC.ZIP.
  76.  
  77. To compile and link with your programme the libraries and header
  78. files should be in the directory with your own source. Imaginitive
  79. people will find a way around this.
  80.  
  81.  
  82. A sample programme:
  83.  
  84. #include "writejam.h"
  85.  
  86. main()
  87. {
  88.    char *jambase = "C:\\mail\\test";
  89.    char *from = "System Operator";
  90.    char *to = "Michael Lecuyer";
  91.    char *subject = "Testing the jamwrite";
  92.    char *text = "This is a test message that we will want to test\n"
  93.                 "which should be easy enough\n";
  94.  
  95.    JAMcopyright();   // Legal requirement for using the JAM API
  96.  
  97.  
  98.    write_jam(jambase, from, to, subject, text, MSG_LOCAL | MSG_PRIVATE);
  99.  
  100.    return 0;
  101. }
  102.  
  103.  
  104.    The write_jam() function takes 6 parameters.
  105.  
  106.    1) The path to the JAMbase - this might look something like "C:\MAIL\TEST"
  107.       This path includes the file name for the jam base but no extensions
  108.       are used.  The JAM base API will create the files:
  109.           TEST.JDT (message text)
  110.           TEST.JDX (index to messages)
  111.           TEST.JHR (JAM header information)
  112.           TEXT.JLR (JAM last read pointers)
  113.  
  114.    2) From Field: This is the name of the sender
  115.  
  116.    3) To Field:  The name of the receiver
  117.  
  118.    4) Subject Field:  What the message is about
  119.  
  120.    5) Text:  pointer to a buffer containing the entire text of the message
  121.  
  122.    6) Flags: these flags are found in the file JAM.DOC and JAM.H in the
  123.       JAMAPI.
  124.  
  125. The JAM Api header files and JAM library are expected to be in the
  126. current directory.
  127.  
  128. The function returns 0 if it fails, 1 if it succeeds in writing to
  129. the message base.  Some parts of the function will print out an error
  130. on the console.  For those who find that unacceptable the print
  131. statements should be removed or modified.
  132.  
  133. The flags are defined as (as found in the file JAM.H):
  134.  
  135.    MSG_LOCAL       0x00000001L    Msg created locally
  136.    MSG_INTRANSIT   0x00000002L    Msg is in-transit
  137.    MSG_PRIVATE     0x00000004L    Private
  138.    MSG_READ        0x00000008L    Read by addressee
  139.    MSG_SENT        0x00000010L    Sent to remote
  140.    MSG_KILLSENT    0x00000020L    Kill when sent
  141.    MSG_ARCHIVESENT 0x00000040L    Archive when sent
  142.    MSG_HOLD        0x00000080L    Hold for pick-up
  143.    MSG_CRASH       0x00000100L    Crash
  144.    MSG_IMMEDIATE   0x00000200L    Send Msg now, ignore restrictions
  145.    MSG_DIRECT      0x00000400L    Send directly to destination
  146.    MSG_GATE        0x00000800L    Send via gateway
  147.    MSG_FILEREQUEST 0x00001000L    File request
  148.    MSG_FILEATTACH  0x00002000L    File(s) attached to Msg
  149.    MSG_TRUNCFILE   0x00004000L    Truncate file(s) when sent
  150.    MSG_KILLFILE    0x00008000L    Delete file(s) when sent
  151.    MSG_RECEIPTREQ  0x00010000L    Return receipt requested
  152.    MSG_CONFIRMREQ  0x00020000L    Confirmation receipt requested
  153.    MSG_ORPHAN      0x00040000L    Unknown destination
  154.    MSG_ENCRYPT     0x00080000L    Msg text is encrypted
  155.    MSG_COMPRESS    0x00100000L    Msg text is compressed
  156.    MSG_ESCAPED     0x00200000L    Msg text is seven bit ASCII
  157.    MSG_FPU         0x00400000L    Force pickup
  158.    MSG_TYPELOCAL   0x00800000L    Msg is for local use only (not for export)
  159.    MSG_TYPEECHO    0x01000000L    Msg is for conference distribution
  160.    MSG_TYPENET     0x02000000L    Msg is direct network mail
  161.    MSG_NODISP      0x20000000L    Msg may not be displayed to user
  162.    MSG_LOCKED      0x40000000L    Msg is locked, no editing possible
  163.    MSG_DELETED     0x80000000L    Msg is deleted
  164.  
  165. For a private message to the sysop or caller the flags might be:
  166.  
  167.    MSG_LOCAL | MSG_PRIVATE
  168.  
  169. or for more a public message:
  170.  
  171.    MSG_LOCAL
  172.  
  173. The MSG_LOCKED flag means no editing by anyone implying that the
  174. message base cleaning programmes aren't to touch it either.
  175.  
  176. Preparing messages for a Fidonet type tosser is beyond the scope of
  177. this writejam() function.  If you need such a function contact the
  178. author.
  179.  
  180. One of the best (and possibly only) ways to test that the function
  181. has worked properly is to use the JAMUTIL programme included in the
  182. JAM API.
  183.  
  184. This programme has been compiled successfully under Borland C/C++
  185. V3.0 and Borland C V2.0.  The PRO version of V3.0 has a builtin
  186. getpid() function.  Because not all libraries include getpid() there
  187. is code to to simulate this call.  Although the function very close
  188. to what Borland uses, it can be removed and the Borland Runtime
  189. Library version used if you have the right version of the compiler.
  190. For people compiling for another OS this function must be replaced.
  191.  
  192. The function also requires the appropriate JAM API library be created
  193. and made available.  Help on compiling the library is available with
  194. the JAMAPI.  It is important to make the correct model library for
  195. your project.  The JAM API will compiler under Microsoft, Borland,
  196. and several other compilers for DOS, Windows, OS/2 and for the Sun
  197. workstation using the GNU GCC compiler.
  198.  
  199. I can be reached at Fidonet address 1:2600/140 or on the Internet
  200. as mjl@acm.org.  I also be contacted through the RA_UTILITY echo
  201. on Fidonet.  Please report problems and suggestions through any
  202. of these channels.
  203.  
  204.  
  205. Borland and Microsoft are registered trademarks of their respective
  206. companies.  
  207.