The parameters for this class is summarized in the following table. All parameters that take a string as a name have default values of empty strings (""), unless otherwise noted.

$::date
$::who
$arpa


$::build_salutation


This is a message from George Bush. Just because I am not officially
the president of America doesn't mean I can't control you. I need to
know everything about you, including how often you have sex, with who,
and what sex the person(s) is/are. If you fail to comply, the power of
the American federal government will fall on your disobiedent
ass, and you will spend the rest of your life in one of our Supermax
prisons.
Sincerely,
G. Bush (top dictator)
punkhol@ex-prs.whitehouse.gov

# :start-databag:
target
(
    who
    (
      worker ( name ( first Michael last Brown ) title victim )
    )
    phone <"+1 (314) 522-3100" >
    email "mbrown@deadguys-butwhy.org"
)
# :end-databag:

Jan 18, 2016
Michael Brown
mbrown@deadguys-butwhy.org


Dear Mr. Brown:


This is a message from George Bush. Just because I am not officially
the president of America doesn't mean I can't control you.
...
Sincerely,
G. Bush (top dictator)
punkhol@ex-prs.whitehouse.gov

member functions (primary)

massmail_o()
SIGNATURE: massmail_o ()
SYNOPSIS: creates a a new, 'empty' massmail object. All of its settings are at default values after this construction.
 

destructor
SIGNATURE: ~massmail_o ()
SYNOPSIS: virtual destructor. The massmail object instance is reset.
 

config()
SIGNATURE: int config (paramstring_o &ps, int *pi = NULL)
SYNOPSIS:
This member function is the workhorse of configuring a massmail object prior to calling run(). Any of the parameters specified in the main table above can be passed to this function (via input variable "ps"). Multiple name-value pairs can be used, separated by a space. Values with embedded punctuation or whitespace must be quote-wrapped (precede a double-quote by a back-slash {standard c programming}).
Example:

    massmail_o mm;
    mm.config("FORMLETTER=\"readme.txt\" RECIPIENTS=\"targets.bag\");
    mm.config("MIMETYPE=\"text/plain\" PHP=NO");
    mm.run();

This code sliver is not sufficient to actually work. The massmail object requires many parameters to be preconfigured in order to be able to run successfully. As can be seen from the example, config() can be called repeatedly, with a variable number of key-value pairs embedded in the 'ps' parameter.
PARAMETERS

pi: [optional] error indicator variable. Its values:
0: all ok
1: unknown keyword encountered
2: YES | NO string expected, not found
3: other flag value issue
4: unknown (eg, illegal) encryption type given

 

set_volume()
SIGNATURE: int set_volume (int x)
SYNOPSIS:
sets the debugging/tracing output volume level. The value of 'x' must be in the range [0..100], inclusive. The volume levels embedded in this object include:
10: error messages printed (symbolic constant 'zMM_Volume_FatalErr');
20: "followup" (post-event) error messages printed (symbolic constant 'zMM_Intolerable_Volume ');
30: default messages in "preprocess_php()" emitted; custom messages in "postprocess_msg()" printed;
35: successful send messages in "postprocess_msg()" emitted;
45: post-send "trace" message printed ('zMM_Volume_BasicMsg')
RETURNS:
0: volume successfully set.
-1: volume not set - inputtd value was out of range.
 

set_ini()
SIGNATURE: int set_ini (const string_o &spath, int *pi = NULL)
SYNOPSIS:
sets the file name (and path, if one is provided in 'spath') of the INI file. Using this function is optional, and should be used if the object's configuration is to be specified via an INI file. This is "optional" because you can use config() to also configure the object. This routine passes the variable 'spath' to a file object, which then verifies if the file exists. If it is not found, or cannot be accessed, this is not considered an error, but the output error flag will be set to indicate this fact.
If this routine succeeds, the myflags bit 'zFlag_MM_USE_INI' will be set, which will allow load_ini() to proceed.
PARAMETERS

pi: [optional] error indicator variable. Its values:
0: all ok, file set
1: INI file not found (warning only)
2: INI file name was previously set (warning only)

RETURNS: 0
 

load_ini()
SIGNATURE: int load_ini (int *pi)
SYNOPSIS:
this member function will load the contents of an INI file. The object will be configured according to the parameters found in the file. This routine can be used in conjunction with config(). The order does not matter. Successive calls to load_ini() will over-write any previously set values. Any parameters omitted from the INI file can be set via config().
This function can be called explicitly, or run() will call it automatically, if an INI file was specified (via set_init()). If called earlier, and "run()" has not been done, this is considered a warning, and the output error variable ('pi') will be set - there is no normallly good reason to call "load_ini()" more than once.
PARAMETERS

pi: [optional] error indicator variable. Its values:
0: all ok
1: ini file is not to be used! ('use_ini' is FALSE)
2: ini file load failure; probably bad syntax in the file
3: "load_ini()" called earlier [warning only]
4: 'i' out of bounds (1st loop). should never happen.. unless 'i' value increased and out of sync with # of elements in the ini file.
5: 'i' out of bounds (2nd loop). same reason as *pie = 4. This can never actually happen, because the same error is handled where output value '4' is set.
6: YES | NO string expected, not found
7: [PANIC] "map2_idx_str()" internal error (should not happen)
8: [PANIC] "config()" call failed

RETURNS:
0: INI file successfully loaded.
-1: INI file not loaded (See 'pi' for reasons why)
 

attach_file()
SIGNATURE: int attach_file (const file_o &f, int *pi = NULL)
SYNOPSIS:
This adds an attachment to the e-mail message to send. This function can be called repeatedly to attach more than 1 file. NOte that when using the INI file, only 1 file can be attached.
RETURNS: 0
 

volume()
SIGNATURE: int volume () const
SYNOPSIS: returns the value of the volume set by set_volume().
RETURNS: 0
TRAITS: this member function is inlined.
 

reset()
SIGNATURE: int reset()
SYNOPSIS:
resets the massmail object to its default, at-construction-state [eg, default] values. See the main table on this page for a list of the massmail parameter default values.
RETURNS: 0
 

run()
SIGNATURE: int run (int *pi)
SYNOPSIS:
processes a list of recipients to send each an e-mail. This member function is the only funtion that "does work". See the main description section on this page for more information about what this object does.
This function invokes "pre_check()" to make sure things are in order for doing a run: recipient list file and form letter file must exist; and if using PHP, the directory for the output file from the PHP CLI must exist.
PARAMETERS

pi: [mandatory] error indicator variable. Its values:
0: all ok
1: no recipient list (file). This value is set in "pre_check()".
2: no [input] form letter (file) was specified or found. This value is set in "pre_check()".
3: directory for the intermediate [post-PHP] file doesn't exist {from pre_check()}.
4: temporary (work) file name was not set - this should have been auto-generated, if not explicitly set {from pre_check()}.
5: INI file could not be opened (bad path?)
zErr_Resource_Unavail: database could not be opened.

RETURNS:
0: recipient list successfully processed.
-1: an error occurred during the run. see 'pi' for info why.
 

preprocess_php()
SIGNATURE: int preprocess_php (const file_o &f, rec_dbag_o &bag)
SYNOPSIS:
This function is one of a series of 4 virtual functions allowing you the option of overriding the default behavior (which in some cases is nothing, and other cases a message is printed). In order to implement your own reinterpretation of this function, a subclass must be created. Typically this subclass is a minimal class with the only these virtual functions explictly defined.
This function provides a "hook" where the application can do something prior to a file being submitted to PHP for processing. It is always called (whether the default version or your own). See the main description section for more information on this function and the other three associated virtual functions.
The default action of this function specifically is to print 'GOT ANOTHER RECIPIENT (# [n] - "[email-address]"', where '[n]' is the count number and '[email-address]' is the current recipient e-mail address. You can shut off or change printing this message in many ways:

1. set the "logging/PRINT_MSG_START" value in the INI file to NO
2. call config() with the "PRINT_MSG_START" value set to NO
3. set the INI value "logging/MESSAGE_START" to some text, eg, any non-blank characters.
4. use config() with the paramstring_o value "MESSAGE_START", providing some text, eg:

        massmail_o x;
        x.config("MESSAGE_START=\"print this!\"");"
        

5. set the volume to 36 or higher

PARAMETERS

• f: the file object for the template file.
• bag: the [recursive] databag containing the data from the recipient list file. The contents of 'bag' is complete dataset for the current recipient being processed.

RETURNS: 0
 

postprocess_php()
SIGNATURE: int postprocess_php (const file_o &f, rec_dbag_o &bag)
SYNOPSIS:
This function is one of a series of 4 virtual functions allowing you the option of overriding the default behavior. In order to implement your own function, a subclass must be created. Typically this subclass is a minimal class with the only these virtual functions explictly defined.
This function provides a "hook" where the application can do something after a file has been being submitted to PHP for processing. It differs from preprocess_php() in that it is provided a file object with the contents of the form letter after PHP processing. If PHP processing is turned off, the file object points to the original template file. However, if off, this function will not be called . See the main description section for more information on this function and the other three associated virtual functions.
The default action of this function specifically is nothing. That is, this function does absolutely nothing; it simply returns 0. Furthermore, it is not even called unless PHP (or USE_PHP) is set to YES. The default value of PHP is NO. The file should not be modified, else serious damage can result.
PARAMETERS

• f: the file object for the template file.
• bag: the [recursive] databag containing the data from the recipient list file. The contents of 'bag' is complete dataset for the current recipient being processed.

RETURNS: 0
 

preprocess_msg()
SIGNATURE: int preprocess_msg (const string_o &msg, rec_dbag_o &bag)
SYNOPSIS:
This function is one of a series of 4 virtual functions, thus allowing you the option of overriding its default behavior. This function provides a "hook" where the application can do something prior to a message being sent. It is called only if the SEND parameter is set to YES (this is so by default). The default action of this function specifically is nothing. That is, this function does absolutely nothing; it simply returns 0.
PARAMETERS

• msg: a string object containing the text to be sent via e-mail.
• bag: the [recursive] databag containing the data from the recipient list file. The contents of 'bag' is the complete dataset for the current recipient being processed.

RETURNS: 0
 

postprocess_msg()
SIGNATURE: int postprocess_msg (const string_o &msg, rec_dbag_o &bag)
SYNOPSIS:
This function is one of a series of 4 virtual functions that provide the application a "hook" where the application can do something after to an e-mail has been sent. This is done just prior to the end of the procssing cycle for the current recipient. It is always called.
The default action of this specific function is to print a line to the console [stdout] like: '"[addr]" - letter sent.' where [addr] is the current e-mail address. This is done if the send was successful. If the send failed, a message like this one is printed to stdout:

[addr]; last error message: "[error text]"

'[error text]' is provided by the OS mail transport system. In the default function case (no subclassing done), there are many ways to turn off or modify console message printing. See the entry for preprocess_php() for a list of alternatives. It can be shut off by setting the parameter 'PRINT_MSG_FINISH' to 'NO'. You can change the message text to your own by setting the parameter MESSAGE_FINISH.
PARAMETERS

• msg: a string object containing the text what as sent via e-mail.
• bag: the [recursive] databag containing the data from the recipient list file. The contents of 'bag' is a complete dataset for the current recipient being processed.

RETURNS: 0
 

curr_count()
SIGNATURE: count_t curr_count ()
SYNOPSIS: returns the index value of the current recipient. The first recipient has value 0.
TRAITS: this member function is inlined.
 

usage.
The steps required to send e-mail using this object, in the simplest case, breaks down into these steps:

1. set up the INI file that the object will read.


2. write a form letter.


3. set up the list of recipients.


4. write a program using the object.


5. run the program.

[1] setting up the INI file.

[2] writing the letter to send.
This can be as simple as writing a letter. However, it can be very complex because you can write a document written with embedded PHP, or even entirely in PHP. A PHP-based document allows you to tailor the final text to the person, the business, or just about any set of parameters applicable to the letter. The massmail_o instance provides a mechanism for pushing the data of the business to the letter. How this is done is detailed in the PHP file object . You should get familiar with its operation in order to take advantage of the PHP processing behaviour. For those of you in a hurry, a [very minimal] Quick-Start boilerplate example is presented here:

The variables from the simple databag items inside a recursive databag are forwarded to the PHP processor. The databag comes from the current business entry being processed. Only simple items (no arrays, lists, or sub-databags) are translated into the PHP file. For a business, this includes the business name (databag path: full_name); and other fields such as id, what, note, or found. Not only top-level simple items are processed: all simple databags in the entire recursive databag. Thus given this business, in databag format:

# :start-databag:
target
(
    id 18900309
    full_name Brainbench
    who
    (
      worker ( name ( first Vyacheslav last Molotov ) title lapdog )
    )
    phone <"+1 (703) 674-3500" "+1 (703) 674-3332">
)
# :end-databag:

string_o lnam = bag.get("who worker name last");    // returns Molotov

$lnam = $_SERVER['who-worker-name-last'];

<?PHP
$biz_name = $_SERVER['full_name'];
$fname    = $_SERVER['who-worker-name-first'];
$lname    = $_SERVER['who-worker-name-last'];
$sex      = $_SERVER['who-worker-sex'];
 
if ($fname != '' && $lname != '')
{
    echo ("Attn: $fname $lname\n");
    if ($sex == 'F')
        echo ("Dear Ms. $lname,\n");
    else
        echo ("Dear Mr. $lname,\n");
    echo ("Are you still working at \"$biz_name\"?\n");
}
?>
The rest of the text is static, and will be mailed as "luggage"
in the body of the letter. You can still of course, embed more
PHP code <?PHP echo ("like so.\n"); ?>

[3] setting up the recipient list.
You can manually edit this file by hand or have a program generate it. For the latter, you can use the business textstream class to convert a text file with standard keyword-oriented business listings to the [simplified] databag format required by this object.

Here is a boilerplate example of a typical listing in a file, in the required databag format:

# :start-databag:
target
(
    id 101175
    full_name Brainbench
    who
    (
        worker
        (
           name ( first Vyacheslav last Molotov )
           sex M
           title "CEO"
        )
    )
    phone <"+1 (703) 674-3500" "+1 (703) 674-3332">
    email <"support@brainbench.com" "marketing@brainbench.com">
    url <"http://www.brainbench.com">
    found "10/23/2013 08:05:37"
)
# :end-databag:

• By default, each business entry's databag must be preceded with "# :start-databag:" (without the double-quotes, on its own line) and followed by "# :end-databag:" (also on a unique line). . The lines separating
• the [top-level] name of the databag ("target", in this example) is irrelevant. You can call it whatever you want (but it must have a name).
• The "id" field is not used. This is an unused extra datum, generated by the business textstream object.
• The databag name "full_name" is the first item checked in order to obtain the name of the business (/organization). If not present, the object searches for "cased_name", then "short_name". The first non-blank field found is used for naming the organization.
• The "who" [recursive databag] list can contain multiple "worker" sub-databags. Each entry represents a worker in the organization.
• Data fields such as phone, url, or found are not used by this class.
• Data fields such as phone, email, and url are repeatable fields: there can be 0, 1, or more occurances within the angle brackets (which represent an array databag). Since the text representation of each of the aforementioned items contains non-alphanumeric characters (e-mails contain at least a '@' character; phone numbers usually contain '+', '-', or '(' and ')'), the values must be wrapped in double-quotes.
• In order to send an e-mail to the recipient, obviously at least 1 e-mail address is required.

[4] make the program.

[5] run the program.

Assuming your program is named massmailer.exe and the INI file for it is mail.ini, you can make a command-line processor that searches for the keyword "-ini", like so:

#include "z_inifile.h"
inifile_o ini;
 
int cmdline (const int argc, const char **argv)
{
    int i;
    string_o s;
    for (i=1; i < argc; i++)
    {
        s = argv[i];
        if (s == "-ini")
            ini.set_name(argv[++i]);
    }
    return 0;
}

massmailer -ini mail.ini

warnings.
Be very careful about quoting text in the INI file. In the future, given a "key-value" pair (syntax: KEY=VALUE), you will be able to append comments by starting text with a '#' (sharp character) in the 'value part, like so:

MESSAGE_START=TO BE, OR NOT TO BE? # this is a comment

However, this will not work:

MESSAGE_START="TO BE, OR NOT TO BE?" # this is a comment

That is becuase the INI processor wraps the 'value' part in double-quotes. Internally, when getting the value in the last case (above), it will see this line: ""TO BE, OR NOT TO BE?" # this is a comment"

It will get the quoted string - which is the stuff in between the first pair of double-quotes that it encounters, which is an empty string - and the remainder of the line will be discarded. However, as of this writing (July 2012), appending comments in this way IS NOT IMPLEMENTED (this entire warning section has been written as a footnote for a future implementation).

limitations.
As of this writing, there are some hard-coded protocols you need to know:
The format of the recipient list has some rather specific rules. It must be in regular text format, and consist of a list of businesses (or other organizations). By default, each biz-org entry starts with this line:

# :start-databag:

# :end-databag:

BAG_TOPMARKER   = ////---o
BAG_BOTMARKER   = \\\\---o
BAG_SEPARATOR   =

////---o
target ( id 100 full_name "Acme Cement Company" )
\\\\---o
////---o
target
(
    id 101
    full_name "Another Business Entity"
)
////---o

BAG_TOPMARKER   =
BAG_BOTMARKER   =
BAG_SEPARATOR   = [((((NEXT-DATABAG))))]

target ( id 100 full_name "Acme Cement Company" )
 
[((((NEXT-DATABAG))))] (...this is the 3rd entry)
 
target
(
    id 101
    full_name "Another Business Entity"
)
 
[((((NEXT-DATABAG))))]
target ( id 102 full_name "Etc #3" who (name (first John last Doe )) )
 

• to use upper- and lower- delimiter pairs, include BAG_SEPARATOR in the INI file, and set it to nothing, ie, "BAG_SEPARATOR =". When this parameter is an empty string, massmail_o will turn to the other delimiters. By default this is set to "#------o" (without the double-quotes). It is an error to have all 3 parameters set. However, if BAG_SEPARATOR is set (to anything non-empty), the other two are ignored.
• Each marker parameter is expected to be on its own line, and start the line. That is, the marker text should be the only thing on the line (a newline is allowed). However, extraneous text is permitted to follow the marker text (such as can be seen in the 3rd entry in the above example, " (...this is the 3rd entry)").
• For separators, the lines should be in between the databags. For upper-lower pairs, they should envelop each databag. Thus in the latter case the first line should be the top marker and the last line in the file should be a bottom marker.

zdb_set_access_method(zstyle_DBax_ODBC);

Various console messages for emitted for warnings, errors, and checkpoints. These are done at volume levels given by the macro values zMM_Intolerable_Volume, zMM_Volume_FatalErr, and zMM_Volume_BasicMsg. In later versions, these should be under programmatic control in future releases.