Download MCM4XB Reference Manual - MarshallSoft Computing

MarshallSoft Client Mailer
Library for Xbase++
Reference Manual
(MCM4XB)
Version 5.0
October 28, 2014
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 2014
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Email: [email protected]
Web: www.marshallsoft.com
MARSHALLSOFT is a registered trademark of MarshallSoft Computing.
1
TABLE OF CONTENTS
1 Introduction
1.1 General Remarks
1.2 MCM Files
1.3 Documentation Set
2 Library Overview
2.1 mcmAttach
2.2 mcmGetError
2.3 mcmGetInteger
2.4 mcmGetInteger2
2.5 mcmGetLetterMacro
2.6 mcmGetListMacro
2.7 mcmGetString
2.8 mcmGetString2
2.9 mcmLoadString
2.10 mcmMergeNext
2.11 mcmMergeText
2.12 mcmOpenBounce
2.13 mcmOpenHeader
2.14 mcmOpenLetter
2.15 mcmOpenList
2.16 mcmOpenReply
2.17 mcmOpenSkip
2.18 mcmPop3Close
2.19 mcmPop3Connect
2.20 mcmReadReply
2.21 mcmRelease
2.22 mcmSendMail
2.23 mcmSetInteger
2.24 mcmSetProxySSL
2.25 mcmSetString
2.26 mcmSleep
2.27 mcmSmtpClose
2.28 mcmSmtpConnect
2.29 mcmStatistics
2.30 mcmUtility
2.31 mcmWriteToLog
3 MCM Error List
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
3
3
3
5
5
6
7
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
2
1 Introduction
The MarshallSoft Client Mailer for Xbase provides the capability to send personalized email to your
clients or customers directly from your Xbase++ application program. The “MarshallSoft Client Mailer
for Xbase Reference Manual” contains details on each individual MCM function.
The most current version of the MarshallSoft Client Mailer for Xbase can be found at
http://www.marshallsoft.com/mcm4xb.htm
1.1 General Remarks
This is the Xbase++ version of the MarshallSoft Client Mailer (MCM). Other versions are for C/C++, Delphi,
Visual Basic, Visual dBase, and Visual FoxPro. All versions employ the identical MCM32.DLL differing
only in documentation and example programs.
All MarshallSoft Client Mailer (MCM) functions return an integer code. Negative values are always errors.
Refer to Section 3.0 below, "MCM Error Return Code List". The file XmcmErrors.txt contains a list of all
error codes and their corresponding numerical value.
Non-negative return codes are never errors. Note that the XmcmErrorText function is used to get the text
message associated with any error code.
1.2 MCM Files (Xbase)
•
•
•
mcm32.ch
mcm32.dll
*.prg
MCM function declaration & constants file.
32-bit MarshallSoft Client Mailer DLL.
Xbase example programs.
3
1.3 Documentation Set
There are five manuals in Adobe PDF format for the MarshallSoft Client Mailer.
•
•
•
•
•
Tutorial Manual: Introduces the basic functionality and overview of the MarshallSoft Client Mailer.
Servers Manual: Covers background information on SMTP & POP3 servers.
User Manual: Covers information that is not programming language specific (letter & list preparation,
program logic, purchasing, performance, SSL, etc.).
Reference Manual: Contains details for each individual MCM function specific for each programming
language (Xbase++, Visual FoxPro, Delphi, C/C++, VB, etc.).
Programmer Manual: Contains programming language (Xbase++, Visual FoxPro, Delphi, C/C++, etc.)
specific information such as compiling and running example programs.
The manuals can be found in the DOCS subdirectory/folder in the MarshallSoft Client Mailer file structure
when it is installed. Note that for clarity purposes some information may have been provided in more than one
manual.
• Tutorial Manual:
mcm_tutorial.pdf or online at
http://www.marshallsoft.com/mcm_tutorial.pdf.
• Servers Manual:
mcm_servers.pdf or online at
http://www.marshallsoft.com/mcm_servers.pdf.
• User Manual:
mcm_users.pdf or online at
http://www.marshallsoft.com/mcm_users.pdf.
• Reference Manuals mcm4xb_reference.pdf or
online at http://www.marshallsoft.com/mcm4xb_reference.pdf.
• Programmer Manuals mcm4xb_programmer.pdf or
online at http://www.marshallsoft.com/mcm4xb_programmer.pdf
Links to the above manuals can also be found online on the MarshallSoft Client Mailer for Xbase++
product page http://www.marshallsoft.com/mcm4xb.htm
4
2.0 MCM Functions
All MCM functions are declared in file MCM32.CH
2.1 XmcmAttach: Initialize MarshallSoft Client Mailer.
SYNTAX
Code = XmcmAttach(KeyCode,EditionCode,ChansWanted,DebugLevel,@PathToMCM)
KeyCode
EditionCode
ChansWanted
DebugLevel
PathToMCM
:
:
:
:
:
MCM key code (identifies purchaser)
MCM edition code (no longer used)
Maximum # channels requested.
Debug level (0=OFF, 1=LOW, 2=HIGH)
Pathname of files folder.
REMARKS
The XmcmAttach function initializes the Client-Mailer DLL (MCM32.DLL), passing the initialization
parameters (1) KeyCode [0 for the evaluation version], (2) Edition Code [pass 0], (3) the maximum number of
channels to use when sending email, and (4) the debug level; 0 for no debug, 1 for low, and 2 for high, and (5)
PathToMCM, the pathname of the log file folder.
A keycode file (keycode.ch) containing the customer's keycode is included when MCM4XB is purchased.
XmcmAttach must be the first MarshallSoft Client Mailer (MCM) function called, excepting mcmUtility.
RETURNS
Evaluation: # days remaining in the evaluation (trial) period.
Purchased: 999
EXAMPLE CODE
KeyCode = 0
EditionCode = 0
ChansWanted = 24
PathToMCM = "c:\mcm4xb\apps"
Code = XmcmAttach(KeyCode,EditionCode,Chanswanted,MCM_DEBUG_OFF,@PathToMCM)
EXAMPLE PROGRAMS
TestMCM, SendMail and GetReply
5
2.2 XmcmGetError: Get text associated with error code.
SYNTAX
Code = XmcmGetError(ErrCode, @Buffer, BufLen)
ErrCode : (INTEGER) Error code.
Buffer : (STRING) Error text buffer.
BufLen : (INTEGER) Size of buffer.
REMARKS
The XmcmGetError function is used to copy the error text associated with the error code 'ErrCode' returned
by a MCM function to the buffer, where it can be displayed by the calling program code.
The size of the buffer should be 256 bytes.
RETURNS
Return = 0 : No such error.
Return < 0 : The number of bytes copied into the buffer.
EXAMPLE CODE
Buffer = Space(256)
if ErrCode < 0
* get MCM error message
Code = XmcmGetError(ErrCode, @Buffer, 255)
. . .
EXAMPLE PROGRAMS
SendMail and GetReply
6
2.3 XmcmGetInteger: Gets MCM processing information.
SYNTAX
Code = XmcmGetInteger(ParmName)
ParmName : (INTEGER) Parameter number.
REMARKS
The XmcmGetInteger function returns an integer whose value depends on the value of the passed parameter
'ParamName' as follows.
RETURNS
MCM_GET_VERSION : The version of MCM in packed hexadecimal format (X.Y.Z)
MCM_GET_VERSION_1ST_PART : The first digit of the version of MCM.
MCM_GET_VERSION_2ND_PART : The second digit of the version of MCM.
MCM_GET_VERSION_3RD_PART : The third digit of the version of MCM.
MCM_GET_BUILD : The build number of MCM.
MCM_GET_LETTER_LINE_NBR : The current letter line just processed.
MCM_GET_LETTER_CHAR_POS : The current character position on the current letter line.
MCM_GET_LETTER_MACROS : The number of macros (substitution strings) found in the letter.
MCM_GET_LIST_LINE_NBR : The current list line just processed.
MCM_GET_MAX_LIST_SIZE : The maximum number of entries allowed in the list of recipients.
MCM_GET_MAX_CHANNELS : The number of channels being used to send email.
MCM_GET_CUSTOMER_ID: The customer ID.
MCM_GET_ALLOWED_CHANNELS: The maximum allowed number of channels.
MCM_GET_ALLOWED_LIST_SIZE: The maximum allowed list size.
MCM_GET_ALLOWED_SKIP_FILES: The maximum allowed number o skip files.
MCM_GET_ALLOWED_REPLY_FILES: The maximum number of reply files.
MCM_GET_EDITION: The MCM edition (no longer used).
MCM_GET_REGISTRATION: The customer registration string.
7
MCM_GET_CHANNEL_STATUS : The current channel status where each bit represents one channel.
MCM_GET_EMAIL_QUEUED_COUNT : The number of emails queued to be sent.
MCM_GET_EMAIL_SENT_COUNT : The number of emails successfully sent.
MCM_GET_EMAIL_ERROR_COUNT : The number of emails queued but not sent due to errors.
MCM_GET_LIST_LINES : The number of lines in the list file.
MCM_GET_LETTER_LINES : The number of lines in the letter file.
MCM_GET_SKIP_LINES : The number of lines in last skip file loaded.
MCM_GET_LIST_MACRO_COUNT : The number of macros (substitution strings) in the recipient list.
MCM_GET_LIST_DELIMITER : The macro (substitution string) delimiter. This will be either the comma,
semicolon, tab, carrot ^, or tilde ~.
MCM_GET_LIST_ERROR_STRING : The line number of last error in the recipient list.
MCM_GET_SKIP_FILE_LIMIT : The maximum number of skip files allowed.
MCM_GET_REPLY_FILE_LIMIT : The maximum number of reply files allowed.
EXAMPLE CODE
? "Customer ID is " + Str(XmcmGetInteger(MCM_GET_CUSTOMER_ID))
EXAMPLE PROGRAM
SendMail
8
2.4 XmcmGetInteger2: Get information for macro processing.
SYNTAX
Code = XmcmGetInteger2(ParmName, Selected)
ParmName : (INTEGER) Parameter number.
Select
: (INTEGER) Selection number for ParamName.
REMARKS
The XmcmGetInteger2 function returns an integer value corresponding to the passed parameters 'ParmName'
and 'Select'.
RETURNS
MCM_GET_LETTER_MACRO_LINE : Get the line on which the 'Select' macro appears.
EXAMPLE CODE
* get macro string i (1,2,3,...)
Buffer = Space(256)
Code = XmcmGetLetterMacro(i, @Buffer, 255)
if Code > 0
* find line in letter on which macro # i occurs
Code = XmcmGetInteger2(MCM_GET_LETTER_MACRO_LINE, i)
? "Macro " + Buffer + " defined on line " + Str(Code)
EXAMPLE PROGRAMS
(none)
9
2.5 XmcmGetLetterMacro: Get Macro Substitution String in Letter
SYNTAX
Code = XmcmGetLetterMacro(MacroNumber, @Buffer, BufSize )
MacroNumber : (INTEGER) Macro number (1,2,...)
Buffer
: (STRING) Macro buffer.
BufSize
: (INTEGER) Size of buffer.
REMARKS
The XmcmGetLetterMacro returns the macro (substitution string) in the letter associated with the macro
number (1,2,3,...). Macros may be up to 40 characters in length. The first macro in a letter is #1, the second is
#2, etc.
For example, consider the letter as shown in section 2.12 XmcmOpenLetter. The first macro in the letter is
"%EmailAddress%, the second is %Fullname%, etc.
RETURNS
Return > 0 : The line number (in the letter) on which macro appears.
Return < 0 : The error code MCM_NO_SUCH_MACRO.
EXAMPLE CODE
* get macro string i (1,2,3,...)
Buffer = Space(256)
Code = XmcmGetLetterMacro(i, @Buffer, 255)
if Code > 0
* find line in letter on which macro # i occurs
Code = XmcmGetInteger2(MCM_GET_LETTER_MACRO_LINE, i)
? "Macro " + Buffer + " defined on line " + Str(Code)
EXAMPLE PROGRAMS
(none)
ALSO SEE
XmcmGetListMacro
10
2.6 XmcmGetListMacro: Get Macro Substitution String in Recipient List
SYNTAX
Code = XmcmGetListMacro(ListNumber, @Buffer, BufSize)
MacroNumber : (INTEGER) Macro number (1,2,...)
Buffer
: (STRING) Macro buffer.
BufSize
: (INTEGER) Size of buffer.
REMARKS
The XmcmGetListMacro returns the macro (substitution string) in the recipient list associated with the macro
number (1,2,3,...). Macros may be up to 40 characters in length, and are defined on the first line of the list.
For example, consider the recipient list as shown in section 2.13 XmcmOpenList. There are three macros
(always appearing on the first line) in the list. The first macro is %EmailAddress%, the second is
%AppointmentTime%, and the third is %Fullname%.
XmcmGetListMacro is called by the application code that sends the email such as the SendMail example
program.
RETURNS
Return > 0 : The macro index.
Return < 0 : The error code MCM_NO_SUCH_MACRO.
EXAMPLE CODE
* get list macro i (1,2,3,...)
Buffer = Space(256)
Code = XmcmGetListMacro (i, @Buffer, 255)
if Code > 0
? "Macro = " + Buffer
EXAMPLE PROGRAMS
(none)
ALSO SEE
XmcmGetLetterMacro
11
2.7 XmcmGetString: Gets string parameter for MCM processing.
SYNTAX
Code = XmcmGetString(ParmName, @Buffer, BufSize)
ParmName : (INTEGER) Parameter number
Buffer
: (STRING) String buffer.
BufSize : (INTEGER) Size of buffer.
REMARKS
The XmcmGetString function returns a string which contents depends on the value of the passed parameter
'ParmName' as follows. Note that MCM reads only the headers of incoming email.
MCM_GET_VERSION : Copies the MCM version string into 'Buffer'.
MCM_GET_LETTER : Copies the entire letter into 'Buffer'. Requires SMTP connection.
MCM_GET_SUBJECT : Copies the letter subject into 'Buffer'. Requires SMTP connection.
MCM_GET_BODY : Copies the body of the letter into 'Buffer'. Requires SMTP connection.
MCM_GET_FROM : Copies the "From:" address into 'Buffer'. Requires SMTP connection.
MCM_GET_TIME_STAMP : Copies the current date & time string into 'Buffer'.
MCM_GET_LAST_EMAIL_SENT : Copies address of last email sent into 'Buffer'.
MCM_GET_RECIPIENT : Copies email address of last recipient.
RETURNS
The number of characters copied.
EXAMPLE CODE
Work = Space(4096)
Code = XmcmGetString(MCM_GET_LETTER, @Work, 4095)
if Code > 0
EXAMPLE PROGRAMS
SendMail and GetReply
ALSO SEE
XmcmGetString2, XmcmGetInteger, and XmcmGetInteger2
12
2.8 XmcmGetString2: Gets string parameter for MCM processing.
SYNTAX
Code = XmcmGetString2(ParmName, Selection, @Buffer, BufSize)
ParmName :
Selection:
Buffer
:
BufSize :
(INTEGER)
(INTEGER)
(STRING)
(INTEGER)
Parameter number
Selection index (1,2,...)
String buffer.
Size of buffer.
REMARKS
The mcmGetString2 function returns a string which contents depends on the value of the passed parameter
'ParamName' as follows. Note that MCM reads only the headers of incoming email.
MCM_GET_BOUNCE_STRING : Copies the selected 'bounce' string into 'Buffer'. The bounce string must
have been previously set by mcmSetString(MCM_ADD_BOUNCE_STRING, String).
Bounce strings are numbered 1,2,...
RETURNS
The number of characters copied.
EXAMPLE CODE
Work = Space(256)
Code = XmcmGetString(MCM_GET_BOUNCE_STRING, 1, @Work, 255)
if Code > 0
EXAMPLE PROGRAMS
GetReply
ALSO SEE
XmcmGetString, XmcmGetInteger, and XmcmGetInteger2
13
2.9 XmcmLoadString: Load substitution string.
SYNTAX
Code = XmcmLoadString(StringKey, StringText)
StringKey : (STRING) String key.
StringText : (STRING) String text.
REMARKS
The XmcmLoadString loads the substitution string for advanced macros.
Advanced macros are not currently implemented in MCM.
RETURNS
< 0 : Error (see Section 3.0 MCM Error List)
> 0 : No error
EXAMPLE CODE
(none)
EXAMPLE PROGRAMS
(none)
14
2.10 XmcmMergeNext: Merge next recipient for sending.
SYNTAX
Code = XmcmMergeNext()
REMARKS
The XmcmMergeNext function merges the next recipient from the recipient list with the loaded letter in
preparation for sending.
See the XmcmMergeText function for a list of the merge codes.
XmcmMergeNext is called by the application code that sends the email such as the SendMail example
program.
RETURNS
< -1 Error (see Section 3.0 MCM Error List)
= -1 End-of-file (MCM_EOF)
= 0 OK to send
> 0 Don't send (see XmcmMergeText)
EXAMPLE CODE
* send letter to each recipient
for I = 1 To 1000
* merge letter with next recipient
MergeCode = XmcmMergeNext()
EXAMPLE PROGRAMS
GetReply
ALSO SEE
XmcmMergeText
15
2.11 XmcmMergeText: Get text for associated merge code.
SYNTAX
Code = XmcmMergeText(MergeCode, @Buffer, BufSize)
MergeCode : (INTEGER) Merge code.
Buffer
: (STRING) String buffer.
BufSize
: (INTEGER) Size of buffer.
REMARKS
The XmcmMergeText function copies the merge code text corresponding with the numerical 'MergeCode' to
'Buffer' so that it can be displayed by the calling application program.
Recall that if the value returned by the XmcmMergeNext function (called the "merge code") is positive, then
email should not be sent to this particular recipient. The numerical values of the merge codes are listed in
Xmcm.h and include
MCM_MERGE_INVALID_ADDRESS : Invalid email address
MCM_MERGE_DUPLICATE_ADDRESS : Duplicate email address
MCM_MERGE_BRACKETS_NOT_ALLOWED : '<' and '>' not allowed in email address
MCM_MERGE_CANNOT_OPEN_ATTACH : Cannot open attachment
MCM_MERGE_UNKNOWN_CHARSET : Unknown character set
MCM_MERGE_EMTY_MACRO_STRING : Empty macro string found in recipient list.
In addition, merge codes between 1 and 24 indicate that the email address was found in a skip (exclusion) list:
MergeCode = 1: Email address was found in skip list #1
...
MergeCode = 24: Email address was found in skip list #24
XmcmMergeText is called by the application code that sends the email such as the SendMail example
program.
RETURNS
Number of characters copied to 'Buffer'.
EXAMPLE CODE
Buffer = Space(256)
if MergeCode > 0
Code = XmcmMergeText(MergeCode, @Buffer, 255)
? Buffer
EXAMPLE PROGRAMS
GetReply
ALSO SEE
XmcmMergeNext and XmcmOpenSkip
16
2.12 XmcmOpenBounce: Open bounce file for processing.
SYNTAX
Code = XmcmOpenBounce(@PathName)
PathName : (STRING) Pathname of bounce file.
REMARKS
The XmcmOpenBounce opens the "bounce" file, into which are written (when checking for client replies) the
email addresses that have been returned as undeliverable (bounced).
This file is created when reading replies (see the GetReply.prg example program) after previously sending
email (see the SendMail.prg example program) and can be used as one of the "skip files" the next time email
is sent.
XmcmOpenBounce is called by the application code that reads replies to previously sent email, such as the
GetReply example program.
RETURNS
< 0 : Error (see Section 3.0 MCM Error List)
> 0 : Bounce file successfully opened.
EXAMPLE CODE
BounceFile = "c:\mcm4xb\apps\bounce.txt"
Code = XmcmOpenBounce(@BounceFile)
EXAMPLE PROGRAMS
GetReply
ALSO SEE
XmcmOpenSkip
17
2.13 XmcmOpenHeader: Open header file for processing.
SYNTAX
Code = XmcmOpenHeader(@HeaderName)
HeaderName : (STRING) Filename of letter header file.
REMARKS
The XmcmOpenHeader file opens the letter header file and scans for macros. An example of a header file is:
To: %EmailAddress%
Subject: Your Dental Appointment
Required headers are:
To:
Subject:
Email recipient
Email subject
Optional header lines are:
CharSet:
CC:
BCC:
Attach:
Header:
Character set
Carbon copy recipients
Blind carbon copy recipients
List of attachments
User specified SMTP header
Refer to the MCM User's manual (mcm_users.pdf) for details of all headers.
RETURNS
< 0 : Error (see Section 3.0 MCM Error List)
> 0 : Letter file successfully opened.
EXAMPLE CODE
HeaderFile = "c:\mcm4xb\apps\header.txt"
Code = XmcmOpenHeader(@HeaderFile)
EXAMPLE PROGRAMS
SendMail
ALSO SEE
XmcmOpenLetter
18
2.14 XmcmOpenLetter: Open letter file for processing.
SYNTAX
Code = XmcmOpenLetter(@LetterName)
LetterName : (STRING) Filename of letter file.
REMARKS
The XmcmOpenLetter file opens the (text or HTML) letter file and scans the letter for macros. An example
of a letter is:
Dear %FullName%,
Your dental appointment is tomorrow at %AppointmentTime%.
Sincerely,
Dr. John H. Holliday
PS: If you prefer that email notices not be sent, reply
to this email with subject "REMOVE %EmailAddress%"
XmcmOpenLetter is called by the application code that sends the email such as the SendMail example
program.
RETURNS
< 0 : Error (see Section 3.0 MCM Error List)
> 0 : Letter file successfully opened.
EXAMPLE CODE
LetterFile = "c:\mcm4xb\apps\letter.txt"
Code = XmcmOpenLetter(@LetterFile)
EXAMPLE PROGRAMS
SendMail
ALSO SEE
XmcmOpenHeader
19
2.15 XmcmOpenList: Open recipient list file for processing.
SYNTAX
XmcmOpenList(@ListPathName)
ListPathName : (STRING) Pathname of (recipient) list file.
REMARKS
The XmcmOpenList file opens the recipient list file, the first line of which contains the macro substitution
string. For example,
EmailAddress,
[email protected],
[email protected],
[email protected],
AppointmentTime,
10:00 am,
Noon,
2:30 pm,
FullName
Mike Marshall
Paula Marshall
Lacy Marshall
Although the comma is used in the above example as the delimiter character, the semicolon, tab, carrot ^,
or tilde ~ could be used instead.
Rewind the recipient list file by passing a NULL or empty string for ListPathName. This allows a second pass
through the list to send email when a first pass was a "merge-only" pass.
RETURNS
< 0 : Error (see Section 3.0 MCM Error List)
> 0 : List file successfully opened.
EXAMPLE CODE
ListFile = "c:\mcm4xb\apps\list.txt"
Code = XmcmOpenList(@ListFile)
EXAMPLE PROGRAMS
SendMail
ALSO SEE
XmcmOpenLetter
20
2.16 XmcmOpenReply: Open reply file for processing.
SYNTAX
Code = XmcmOpenReply(@RemoveFile, @RemoveString)
RemoveFile
: (STRING) Pathname of reply file.
RemoveString : (STRING) Reply string.
REMARKS
The XmcmOpenReply function opens a reply file that is associated with the specified subject string. When
reading client replies (to previously sent email), if the subject begins with the specified string, as for example,
REMOVE [email protected]
then the email address following the string ("REMOVE" in the example above) is written to the reply file.
More than one reply file can be opened.
RETURNS
< 0 : Error (see Section 3.0 MCM Error List)
> 0 : No error.
EXAMPLE CODE
RemoveFile = "c:\mcm4xb\apps\remove.txt"
RemoveString = "REMOVE"
* open file for replies on subject line "REMOVE email-address"
Code = XmcmOpenReply(@RemoveFile, @RemoveString)
EXAMPLE PROGRAMS
GetReply
ALSO SEE
XmcmOpenSkip and XmcmOpenBounce
21
2.17 XmcmOpenSkip: Open skip file for processing.
SYNTAX
Code = XmcmOpenSkip(@SkipPathName)
SkipPathName : (STRING) Pathname of skip file.
REMARKS
The XmcmOpenSkip function opens a file containing email addresses of recipients to which email should not
be sent, even if the email address appears in the list of recipients.
Typically, skip files are either a list of email addresses that were previously not deliverable or addresses of
recipients who replied to previously sent email with one of the string specified in XmcmOpenReply.
More than one skip file can be opened.
RETURNS
< 0 : Error (see Section 3.0 MCM Error List)
> 0 : No error
EXAMPLE CODE
BounceFile = "c:\mcm4xb\apps\bounce.txt"
* Open file containing addresses of undeliverable email.
Code = XmcmOpenSkip(@BounceFile)
EXAMPLE PROGRAMS
SendMail
ALSO SEE
XmcmOpenReply and XmcmOpenBounce
22
2.18 XmcmPop3Close: Close POP3 connection.
SYNTAX
Code = XmcmPop3Close()
REMARKS
The XmcmPop3Close program closes the connection to the POP3 server.
RETURNS
< 0 : Error (see Section 3.0 MCM Error List)
> 0 : No error
EXAMPLE CODE
* close POP3 connection
XmcmPop3Close()
EXAMPLE PROGRAMS
GetReply
ALSO SEE
XmcmPop3Connect
23
2.19 XmcmPop3Connect: Connect to POP3 server.
SYNTAX
Code = XmcmPop3Connect(@Server, Port, @User, @Pass )
Server
Port
User
Pass
:
:
:
:
(STRING)
(INTEGER)
(STRING)
(STRING)
POP3
POP3
POP3
POP3
server name or IP address.
port (normally 110).
user name.
password.
REMARKS
The XmcmPop3Connect function connects to the specified POP3 server for the purpose of (1) reading replies
from servers reporting than email was undeliverable and (2) reading replies from recipients.
Once connected, the number of messages in the POP3 account is returned.
Note: XmcmPop3Connect and XmcmSmtpConnect should not be called in the same program.
RETURNS
< 0 : Error (see Section 3.0 MCM Error List)
= 0 : No messages on the server.
> 0 : The number of messages on the server.
EXAMPLE CODE
* connect to POP3 server
POP3_Server = "mail.hiwaay.net"
POP3_User = "username"
POP3_Pass = "secret"
POP3_Port = 110
Code = XmcmPop3Connect(@POP3_Server, POP3_Port, @POP3_User, @POP3_Pass)
EXAMPLE PROGRAMS
GetReply
ALSO SEE
XmcmPop3Close
24
2.20 XmcmReadReply: Read next email from POP3 server.
SYNTAX
Code = XmcmReadReply(@SubjBuf, SubjLen, Flags )
SubjBuf : (STRING) Reply buffer.
SubjLen : (INTEGER) Size of buffer.
Flags
: (INTEGER) Delete flags.
REMARKS
The XmcmReadReply function reads the next email from the POP3 server, copying the subject to the
'UserBuf' buffer.
The email read is classified as one of three types:
(1) Email from servers indicating that the email was undeliverable.
(2) Email from recipients who have responded to one of the previous specified reply strings.
(3) All other email.
DeleteFlags specify if the email of the type specified in the above paragraph is to be deleted.
MCM_DELETE_BOUNCED
MCM_DELETE_MATCHED
MCM_DELETE_OTHER
1
2
4
The above Delete Codes can be added together to expand the messages deleted. For example, to specify that
only type 1 ( bounced) and type 2 (recognized replied to) emails are to be deleted, but not others, set 'Flags' to
3. Hence, Flag = 3 will delete failure (bounced) email and recognized (matched) replies but keep all other
messages. If no messages are to be deleted, use Flags = 0.
RETURNS
< 0 : Error (see Section 3.0 MCM Error List)
= 0 : No reply string matches.
> 0 : Matched reply string (1 to 24).
= 999 : Email was undeliverable.
EXAMPLE CODE
DeleteCode = MCM_DELETE_BOUNCED + MCM_DELETE_MATCHED
SubjectBuffer = Space(256)
Code = XmcmReadReply(@SubjectBuffer, 255, DeleteCode)
EXAMPLE PROGRAMS
GetReply.
ALSO SEE
25
2.21 XmcmRelease: Close down MCM.
SYNTAX
Code = XmcmRelease()
REMARKS
The XmcmRelease function closes down all MarshallSoft Client Mailer (MCM) processing and should be the
last MCM function called.
RETURNS
< 0 : Error (see Section 3.0 MCM Error List)
> 0 : No error
EXAMPLE CODE
XmcmRelease()
EXAMPLE PROGRAMS
SendMail and GetReply
26
2.22 XmcmSendMail: Sends merged mail.
SYNTAX
Code = XmcmSendMail()
REMARKS
The XmcmSendMail function sends the email created by calling XmcmMergeNext.
RETURNS
< 0 : Error (see Section 3.0 MCM Error List)
> 0 : No error
EXAMPLE CODE
* send letter to recipient
Code = XmcmSendMail()
EXAMPLE PROGRAMS
SendMail
27
2.23 XmcmSetInteger : Sets numeric parameter for MCM processing.
SYNTAX
Code = XmcmSetInteger(ParamName, ParamValue)
ParamName : (INTEGER) Parameter number
ParamValue : (INTEGER) Parameter value.
REMARKS
The XmcmSetInteger functions sets the specified integer parameter
MCM_ALLOW_EMPTY_FIELDS : Allows (1) or disallows (0) empty fields in the list of recipients, with the
exception of the first field, which is reserved for the recipient's email address (since an email address must
always be present). The default is 0 (empty fields not allowed).
MCM_SET_DEBUG_LEVEL : Changes the diagnostic debug level (initially set by mcmAttach) to
MCM_DEBUG_OFF, MCM_DEBUG_LOW, or MCM_DEBUG_HIGH.
MCM_SET_DUPLICATE_DETECT : Enables (1) or disables (0) detection of duplicate email addresses in the
recipient list. Does not affect operation of skip (exclusion) lists. The default is enabled (1).
MCM_SET_CHANNEL_DIVISOR : Sets the channel divisor D (default = 4) such that the number of channels
N used is reduced so that (N <= L / D) where L = the number of lines in the recipient list. In order to take
affect at runtime, mcmOpenList must be called before mcmOpenLetter.
MCM_SET_MACRO_DELIMITER : Specifies the macro substitution delimiter in the letter to be sent. Choose
percent %, blackslash \, or backquote ` (the default).
MCM_AUTO_LOAD_HEADER_FILE : Sets a flag so that the header file will be automatically loaded when
mcmOpenLetter is called, provided that the header file has the same name as the letter file except for
extension ".hdr" rather than ".txt" or ".htm". Avoid having to call mcmOpenHeader.
MCM_SET_SMTP_PROTOCOL : Sets the SMTP protocol to 'ParamValue', which should be one of
SMTP_AUTHENTICATE_CRAM, SMTP_AUTHENTICATE_LOGIN, or SMTP_AUTHENTICATE_PLAIN.
Required by some SMTP servers. See \MCM4C\SSL\SSL_SERVERS.TXT.
RETURNS
< 0 : Error (see Section 3.0 MCM Error List)
>= 0 : Parameter value set (no error).
EXAMPLE CODE
* set debug level to MCM_DEBUG_LOW
Code = XmcmSetInteger(MCM_SET_DEBUG_LEVEL, MCM_DEBUG_LOW)
EXAMPLE PROGRAMS
None.
28
2.24 XmcmSetProxySSL: Set SSL Proxy Parameters
SYNTAX
FUNCTION XmcmSetProxySSL(nProxyCode,nProxyFlags,@cProxyDir,
@cProxyCert,@cProxyExe,nProxyPort)
nProxyCode
nProxyFlags
cProxyDir
cProxyCert
cProxyExe
nProxyPort
:
:
:
:
:
:
proxy
proxy
proxy
proxy
proxy
proxy
code (reserved, set to 0)
server flags (1=icon on taskbar)
directory (on this machine)
certificate (STUNNEL.PEM) - file or path
executable (STUNNEL.EXE) - file or path
port
REMARKS
The mcmSetProxySSL program sets parameters for the proxy server (Stunnel) and must be called before
connecting to any SMTP or POP3 server that requires SSL.
For details on using Stunnel, see the section "Using Stunnel" online in the MCM User's Manual or
http://www.marshallsoft.com/stunnel.htm.
Set ProxyFlags = 1 if an icon is to be placed on the task bar.
Set ProxyDir to the path used to write the Stunnel configuration and log files.
Set ProxyCert to the filename or pathname of the X509 certificate (in PEM format).
Set ProxyExe to the proxy executable filename or pathname.
Set ProxyPort to the proxy to be used to communicate with the proxy server, or 0 to disable the proxy
server. Any unused port can be specified.
RETURNS
< 0 : Error (see Section 3.0 MCM Error List)
>= 0 : No error.
EXAMPLE CODE
ProxyDir = "c:\mcm4xb\ssl"
ProxyCert = "c:\mcm4xb\ssl\stunnel.pem"
ProxyExe = "c:\mcm4xb\ssl\stunnel.exe"
Code = XmcmSetProxySSL(0,1,ProxyDir,ProxyCert,ProxyExe,8801)
EXAMPLE PROGRAMS
SendMail
29
2.25 XmcmSetString: Sets string for MCM processing.
SYNTAX
Code = XmcmSetString(ParamName, @ParamString)
ParamName
ParamString
: (INTEGER) Parameter number.
: (STRING) Parameter string.
REMARKS
The XmcmSetString function sets a string parameter.
MCM_SET_FROM_ADDRESS : Sets the "From:" address on subsequent outgoing email (initially set by
XmcmSmtpConnect).
MCM_SET_CC_ADDRESS : Sets the "CC:" address string for all outgoing email. Addresses must be enclosed
in '<' and '>' brackets, as in "<[email protected]>".
MCM_SET_BCC_ADDRESS: Sets the "BCC:" address string for all outgoing email. Addresses must be
enclosed in '<' and '>' brackets, as in "<[email protected]>".
RETURNS
< 0 : Error (see Section 3.0 MCM Error List)
>= 0 : Length of parameter string (no error).
EXAMPLE CODE
FromAddr = "[email protected]"
* set "From:" address
Code = XmcmSetString(MCM_SET_FROM_ADDRESS, @FromAddr)
EXAMPLE PROGRAMS
None.
30
2.26 XmcmSleep: Sleeps specified milliseconds.
SYNTAX
Code = XmcmSleep(MilliSecs)
MilliSecs : (INTEGER) Milliseconds to sleep.
REMARKS
The XmcmSleep function sleeps the number of specified milliseconds. This function is the same as the
Windows API Sleep function.
RETURNS
MilliSecs
EXAMPLE CODE
* sleep 3 seconds
Code = XmcmSleep(3000)
EXAMPLE PROGRAMS
SendMail and GetReply.
31
2.27 XmcmSmtpClose: Close SMTP server connection.
SYNTAX
Code = XmcmSmtpClose()
REMARKS
The XmcmSmtpClose function closes all SMTP channels, and will not return until all channels are closed.
Before calling XmcmSmtpClose, the Code = XmcmGetInteger(MCM_GET_CHANNEL_STATUS)
should be called repeatedly until it returns 0, indicating that all channels have finished sending. See the
SendMail example program.
RETURNS
< 0 : Error (see Section 3.0 MCM Error List)
>= 0 : No error.
EXAMPLE CODE
* close all connections to SMTP server
XmcmSmtpClose()
EXAMPLE PROGRAMS
SendMail
ALSO SEE
XmcmPop3Close
32
2.28 XmcmSmtpConnect: Connect to SMTP server.
SYNTAX
Code = XmcmSmtpConnect(@Server, Port, @User, @Pass, @From, ReOpen, Delay)
Server
Port
User
Pass
From
ReOpen
Delay
:
:
:
:
:
:
:
(STRING)
(INTEGER)
(STRING)
(STRING)
(STRING)
(INTEGER)
(INTEGER)
SMTP server name of IP address.
SMTP port (normally 25 or 587)
SMTP user name (SMTP Authentication only)
SMTP password (SMTP Authentication only)
Email address of sender.
Number of emails before closing & reopening.
Number of seconds to delay before reopening
connection.
REMARKS
The XmcmSmtpConnect function connects to the specified SMTP server using the number of channels
authorized by the MCM license, but not more than the maximum that was passed to the XmcmAttach
function.
The "well known port" for SMTP is 25. However, some servers require that port 587 be used, reserving port
25 only for other known SMTP servers.
If the SMTP server requires "SMTP Authentication", the user and password must be specified. Otherwise pass
the empty string Chr(0).
The ReOpen value specifies the number of emails sent (by each channel) before closing and reopening the
connection, and is normally used with servers that set a maximum number of emails that can be sent. Pass 0 to
disable the ReOpen feature.
The Delay value is the number of seconds to delay after closing the connection (ReOpen > 0 was specified)
before reopening it . Pass 0 to specify no delay.
RETURNS
< 0 : Error (see Section 3.0 MCM Error List)
>= 0 : No error.
EXAMPLE CODE
SMTP_Server
SMTP_User =
SMTP_Pass =
SMTP_From =
SMTP_Port =
= "mail.hiwaay.net"
Chr(0)
Chr(0)
Chr(0)
587
* connect to SMTP server on port 587
Code = XmcmSmtpConnect(@SMTP_Server, SMTP_Port, @SMTP_User,
@SMTP_Pass, @SMTP_From, 0, 0)
EXAMPLE PROGRAMS
SendMail
33
2.29 XmcmStatistics: Get runtime statistics.
SYNTAX
Code = XmcmStatistics(ParmName)
ParamName : Parameter number.
REMARKS
The XmcmStatistics function returns the runtime statistic corresponding to 'ParamName' .
MCM_STAT_TOTAL_RECIPIENTS
MCM_STAT_BRACKETED_ADDRESSES
MCM_STAT_INVALID_ADDRESSES
MCM_STAT_DUPLICATE_ADDRESSES
MCM_STAT_WITH_BAD_ATTACHMENT
MCM_STAT_SKIPPED_ADDRESSES
MCM_STAT_WITH_UNKNOWN_CHARSETS
MCM_STAT_AVG_SEND_TIME
MCM_STAT_AVG_CONNECT_TIME
:
:
:
:
:
:
:
:
:
Total number of recipients
Number of bracketed addresses
Number of invalid addresses
Number of duplicate addresses
Number of bad attachments
Number of skipped addresses
Number of unknown char sets
The average time (milliseconds) to send each email.
The average time (milliseconds) to connect to the server.
RETURNS
The selected runtime statistic.
EXAMPLE CODE
DupAddresses = XmcmStatistics(MCM_STAT_DUPLICATE_ADDRESSES)
? Str(DupAddresses ) + " duplicate addresses seen"
EXAMPLE PROGRAMS
SendMail
ALSO SEE
XmcmGetIntetger and XmcmGetInterger2
34
2.30 mcmUtility: MCM Utility Function
SYNTAX
mcmUtility(ParamName, @ParamString)
ParamName
: Parameter name.
ParamString : Parameter string.
REMARKS
The mcmUtility function can only be called before calling any other MCM functions.
ParamName
MCM_GET_FILE_LINE_COUNT
ParamString
File name
Returns
# lines in file.
RETURNS
See above.
EXAMPLE CODE
Lines = mcmUtility(MCM_GET_FILE_LINE_COUNT, @ListFile)
EXAMPLE PROGRAMS
SendMail.prg
35
2.31 XmcmWriteToLog: Write to log file.
SYNTAX
Code = XmcmWriteToLog(@Text)
String : (STRING) Text to write to the log file.
REMARKS
The XmcmWriteToLog function writes the specified string to the MCM log file. Note that
XmcmWriteToLog cannot be called until after XmcmAttach is called.
RETURNS
The length of the passed string.
EXAMPLE CODE
Dim Text
Text = "(SendMail Example Program)"
XmcmWriteToLog(@Text)
EXAMPLE PROGRAMS
SendMail and GetReply
36
3.0 MCM Error List
The numerical list of MCM errors follows:
-1:
-101:
-102:
-103:
-104:
-105:
-106:
-107:
-141:
-142:
-171:
-201:
-202:
-203:
-204:
-205:
-206:
-207:
-208:
-210:
-211:
-212:
-214:
-215:
-216:
-217:
-218:
-219:
-220:
-221:
-222:
-223:
-224:
-225:
-226:
-227:
-228:
-229:
-302:
-303:
-304:
-305:
-306:
-307:
-308:
-309:
-310:
-311:
-312:
-351:
-352:
-353:
-354:
-355:
-401:
-402:
-403:
-404:
End-of-File (list)
Cannot set SMTP port
Cannot connect to SMTP server
Invalid key code
Send mail fails
Cannot set SMTP user name
Cannot set SMTP password
Invalid email address
Cannot set POP3 port
Cannot connect to POP3 server
Too many reply files
Not authorized (internal error).
First line of letter must start with 'To:'
Second line of letter must start with 'Subject:'
Body of email is missing
Cannot open MCM bin-file
Cannot read MCM bin-file
Invalid bin-file format
Corrupted bin-file
Max recipient list size exceeded in evaluation version
Cannot allocate memory for letter buffers
TCP/TP running on Ethernet
Path to MCM directory cannot be null
Must specify path to MCM directory
No such macro
Maximum skip files exceeded
Maximum reply files exceeded
No such parameter
No such header
Unknown CharSet
Buffer too small
No channels allocated (by mcmAttach)
All channels have been disabled
Evaluation version expired
String too long. Expect <= 256
String too long. Expect <= 1000
Bad email address. Expect '<name@domain>'
Not authorized to use this version of MCM32.DLL
lstInit not called
Cannot open list file
No such string
Bad delimiter. Expecting commas or tabs
Cannot determine delimiter on macro line
Cannot determine delimiter on entry line
Delimiter character must match delimiter on macro line
Number delimters must match number on macro line
List buffer is too small
Missing entry in recipient-list
Recipient list string is too long
Cannot start SMTP thread
Maximum allowed channels exceeded
No channels specified!
mcmSmtpClose already called
Not connected to servers
End-of-File (letter)
ltrInit not called
Cannot open letter file
Cannot allocate memory for (raw) letter
37
-405:
-406:
-408:
-409:
-410:
-411:
-412:
-413:
-414:
-415:
-451:
-452:
-453:
-454:
-455:
-501:
-502:
-503:
-504:
-505:
-506:
-507:
-541:
-542:
-543:
-544:
-602:
-701:
-702:
-703:
-704:
-705:
-801:
-802:
-803:
-902:
-903:
-951:
-952:
-953:
-954:
-955:
Letter file not opened
Macro not closed
Macro too big
Illegal character inside macro
Macro not closed before end-of-line
Isolated macro definition character (percent sign)
Error reading letter file
Macro cannot contain space characters
Macro not found
Unknown file extension: Expecting .htm, .txt, or .rtf
Memory mutex operation failed
Timed out waiting for memory mutex
No such buffer exists
bufInit not called
Timed out waiting for free buffer
Letter has not been loaded
Macro not found in list macro line
No such field in on list entry line
Buffer overflow
String table key too large (max = 40 chars)
String table replacement text too large (max = 256 chars)
String table overflow
Supermacro not closed
Illegal character in supermacro
Supermacro too big
Supermaccro table lookup fails
logInit not called
Max files exceeded
Cannot allocate memory
No such file
No such file index
String not found
No space remaining in file table
No such file (bad file table entry)
File not open
Cannot allocate memory
Slot table overflow
MCM aborted
Bad key code
Evaluation version expired
Bad edition code
Must call mcmAttach first
38