



                           SMTP Email Engine

                           Library for COBOL

                                 (SEE4CB)


                            REFERENCE MANUAL



                               Version 1.0

                               June 8, 1998




                     This software is provided as-is.
              There are no warranties, expressed or implied.




                           Copyright (C) 1998
                           All rights reserved



                       MarshallSoft Computing, Inc.
                           Post Office Box 4543
                           Huntsville AL 35815


                           Voice : 256-881-4630
                             FAX : 256-880-0925
                           email : info@marshallsoft.com
                             web : www.marshallsoft.com

                               _______
                          ____|__     |                (R)
                       --+       |    +-------------------
                         |   ____|__  |  Association of
                         |  |       |_|  Shareware
                         |__|   o   |    Professionals
                       --+--+   |   +---------------------
                            |___|___|    MEMBER


      MARSHALLSOFT is a registered trademark of MarshallSoft Computing.





     SEE4CB Reference Manual                                   Page 1

                            C O N T E N T S



        Chapter                                     Page

        Table of Contents.............................2

        General Remarks...............................3

        SEE Functions.................................3

           seeClose...................................3

           seeConnectTo...............................4

           seeDriver..................................5

           seeErrorText...............................6

           seeIntegerParam............................7

           seeSendEmail...............................8

           seeStatistics..............................9

           seeStringParam............................10

           seeVerifyFormat...........................11

        SEE Error Codes..............................12



























     SEE4CB Reference Manual                                   Page 2


      General Remarks


      All functions return an integer code. Negative values are always
      errors. See section "SEE Error Codes". Non-negative return codes are
      never errors.

      Note that all strings are null terminated. For example:

      WORKING-STORAGE SECTION.
       01  LOG_FILENAME.
           05  FILLER PIC X(8) VALUE "test.log".
           05  FILLER PIC X VALUE X'00'.



      SEE Functions



      +----------+--------------------------------------------------------+
      | seeClose | Closes SMTP Email Engine.                              |
      +----------+--------------------------------------------------------+


        SYNTAX  CALL "seeClose" WITH STDCALL
                  END-CALL.

       REMARKS  The seeClose function closes the connection created by
                calling seeConnectTo. seeConnectTo can be called again to
                open a connection to another SMTP server if desired.

                Normally, there is only one seeConnectTo and one seeClose
                in your program.

       RETURNS  < 0 : An error has occured. See the error list.

       EXAMPLE

                *> call after sending all email.

                CALL "seeClose" WITH STDCALL

      ALSO SEE  seeConnectTo.













     SEE4CB Reference Manual                                   Page 3


      +--------------+----------------------------------------------------+
      | seeConnectTo | Connects to SMTP server.                           |
      +--------------+----------------------------------------------------+


        SYNTAX  CALL "seeConnectTo" WITH STDCALL USING
                    BY REFERENCE Server  *> SMTP server.
                    BY REFERENCE From    *> Your email address in brackets.
                    BY REFERENCE ReplyTo *> Email address to reply to.
                  END-CALL.

       REMARKS  The seeConnectTo function establishes a connection with the
                SMTP server as specified by the Server argument.

                Your SMTP server name will typically be named
                "mail.XXX.com" where XXX is your email address, such as
                name@XXX.com. Your SMTP server name can also be found in
                the setup information for your normal email client, such as
                Eudora or Microsoft Outlook.

                The SMTP server name can also be specified in dotted
                decimal notation if wanted. For example "10.23.231.1".

                The From string is required and must be enclosed in "<>"
                brackets, such as <mike@marshallsoft.com>.

                The ReplyTo string is optional and is used for the
                "Reply-To:" header line. If used, the email address must be
                enclosed in "<>" brackets.


       RETURNS  < 0 : An error has occured. See the error list.

       EXAMPLE

                WORKING-STORAGE SECTION.
                 01  IS_ZERO      PIC 9(9) COMP-5 VALUE 0.
                 01  SMTP_SERVER.
                     05  FILLER PIC X(15) VALUE "mail.hiwaay.net".
                     05  FILLER PIC X VALUE X'00'.
                 01  EMAIL_FROM.
                     05  FILLER PIC X(23) VALUE "<mike@marshallsoft.com>".
                     05  FILLER PIC X VALUE X'00'.

                *> connect to SMTP server
                DISPLAY "Calling seeConnectTo()..."
                CALL "seeConnectTo" WITH STDCALL USING
                  BY REFERENCE SMTP_SERVER   *> SMTP server name
                  BY REFERENCE EMAIL_FROM    *> sender's email address
                  BY REFERENCE IS_ZERO       *> no Reply-To header

      ALSO SEE  seeClose.





     SEE4CB Reference Manual                                   Page 4


      +-----------+-------------------------------------------------------+
      | seeDriver | Executes next SEE state.                              |
      +-----------+-------------------------------------------------------+


        SYNTAX  CALL "seeDriver" WITH STDCALL
                  END-CALL.

       REMARKS  The seeDriver function executes the next state in SEE16.DLL
                or SEE32.DLL after calling seeConnectTo, seeSendEmail, or
                seeClose provided that the AUTO_DRIVER_CALL flag is
                disabled.

                The purpose of this function is to allow the programmer to
                get control after the driver executes each state.

       RETURNS  = 0 : The driver is done.
                < 0 : An error has occured. See the error list.
                > 0 : The returned value is the state just executed.

       EXAMPLE

                WORKING-STORAGE SECTION.
                 01  SEE-CODE PIC 9(9) COMP-5.


                DRIVER-LOOP.

                  CALL "seeDriver" WITH STDCALL
                  END-CALL.
                  *> check results
                  MOVE PROGRAM-STATUS TO SEE-CODE
                  IF SEE-CODE < 0 THEN
                    DISPLAY "Error returned from seeDriver"
                    GO TO ERROR-EXIT
                  END-IF.
                  *> ready to execute next state ?
                  IF SEE-CODE > 0 THEN
                    GO TO DRIVER-LOOP
                  END-IF.
                  *> Done since SEE-CODE is 0

      ALSO SEE  seeIntegerParam














     SEE4CB Reference Manual                                   Page 5


      +--------------+----------------------------------------------------+
      | seeErrorText | Get text associated with error code.               |
      +--------------+----------------------------------------------------+


        SYNTAX  CALL "seeErrorText" WITH STDCALL USING
                    BY VALUE     Code   *> Error code returned by SEE.
                    BY REFERENCE Buffer *> Buffer to place error text into.
                    BY VALUE     BufLen *> Length of above Buffer.
                  END-CALL.

       REMARKS  The seeErrorText function is used to get the error text
                associated with an an error code as returned by
                selConnectTo, seeSendEmail, seeClose, or seeDriver.

                When an error occurs, seeErrorText can be used to get the
                error text so that it can be displayed for the user.

       EXAMPLE

                WORKING-STORAGE SECTION.
                 01  SEE-CODE     PIC 9(9) COMP-5.
                 01  BUFFER       PIC X(80).
                 01  BUF-LEN      PIC 9(9) COMP-5 VALUE 80.

                CALL "seeErrorText" WITH STDCALL USING
                  BY VALUE     SEE-CODE
                  BY REFERENCE BUFFER
                  BY VALUE     BUF-LEN
                END-CALL
                DISPLAY BUFFER

      ALSO SEE
























     SEE4CB Reference Manual                                   Page 6


      +-----------------+-------------------------------------------------+
      | seeIntegerParam | Sets SEE integer parameter.                     |
      +-----------------+-------------------------------------------------+


        SYNTAX  CALL "seeIntegerParam" WITH STDCALL USING
                    BY VALUE ParmIndex  *> Parameter index (see below).
                    BY VALUE ParmValue  *> Value of parameter to set.
                  END-CALL.

       REMARKS The seeIntegerParam is used to set an integer parameter as
                defined in SEE.H. For more information, refer to the Users
                Manual. All times are in milliseconds.

                        Parameter Name     Default
                 SEE_MIN_RESPONSE_WAIT  :  500
                 SEE_MAX_RESPONSE_WAIT  :  10000
                     SEE_MIN_LINE_WAIT  :  5
                     SEE_MAX_LINE_WAIT  :  10000
                      SEE_CONNECT_WAIT  :  60000
                  SEE_QUOTED_PRINTABLE  :  0
                  SEE_AUTO_CALL_DRIVER  :  1

                SEE_MIN_RESPONSE_WAIT is the delay before looking for the
                server's response.

                SEE_MAX_RESPONSE_WAIT is the time after which a "time-out"
                error ocurrs if the server has not responded.

                SEE_MIN_LINE_WAIT is the delay before checking if the
                server is ready to accept the next line of input.

                SEE_MAX_LINE_WAIT is the time after which a "time-out"
                error is declared if the server has not responded.

                SEE_CONNECT_WAIT is the maximum time allowed to complete a
                connection to the SMTP server.

                SEE_QUOTED_PRINTABLE controls the whether messages are (1)
                or are not (0) encoded as quoted-printable.

                SEE_AUTO_CALL_DRIVER controls whether ssDriver is called
                automatically (to completion) after seeConnectTo,
                seeSendEmail, or seeClose is called.

       EXAMPLE

                CALL "seeIntegerParam" WITH STDCALL USING
                  BY VALUE SEE_AUTO_CALL_DRIVER  *> Disable auto call
                  BY VALUE IS_ZERO               *> off (disabled)
                END-CALL.

      ALSO SEE  seeStringParam.




     SEE4CB Reference Manual                                   Page 7


      +--------------+----------------------------------------------------+
      | seeSendEmail | Sends email and attachments.                       |
      +--------------+----------------------------------------------------+


        SYNTAX  CALL "seeSendEmail" WITH STDCALL USING
                    BY REFERENCE To     *> Receipient, separated by commas.
                    BY REFERENCE CC     *> CC list, separated by commas.
                    BY REFERENCE BCC    *> BCC list, separated by commas.
                    BY REFERENCE Subj   *> Subject text.
                    BY REFERENCE Msg    *> Message or message filename.
                    BY REFERENCE Attach *> File attachment.
                  END-CALL.

       REMARKS  The seeSendEmail function is used to send email once a
                conection has been made to your SMTP server after calling
                seeConnectTo.

                Note that all email addresses (in To, CC, and BCC strings)
                must be bracketed, for example: <mike@marshallsoft.com>

                The CC and BCC strings may contain multiple email
                addresses, separted by commas. For example:

                "Billy Bob<bbob@isp.com>,Buster<bm@isp.com>"

                If the first character of the message (fifth argument) is
                a '@', then it is considered as the filename which contains
                the message to send.

       RETURNS  < 0 : An error has occured. See the error list.

       EXAMPLE

                WORKING-STORAGE SECTION.
                 01  EMAIL_TO.
                     05  FILLER PIC X(23) VALUE "<mike@marshallsoft.com>".
                     05  FILLER PIC X VALUE X'00'.
                 01  EMAIL_SUBJ.
                     05  FILLER PIC X(10) VALUE "COBOL Test".
                     05  FILLER PIC X VALUE X'00'.
                 01  EMAIL_MSG.
                     05  FILLER PIC X(10) VALUE "@message.mai".
                     05  FILLER PIC X VALUE X'00'.

                CALL "seeSendEmail" WITH STDCALL USING
                  BY REFERENCE EMAIL_TO      *> receipient
                  BY REFERENCE IS_ZERO       *> no CC list
                  BY REFERENCE IS_ZERO       *> no BCC list
                  BY REFERENCE EMAIL_SUBJ    *> email subject
                  BY REFERENCE EMAIL_MSG     *> text of message
                  BY REFERENCE IS_ZERO       *> no attachment

      ALSO SEE seeConnectTo



     SEE4CB Reference Manual                                   Page 8


      +---------------+---------------------------------------------------+
      | seeStatistics | Returns runtime statistics.                       |
      +---------------+---------------------------------------------------+


        SYNTAX  CALL "Statistics" WITH STDCALL USING
                    BY VALUE Index   *> Specifies which statistic.
                  END-CALL.

       REMARKS  The seeStatistics function is used to return runtime
                statistics in the SEE DLL. The values of Index are defined
                in SEE.H as follows:

                   SEE_GET_SOCK_ERROR : Gets last socket error.
                      SEE_GET_COUNTER : Gets # times driver called.
                     SEE_GET_RESPONSE : Gets last SMTP response code.

                SEE_GET_MESSAGE_BYTES_READ : Gets # message bytes read.
                 SEE_GET_ATTACH_BYTES_READ : Gets # attachment bytes read.
                  SEE_GET_TOTAL_BYTES_READ : Gets total of above two.

                SEE_GET_MESSAGE_BYTES_SENT : Gets # message bytes sent.
                 SEE_GET_ATTACH_BYTES_SENT : Gets # attachment bytes sent.
                  SEE_GET_TOTAL_BYTES_SENT : Gets total of above two.

                The number of message bytes sent will usually be larger
                than your message size because of SMTP protocol overhead.

                The number of attachment bytes sent will be at least
                one-third larger than the actual attachment since every 3
                bytes are encoded as 4 7-bit ASCII bytes before being
                transmitted.

                The purpose of "...BYTES_READ" and "...BYTES_SENT" is to
                provide the ability to track the transmission progress of
                large messages and attachments. See the DRIVER example
                program.

       EXAMPLE

                *> get total message & attachment bytes transmitted.

                CALL "Statistics" WITH STDCALL USING
                  BY VALUE SEE_GET_TOTAL_BYTES_SENT  *> get bytes sent
                END-CALL.


      ALSE SEE  seeDriver, seeIntegerParam and seeStringParam.









     SEE4CB Reference Manual                                   Page 9


      +----------------+--------------------------------------------------+
      | seeStringParam | Sets SEE string parameter.                       |
      +----------------+--------------------------------------------------+


        SYNTAX  CALL "seeStringParam" WITH STDCALL USING
                    BY VALUE     ParamName    *> Index of parameter.
                    BY REFERENCE ParamString  *> Parameter string.
                  END-CALL.

       REMARKS  The seeStringParam function is used to set a string
                parameter as defined in SEE.H. For more information, refer
                to the Users Manual.

                SEE_LOG_FILE : Specifies the log filename.

                The log file is used to debug a SMTP session. Be advised
                that log files can be quite large. Don't use them unless
                neccessary.

       EXAMPLE

                WORKING-STORAGE SECTION.
                 01  LOG_FILENAME.
                     05  FILLER PIC X(8) VALUE "test.log".
                     05  FILLER PIC X VALUE X'00'.

                CALL "seeStringParam" WITH STDCALL USING
                  BY VALUE     SEE_LOG_FILE
                  BY REFERENCE LOG_FILENAME
                END-CALL.

      ALSO SEE seeIntegerParam
























     SEE4CB Reference Manual                                   Page 10


      +-----------------+-------------------------------------------------+
      | seeVerifyFormat | Check email address format.                     |
      +-----------------+-------------------------------------------------+


        SYNTAX  CALL "seeVerifyFormat" WITH STDCALL USING
                    BY REFERENCE String   *> Email address to check.
                  END-CALL.

       REMARKS  The seeVerifyFormat function is use to test an individual
                email address for proper formatting. If this function
                returns 0 or above, then the email address is properly
                formatted. But, if this function returns a negative value,
                the email address is either badly formatted, or it uses
                characters (such as '%') that are not normally used as part
                of an email address.

                Note that left and right brackets ('<' and '>') must
                surround the email address.

       EXAMPLE

                WORKING-STORAGE SECTION.
                 01 EMAIL_ADDR.
                    05 FILLER PIC X(26) VALUE "Billy Bob<beb@hisasp.com>".
                    05 FILLER PIC X VALUE X'00'.

                CALL "seeVerifyFormat" WITH STDCALL USING
                  BY REFERENCE EMAIL_ADDR
                END-CALL.

      ALSO SEE seeErrorText

























     SEE4CB Reference Manual                                   Page 11

                          SEE Error Codes




      +-----------------------+-----------------------------------------+
      | SEE_NO_ERROR          | No error.                               |
      | SEE_CANNOT_COMPLY     | Cannot comply. Not always an error.     |
      +-----------------------+-----------------------------------------+
      | SEE_EOF               | End of file (socket has been closed).   |
      | SEE_IS_BLOCKING       | Socket is currently blocking.           |
      | SEE_BAD_DOTTED        | Bad dotted address.                     |
      | SEE_TIMED_OUT         | Socket timed out awaiting data.         |
      | SEE_ABORTED           | The DLL has been corrupted.             |
      | SEE_ALREADY_CONNECTED | Already connected to server.            |
      | SEE_BACK_OVERFLOW     | Response buffer has overflowed.         |
      | SEE_BAD_ADDRESS_CHAR  | Bad character in email address.         |
      | SEE_CANNOT_ATTACH     | Cannot access WINSOCK                   |
      | SEE_CANNOT_OPEN       | Cannot open file.                       |
      | SEE_CONNECT_ERROR     | Error attempting to connect.            |
      | SEE_EMPTY_ADDRESS     | EMPTY email address.                    |
      | SEE_FROM_NULL_ARG     | FromPtr is NULL.                        |
      | SEE_MISSING_AT_CHAR   | Missing '@' character in email address. |
      | SEE_MISSING_FROM      | Missing FROM email address.             |
      | SEE_MISSING_LEFT      | Missing '<' delimiter in email address. |
      | SEE_MISSING_RIGHT     | Missing '>' terminating email address.  |
      | SEE_NOT_CONNECTED     | Not connected to server                 |
      | SEE_NO_RECEIPIENTS    | Must have at least one receipient.      |
      | SEE_NO_SERVER         | Cannot find Smtp server.                |
      | SEE_NULL_POINTER      | Unexpected NULL pointer.                |
      | SEE_RCPT_NULL_ARG     | ToPtr is NULL.                          |
      | SEE_SMTP_ERROR        | SMTP returned error.                    |
      | SEE_SMTP_NULL_ARG     | SMTP Server not specified.              |
      | SEE_SOCK_READ_ERROR   | Socket read error.                      |
      | SEE_SOCK_WRITE_ERROR  | Socket write error.                     |
      | SEE_TOO_MANY_AT_CHARS | Too many '@' symbols in email address.  |
      +-----------------------+-----------------------------------------+

      NOTES:

      (1) All error codes are negative.
      (2) Numerical error codes are defined in DEFINES.H.
      (3) SEE_ABORTED will be returned if the DLL has been modified. You
          should never get this message!














     SEE4CB Reference Manual                                   Page 12


