



                         SMTP/POP3 Email Engine

                         Library for Visual dBase


                                 (SEE4DB)


                            REFERENCE MANUAL



                               Version 3.0

                               May 10, 1999




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




                           Copyright (C) 1999
                           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.




     SEE4DB Reference Manual                                   Page 1

                            C O N T E N T S


        Chapter                                     Page

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

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

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

           seeAttach..................................3

           seeClose...................................4

           seeDebug...................................5

           seeDecodeBuffer............................6

           seeDeleteEmail.............................7

           seeDriver..................................8

           seeEncodeBuffer............................9

           seeErrorText..............................10

           seeExtractText............................11

           seeGetEmailCount..........................12

           seeGetEmailFile...........................13

           seeGetEmailLines..........................14

           seeGetEmailSize...........................15

           seeGetEmailUID............................16

           seeIntegerParam...........................17

           seePop3Connect............................19

           seeRelease................................20

           seeSendEmail..............................21

           seeSmtpConnect............................22

           seeStatistics.............................23

           seeStringParam............................24

           seeVerifyFormat...........................25

           seeVerifyUser.............................26


     SEE4DB Reference Manual                                   Page 2

      General Remarks

      All functions return an integer code. Negative values are always
      errors. See Section 10.3 "SEE Error Return Code List" in the
      SEE/POP3 Users Manual (SEE4DB_U.TXT). Non-negative return codes are
      never errors.

      This declaration file is for dBase 7.0 (Win32). If dBase 5.X (Win16)
      is being used, replace CINT with CLONG as shown in SEE16.CC.

      In the code following, C style comments (//) are used to improve
      clarity.

      SEE4DB Functions


      +-----------+-------------------------------------------------------+
      | seeAttach | Attach SMTP/POP3 Email Engine.                        |
      +-----------+-------------------------------------------------------+


        SYNTAX  CLONG seeAttach(CLONG,CSTRING)
                    // CLONG   NbrChans : Number of channels or threads
                    // CSTRING KeyCode  : Key code value.

       REMARKS The seeAttach function must be the first SEE call made. Pass
                the maximum number of channels or threads that will be in
                use. Use NbrChans = 1 for non-threaded applications.

                The 'Chan' parameter for subsequent calls to SEE functions
                must be in the range of 0 to NbrChans-1.

                In WIN32, up to 128 threads (numbered from 0 to 127) can be
                started, each of which can be connected to a different
                server and run independently.

                When SEE is registered, you will receive a 'KeyCode' which
                matches the 'KeyCode' within the registered DLL. For the
                shareware version, the keycode is 0.

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

       EXAMPLE

                // attach for use with non-threaded application
                Code = seeAttach(1, SEE_KEY_CODE)

      ALSO SEE  seeSmtpConnect and seePop3Connect.










     SEE4DB Reference Manual                                   Page 3


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


        SYNTAX  CLONG seeClose(CLONG)
                    // CLONG Chan : channel number

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

                SEE can not be connected to both the SMTP server and the
                POP3 server at the same time (using the same thread). Call
                seeClose to terminate one connection before connecting
                again.

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

       EXAMPLE

                // attach SEE
                Code = seeAttach(1, SEE_KEY_CODE)
                // connect to SMTP server
                Code = seeSmtpConnect(...)
                // send email with seeSendEmail
                . . .
                // close connection to SMTP server
                Code = seeClose(0)
                // connect to POP3 server
                Code = seePop3Connect(...)
                // check/read/delete our email as needed
                . . .
                // close connection to POP3 server
                Code = seeClose(0)
                // release SEE
                Code = seeRelease

      ALSO SEE  seeSmtpConnect and seePop3Connect.

















     SEE4DB Reference Manual                                   Page 4


      +----------+--------------------------------------------------------+
      | seeDebug | Returns debug information.                             |
      +----------+--------------------------------------------------------+


        SYNTAX  CLONG seeDebug(CLONG,CLONG,CSTRING,CLONG)
                    // CLONG   Chan   : Channel
                    // CLONG   Index  : Command index.
                    // CSTRING Buffer : Buffer to place text into.
                    // CLONG   BufLen : Length of above Buffer.

       REMARKS  The seeDebug function returns debug information depending
                on the value of Index.

                      SEE_GET_REGISTRATION : Gets the registration string.
                     SEE_GET_LAST_RESPONSE : Gets last server response.
                         SEE_GET_SERVER_IP : Gets server IP address in
                                             "dotted" notation.

       RETURNS Length of text placed into *Buffer*.

       EXAMPLE

                // Get the registration string from SEE32.DLL.

                Buffer = SPACE(128)

                Code = seeDebug(0, SET_GET_REGISTRATION, Buffer, 128)
                ? "Registration: " + Left(Buffer,Code)

                // Also see the SEEVER example program.

      ALSO SEE  seeStatistics.
























     SEE4DB Reference Manual                                   Page 5


      +-----------------+-------------------------------------------------+
      | seeDecodeBuffer | Decodes buffer using BASE64.                    |
      +-----------------+-------------------------------------------------+


        SYNTAX  CLONG seeDecodeBuffer(CSTRING,CSTRING,CLONG)
                    // CSTRING Coded  : Buffer of BASE64 coded chars.
                    // CSTRING Clear  : Buffer to put decoded bytes.
                    // CLONG   Length : Length of 'Coded' buffer.

       REMARKS  The seeDecodeBuffer function decodes the buffer 'Coded'
                of length 'Length' into 'Clear', returning the length in
                'Clear'.

                The buffer 'Coded' MUST contain BASE64 encoded text, as
                created by seeEncodeBuffer.

                The buffer 'Clear' will contain the ASCII or binary data
                that was encoded.

       RETURNS  Number of bytes placed in 'Clear'.

       EXAMPLE

                ClearBuffOne = SPACE(100)
                ClearBuffTwo = SPACE(100)
                CodedBuff = SPACE(134)
                NL = SPACE(2)

                NL = Chr(13) + Chr(10)

                ClearBuffOne = "SEE/POP3 Test" + NL + "Bye." + NL + Chr(0)

                Length = Len(ClearBuffOne)

                // BASE64 encode

                Length = seeEncodeBuffer(ClearBuffOne, CodedBuff, Length)

                // BASE64 decode

                Length = seeDecodeBuffer(CodedBuff, ClearBuffTwo, Length)

                // ClearBuffTwo should have same text as ClearBuffOne

      ALSO SEE  seeEncodeBuffer.











     SEE4DB Reference Manual                                   Page 6


      +----------------+--------------------------------------------------+
      | seeDeleteEmail | Deletes email from Server.                       |
      +----------------+--------------------------------------------------+


        SYNTAX  CLONG seeDeleteEmail(CLONG,CLONG)
                    // CLONG Chan   : Channel
                    // CLONG MsgNbr : message number

       REMARKS  The seeDeleteEmail function deletes the email numbered
                'MsgNbr' from the server. Note that the first email message
                is numbered 1.

                Be careful! Once an email has been deleted from the
                server, it cannot be recovered.

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

       EXAMPLE

                . . .
                ' delete message # 5 , # 6, and #7.
                Code = seeDeleteEmail(0, 5)
                if Code >= 0
                   Code = seeDeleteEmail(0, 6)
                endif
                if Code >= 0
                   Code = seeDeleteEmail(0, 7)
                endif
                . . .

      ALSO SEE  seeGetEmailCount and seeGetEmailUID.

























     SEE4DB Reference Manual                                   Page 7


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


        SYNTAX  CLONG seeDriver(CLONG)
                    // CLONG Chan : Channel

       REMARKS  The seeDriver function executes the next state in the SEE
                state engine. The purpose of this function is to allow the
                programmer to get control after the driver executes each
                SEE state.

                The seeDriver function is explicitly called only after the
                AUTO_DRIVER_CALL flag has been disabled (see function
                seeIntegerParam). If the AUTO_DRIVER_CALL flag has not been
                disabled (the default), then seeDriver does not need to be
                called.

                Refer to the section 4.0 "Theory of Operation" in the
                SMTP/POP3 Users Manual for more details on the operation of
                seeDriver.

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

       EXAMPLE

                Code
                . . .
                Code = seeSmtpConnect(...)
                . . .
                // disable automatic calling of seeDriver().
                Code = seeIntegerParam(0, AUTO_DRIVER_CALL,  0)
                Code = seeSendEmail(...)
                if Code< 0
                  ? "Error " + Str(Code)
                  return
                endif
                do while Code > 0
                  Code = seeDriver(0)
                  if Code < 0
                    ? "Error " + Str(Code)
                    return
                  endif
                  if Code = 0
                    return
                  endif
                  // do something here . . .
                enddo

      ALSO SEE  seeIntegerParam, seeSmtpConnect, and seePop3Connect.




     SEE4DB Reference Manual                                   Page 8


      +-----------------+-------------------------------------------------+
      | seeEncodeBuffer | Encodes buffer using BASE64.                    |
      +-----------------+-------------------------------------------------+


        SYNTAX  CLONG seeEncodeBuffer(CSTRING,CSTRING,CLONG)
                    // CSTRING Clear  : Buffer to put decoded bytes.
                    // CSTRING Coded  : Buffer to put BASE64 encoded.
                    // CLONG   Length : Length of 'Clear' buffer.

       REMARKS  The seeEncodeBuffer function encodes 'Clear' into
                'Coded' using Base-64 encoding.

                The 'Clear' buffer may contain any ASCII or binary data.

                The 'Coded' buffer will contain 7-bit ASCII data broken
                into lines of 76 characters followed by a carriage return
                Chr(13) and line feed Chr(10). That is, 'Coded' will
                contains multiple lines.

       RETURNS  Number of bytes in 'Coded'.

       EXAMPLE

                ClearBuffOne = SPACE(100)
                ClearBuffTwo = SPACE(100)
                CodedBuff = SPACE(134)
                NL = Buffer(2)

                NL = Chr(13) + Chr(10)

                ClearBuffOne = "SEE/POP3 Test" + NL + "Bye." + NL + Chr(0)

                Length = Len(ClearBuffOne)

                // BASE64 encode

                Length = seeEncodeBuff(ClearBuffOne, CodedBuff, Length)

                // BASE64 decode

                Length = seeDecodeBuff(CodedBuff, ClearBuffTwo, Length)

                // ClearBuffTwo should have same text as ClearBuffOne

      ALSO SEE  seeIntegerParam, seeSmtpConnect, and seePop3Connect.











     SEE4DB Reference Manual                                   Page 9


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


        SYNTAX  CLONG seeErrorText(CLONG,CLONG,CSTRING,CLONG)
                    // CLONG   Chan   : Channel Channel
                    // CLONG   Code   : Error code returned by SEE.
                    // CSTRING Buffer : Buffer to place error text.
                    // CLONG   BufLen : Length of above Buffer.

       REMARKS  The seeErrorText function is used to get the error text
                associated with an an error code as returned by one of the
                other SEE functions.

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

       EXAMPLE

                Buffer = SPACE(64)

                Code = seeSmtpConnect(...)
                if Code < 0
                   // error detected
                   Code = seeErrorText(0, Code, Buffer, 64)
                   ? Left(Buffer,Code)
                endif





























     SEE4DB Reference Manual                                   Page 10


      +----------------+--------------------------------------------------+
      | seeExtractText | Extract specified text from buffer.              |
      +----------------+--------------------------------------------------+


        SYNTAX  CLONG seeExtractText(CSTRING,CSTRING,CSTRING,CLONG)
                    // CSTRING Source  : Text buffer to search.
                    // CSTRING Text    : Text searching for.
                    // CSTRING Buffer  : Buffer for line if found.
                    // CLONG   BufSize : Size of 'Buffer'.

       REMARKS  The seeExtractText function is used to search the text
                buffer 'Source' for text 'Text'. If found, the entire line
                is copied to 'Buffer', up to a maximum of 'BufSize' bytes.

                The primary purpose of seeExtractText is to extract header
                lines from the buffer after calling seeGetEmailLines.

                The seeExtractText does not require a connection to a SMTP
                or POP3 server.

                For an example of use, see the STATUS sample program.

       RETURNS  Number of bytes placed in 'Buffer'.

       EXAMPLE

                Temp = SPACE(80)
                From = SPACE(20)

                From = "From: "
                ' search 'Source' for the line containing "From:"
                Code = seeExtractText(Source, From, Temp, 80)
                ' print line if found
                if Code > 0
                  ? Left(Temp,Code)
                endif

      ALSO SEE  seeGetEmailLines.


















     SEE4DB Reference Manual                                   Page 11


      +------------------+------------------------------------------------+
      | seeGetEmailCount | Get number of email messages on server.        |
      +------------------+------------------------------------------------+


        SYNTAX  CLONG seeGetEmailCount(CLONG)
                      // CLONG Chan : Channel Channel

       REMARKS  The seeGetEmailCount function returns the number of
                messages waiting on the server, independent of whether
                they have been previously read.

                If you have disabled the driver AUTO_CALL capability,
                the message count must be found by

                   Count = seeStatistics(Chan, SEE_GET_MSG_COUNT)

                after calling seeDriver until it returns 0. Refer to the
                STATUS sample program for an example of use.

       RETURNS  < 0 : An error has occurred. See the error list
                >=0 : The number of email messages waiting (if AUTO_CALL
                      was disabled).

       EXAMPLE

                // connect to POP3 server
                Code = seePop3Connect(...)
                // get # messages waiting
                Code = seeGetEmailCount(0)
                ? Str(Code) + "  messages waiting"

      ALSO SEE  seeGetEmailLines.
























     SEE4DB Reference Manual                                   Page 12


      +-----------------+-------------------------------------------------+
      | seeGetEmailFile | Read email message and save to a file.          |
      +-----------------+-------------------------------------------------+


        SYNTAX  CLONG seeGetEmailFile(CLONG,CLONG,CSTRING,...,CSTRING)
                    // CLONG   Chan      : channel number
                    // CLONG   MsgNbr    : header #
                    // CSTRING EmailName : email filename
                    // CSTRING EmailDir  : directory for email
                    // CSTRING AttachDir : directory for attachments

       REMARKS  The seeGetEmailFile reads the email message 'MsgNbr',
                saving it to disk as filename 'EmailName' in directory
                'EmailDir', and saving MIME attachments to directory
                'AttachDir'.

                Be sure that the specified directories exist before calling
                this function. Use '.' to specify the current directory.

                Also note that a older file of the same name as being saved
                will be overwritten by the newer file.


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

       EXAMPLE

                ' read message 1 and save as MYMAIL.TXT in
                ' the current directory

                Code = seeGetEmailFile(0, 1, "mymail.txt", ".", ".")
                if Code < 0
                  ... handle error code
                endif

      ALSO SEE  seeGetEmailLines.




















     SEE4DB Reference Manual                                   Page 13


      +------------------+------------------------------------------------+
      | seeGetEmailLines | Read lines from email message.                 |
      +------------------+------------------------------------------------+


        SYNTAX  CLONG seeGetEmailLines(CLONG,...,CLONG,CSTRING,CLONG )
                    // CLONG   Chan   : Channel Channel
                    // CLONG   MsgNbr : message #
                    // CLONG   Lines  : # lines
                    // CSTRING Buffer : buffer for email
                    // CLONG   Size   : size of buffer

       REMARKS  The seeGetEmailLines function reads all header lines plus
                the number of body lines specified by the 'Lines' argument
                into 'Buffer', up to a maximum of 'Size' bytes.

                The primary purpose of this function is to read the header
                lines without having to read the entire message.

                If you have disabled the driver AUTO_CALL capability,
                the size must be found by

                   Count = seeStatistics(Chan, SEE_GET_BUFFER_COUNT)

                after calling seeDriver until it returns 0.

                See the STATUS sample code for an example of use.

       RETURNS  < 0 : An error has occurred. See the error list.
                >=0 : The number of bytes read (if AUTO_CALL
                      was disabled).

       EXAMPLE

                Buffer = SPACE(1024)
                . . .
                ' read header lines for email # 1
                Code = seeGetEmailLines(0,1,0,Buffer,1024)

      ALSO SEE  seeGetEmailFile

















     SEE4DB Reference Manual                                   Page 14


      +-----------------+-------------------------------------------------+
      | seeGetEmailSize | Get size of email message in bytes.             |
      +-----------------+-------------------------------------------------+


        SYNTAX  CLONG seeGetEmailSize(CLONG,CLONG)
                    // CLONG Chan   : channel number
                    // CLONG MsgNbr : message number

       REMARKS  The seeGetEmailSize function returns the size in bytes of
                the specified message # 'MsgNbr'.

                seeGetEmailSize returns the size of the entire email
                message, including any attachments. Note that attachments
                will be encoded (MIME, UUENCODE, etc.), and thus take up
                more room than after they are decoded.

                If you have disabled the driver AUTO_CALL capability,
                the size must be found by

                   Count = seeStatistics(Chan, SEE_GET_MSG_SIZE)

                after calling seeDriver until it returns 0.

                See the READER sample code for an example of use.

       RETURNS  < 0 : An error has occurred. See the error list
                >=0 : The size of the email in bytes on the server
                      (if AUTO_CALL was disabled).

       EXAMPLE  long FileSize;
                . . .
                // get size of email message # 3
                FileSize = seeGetEmailSize(0, 3)


      ALSO SEE  seeGetEmailCount.




















     SEE4DB Reference Manual                                   Page 15


      +----------------+--------------------------------------------------+
      | seeGetEmailUID | Get user ID from the server.                     |
      +----------------+--------------------------------------------------+


        SYNTAX  CLONG seeGetEmailUID(CLONG,CLONG,CSTRING,CLONG)
                    // CLONG   Chan   : channel number
                    // CLONG   MsgNbr : message (-1 for all) #
                    // CSTRING Buffer : pointer to Buffer
                    // CLONG   BufLen : size of buffer

       REMARKS  The seeGetEmailUID function is used to ask the POP3 server
                for the unique user ID string for a particular email
                message, or for all email messages on the server.

                The UID string is always the same for a particular email
                message, regardless of the email message number.

                Most POP3 servers can provide such a unique ID string. A
                few POP3 servers do not provide ID strings.

       RETURNS  < 0 : An error has occurred. See the error list
                >=0 : The number of bytes in moved into 'Buffer'.
                      (if AUTO_CALL was disabled).

       EXAMPLE

               Buffer = SPSACE(2048)

               // get list of UID's for all mail on the server.
               Code = seeGetEmailUID(0, -1, Buffer, 2048)

      ALSO SEE  seeGetEmailCount.
























     SEE4DB Reference Manual                                   Page 16


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


        SYNTAX  CLONG seeIntegerParam(CLONG,CLONG,CLONG)
                    // CLONG Chan      : channel number
                    // CLONG ParmIndex : parameter index (see below).
                    // CLONG ParmValue : value of parameter to set.

       REMARKS The seeIntegerParam is used to set an integer parameter
                which controls the operation of SEE4DB.  For more information,
                refer to the Users Manual. All times are in milliseconds.
                Pass 1 for TRUE (or YES) and 0 for FALSE (or NO).

                        Parameter Name     Default
                 SEE_MIN_RESPONSE_WAIT  :  0
                 SEE_MAX_RESPONSE_WAIT  :  25000
                     SEE_MIN_LINE_WAIT  :  0
                     SEE_MAX_LINE_WAIT  :  25000
                      SEE_CONNECT_WAIT  :  60000
                  SEE_QUOTED_PRINTABLE  :  0
                  SEE_AUTO_CALL_DRIVER  :  1
                        SEE_FILE_PREFIX :  0
                         SEE_SLEEP_TIME :  50

                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 occurs 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.

                (continued on next page)















     SEE4DB Reference Manual                                   Page 17


                SEE_QUOTED_PRINTABLE controls whether messages are or are
                not encoded as quoted-printable. Use QUOTED_OFF (0) to
                disable quoting, QUOTED_PLAIN (1) to enable normal quoting,
                and QUOTED_HTML (2) to enabled quoting of embedded HTML
                text.

                SEE_AUTO_CALL_DRIVER controls whether seeDriver is called
                automatically (to completion) after seeSmtpConnect or
                seePop3Connect has been called. Refer to the Users manual
                for more details on the operation of seeDriver.

                SEE_SLEEP_TIME is the time SEE sleeps when waiting on a
                winsock.

                SEE_FILE_PREFIX controls whether "1-", "2-", etc. is
                prefixed to the filename of each attachment. If two
                attachments are named FILEONE.ZIP and FILETWO.ZIP, they
                will be saved as 1-FILEONE.ZIP and 2-FILETWO.ZIP.

                Note that Windows 3.1 may truncate long filenames.

                This feature should always be used unless you are
                downloading to a directory specifically for downloaded
                attachments.

       EXAMPLE

                // enable quoting
                Code = seeIntegerParam(Chan, SEE_QUOTED_PRINTABLE, 1)

                // disable auto call feature
                Code = seeIntegerParam(Chan, SEE_AUTO_CALL_DRIVER, 0)

                // enable attachment file prefixes
                Code = seeIntegerParam(Chan, SEE_FILE_PREFIX, 1)

                // set maximum response wait to 45 seconds
                Code = seeIntegerParam(Chan, SEE_MAX_RESPONSE_WAIT, 45000)


      ALSO SEE  seeStringParam.
















     SEE4DB Reference Manual                                   Page 18


      +----------------+--------------------------------------------------+
      | seePop3Connect | Connects to POP3 Server.                         |
      +----------------+--------------------------------------------------+


        SYNTAX  CLONG seePop3Connect(CLONG,CSTRING,CSTRING,CSTRING)
                    // CLONG   Chan    : channel number
                    // CSTRING Pop3Ptr : Pop3 server name
                    // CSTRING UserPtr : POP3 user name
                    // CSTRING PassPtr : POP3 password

       REMARKS  The seePop3Connect function establishes a connection with
                the POP3 server as specified by the Server argument.

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

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

                SEE can not be connected to both the SMTP server and the
                POP3 server at the same time. Call seeClose to terminate
                one connection before connecting again.

                Refer to the SEE4DB Users Manual for more information.

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

       EXAMPLE

                Code = seePop3Connect(0,
                          "mail.myisp.com",  // POP3 server
                          "billbob",         // user
                          "xxx")             // password

      ALSO SEE  seeSmtpConnect and seeClose.


















     SEE4DB Reference Manual                                   Page 19


      +------------+------------------------------------------------------+
      | seeRelease | Releases SEE.                                        |
      +------------+------------------------------------------------------+


        SYNTAX  CLONG seeRelease(CVOID)

       REMARKS  The seeRelease function releases the SEE system. This
                should be the very last function called.

                seeClose should be called for all channels before calling
                seeRelease.

       RETURNS  < 0 : An error has occurred. Call seeErrorText.

       EXAMPLE

                // Initialize SEE for one channel (# 0).
                Code = seeAttach(1, SEE_KEY_CODE)

                //
                // call any SEE function except seeAttach and seeRelease.
                //

                // close channel 0
                Code = seeClose(0)
                // Terminate SEE
                Code = seeRelease()

      ALSO SEE seeAttach.



























     SEE4DB Reference Manual                                   Page 20


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


        SYNTAX  CLONG seeSendEmail(CLONG,CSTRING,...,CSTRING)
                    // CLONG   Chan   : channel number
                    // CSTRING To     : recipient, separated by commas.
                    // CSTRING CC     : CC list, separated by commas.
                    // CSTRING BCC    : BCC list, separated by commas.
                    // CSTRING Subj   : subject text.
                    // CSTRING Msg    : message or message filename.
                    // CSTRING Attach : file attachment.

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

                Note that all email addresses (in To, CC, and BCC strings)
                must be bracketed. For example:

                   "Mike M<mike@marshallsoft.com>"

                The CC and BCC strings may contain multiple email
                addresses, separated 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.

                'Attach' may contain one or more attachments, separated by
                commas. For example,

                   "file1.zip,file2.doc".

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

       EXAMPLE

              seeSendEmail(0,
                           "<myfriend@hisisp.com>", // recipient
                           "",                      // CC list
                           "",                      // BCC list
                           "Hello",                 // subject
                           "Call me ASAP!",         // message
                           "")                      // attachment

      ALSO SEE  seeSmtpConnect.







     SEE4DB Reference Manual                                   Page 21


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


        SYNTAX  CLONG seeSmtpConnect(CLONG,CSTRING,CSTRING,CSTRING)
                    // CLONG   Chan    : channel number
                    // CSTRING Server  : SMTP server.
                    // CSTRING From    : your email addr in brackets.
                    // CSTRING ReplyTo : email address to reply to.

       REMARKS  The seeSmtpConnect 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 M<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.

                SEE can not be connected to both the SMTP server and the
                POP3 server at the same time. Call seeClose to terminate
                one connection before connecting again.

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

       EXAMPLE

                seeSmtpConnect(0,
                               "mail.myisp.com",   // my SMTP server
                               "<me@myisp.com>",   // my email address
                               "")                 // no Reply-To

                seeSmtpConnect(0,
                               "mail.myisp.com",   // my SMTP server
                               "<me@myisp.com>",   // my email address
                               "<him@himisp.com>)  // Reply-To address

      ALSO SEE  seeClose.








     SEE4DB Reference Manual                                   Page 22


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


        SYNTAX  CLONG seeStatistics(CLONG,CLONG)
                    // CLONG Chan  : channel number
                    // CLONG Index : specifies which statistic.

       REMARKS  The seeStatistics function is used to return runtime
                statistics in the SEE DLL. The values of 'Index' are
                defined in SEE16.CC and SEE32.CC as follows:

                      SEE_GET_VERSION : Gets the SEE version number.
                   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.
                         SEE_GET_MSG_COUNT : Gets # emails waiting.
                          SEE_GET_MSG_SIZE : Gets size of email.
                      SEE_GET_BUFFER_COUNT : Gets # bytes in buffer for
                                             seeGetEmailLines.
                    SEE_GET_CONNECT_STATUS : Returns TRUE if connected.
                     SEE_GET_VERIFY_STATUS : Returns seeVerifyUser status.
                      SEE_GET_ATTACH_COUNT : Gets # attachments received.

                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 READER example.

       EXAMPLE

                ' get total message and attachment bytes transmitted.

                Code = seeStatistics(0, SEE_GET_TOTAL_BYTES_SENT)

      ALSE SEE  seeDriver, seeIntegerParam, and seeStringParam.







     SEE4DB Reference Manual                                   Page 23


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


        SYNTAX  CLONG seeStringParam(CLONG,CLONG,CSTRING)
                    // CLONG   Chan        : channel number
                    // CLONG   ParamName   : index of parameter.
                    // CSTRING ParamString : parameter string.

       REMARKS  The seeStringParam function is used to set a string
                parameter as defined in SEE16.CC and SEE32.CC. For more
                information, refer to the Users Manual.

                   SEE_LOG_FILE   : Specifies the log filename.
                   SEE_SET_REPLY  : Sets the "Reply To" string.
                   SEE_SET_HEADER : Adds header line(s).

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

                Use SEE_SET_REPLY to change the "Reply-To:" header after
                connecting to the server, just before sending an email.

                Use SEE_SET_HEADER to add one or more header lines. Each
                header line except the last should end with a carriage
                return line feed pair.

       EXAMPLE

                X = SPACE(100)

                ' specify a log file.

                Code = seeStringParam(0, SEE_LOG_FILE, "mytest.log")

                ' specify "Reply-To:" address

                Code = seeStringParam(0, SEE_SET_REPLY, "<bill@myisp.com>")

               ' add our header lines
               X="X-Priority: Normal"+CHR(13)+CHR(10)+ "Sender: FromUs"
               Code = seeStringParam(0, SEE_SET_HEADER, X)

      ALSO SEE  seeIntegerParam.











     SEE4DB Reference Manual                                   Page 24


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


        SYNTAX  CLONG seeVerifyFormat(CSTRING)
                    // CSTRING Text : email address to check.

       REMARKS  The seeVerifyFormat function is used 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

                Buffer = SPACE(80)

                . . .

                Code = seeVerifyFormat("Billy E. Bob<beb@hisasp.com>")
                if Code < 0
                   Code = seeErrorText(0,Code,Buffer,80)
                   ? "Email address error : " + Left(Buffer,Code)
                endif

      ALSO SEE  seeErrorText.

























     SEE4DB Reference Manual                                   Page 25


      +---------------+---------------------------------------------------+
      | seeVerifyUser | Verify email address.                             |
      +---------------+---------------------------------------------------+


        SYNTAX  CLONG seeVerifyUser(CLONG,CSTRING)
                    // CLONG   Chan : channel number
                    // CSTRING Text : email address to verify.

       REMARKS  The seeVerifyUser function is used to verify an individual
                email address with the email server which "owns" the email
                address.

                seeVerify will connect to the specified server and request
                verification of the user. Some SMTP servers may refuse
                connection of any client not directly connected to them or
                may refuse all "verify user" requests. Web based email
                servers such as hotmail.com may refuse all SMTP
                connections.

                Note that you connect to the remote SMTP server rather than
                the SMTP server that you use to send email.

                For example, to verify msc@traveller.com, you must first
                connect to the SMTP server "mail.traveller.com" then call
                SeeVerifyUser("msc").


       EXAMPLE

                SmtpServer = SPACE(65)
                User       = SPACE(40)
                Buffer     = SPACE(128)

                SmtpServer = "mail.traveller.com"
                Usr  = "msc"

                Code = seeSmtpConnect(0,SmtpServer, ...)
                . . .
                Code = seeVerifyUser(0,UserPtr)
                if Code = 0
                  ' display last server response
                  Code =  seeDebug(0,SEE_GET_LAST_RESPONSE, Buffer, 128)
                  ? Left(User,Code) + " is NOT verified"
                else
                  ? Left(User,Code) + " is verified"
                endif

      ALSO SEE  seeErrorText and seeDebug.








     SEE4DB Reference Manual                                   Page 26

