mtaDequeueStart()

int mtaDequeueStart(void                     *ctx1,
                    mta_dq_process_message_t *process_message,
                    mta_dq_process_done_t    *process_done,
                    int                       item_code, ...);

ctx1

Optional pointer to a caller-supplied context or other data type. This pointer will be passed as the ctx1 argument to the caller-supplied routines process_message and process_done. A value of NULL may be passed for this argument.

process_message

The address of a caller-supplied routine to process each message. 

process_done

Optional address of a caller-supplied clean up routine. A NULL value may be passed for this argument. 

item_code

An optional list of item codes. See the description section that follow for a list of item codes. The list must be terminated with an integer argument with value 0.

MTA_CHANNEL

const char *channel

size_t channel_len

Explicitly specify the name of the channel name to perform dequeue processing for. This item code must be followed by two additional call arguments: the name of the channel and the length in bytes of that channel name. If a value of zero is passed for the length, then the channel name must be NULL terminated. 

When this item code is not specified, the name of the channel to process queued messages for is taken from the PMDF_CHANNEL environment variable.

MTA_ITEM_LIST

mta_item_list_t *item_list

Specify a pointer to an item list array. The item list array must be terminated with a final array entry with an item code value of zero. For further information on item list usage, see Item Codes and Item Lists.

MTA_JBC_MAX_ATTEMPTS

size_t attempts

Specify the maximum number of contiguous attempts that will be made to sleep and then re-query the Job Controller for work after being told by the Job Controller that there are no more messages to process. The default value for this setting is 5 attempts. If an attempt succeeds in providing additional work, the count of attempts is reset to zero. (The duration of each sleep may be specified with the MTA_JBC_RETRY_INTERVAL item code.)

This item code must be followed by an additional argument: the maximum number of contiguous attempts to make. 

MTA_JBC_RETRY_INTERVAL

size_t seconds

Set the number of seconds mtaDequeueMessage() sleeps before again querying the Job Controller for additional work. When not specified, a value of 10 seconds is used. This item code must be followed by one additional argument: the number of seconds to sleep for.

MTA_THREAD_MAX_THREADS

size_t threads

Specify the maximum number of processing threads to run concurrently. If not specified, then a limit of 20 threads is assumed.

This item code must be followed by one additional argument: the maximum number of concurrent threads to permit. 

MTA_THREAD_STACK_SIZE

size_t bytes

By default, the processing threads will have a stack whose size is sufficient for MTA SDK operations. This is the size returned by the mtaStackSize() routine. To request a larger size, use this item code to specify the desired size. Note that specification of a smaller size is ignored: mtaDequeueMessage() will never use a stack size smaller than that returned by mtaStackSize().

This item code must be followed by one additional argument: the minimum size in bytes for each thread’s stack. 

MTA_THREAD_MAX_MESSAGES

size_t messages

The number of messages to allocate per processing thread. The channel program will aim to run N processing threads where N is computed as follows: N = (count of pending queued messages) / MTA_THREAD_MAX_MESSAGES. For example, if there are 100 queued messages and MTA_THREAD_MAX_MESSAGES has its default value of 20 messages, then 5 processing threads are started.

This value does not control the total number of messages presented to a single processing thread. 

This item code must be followed by one additional argument: the number of messages for each processing thread. 

MTA_THREAD_WAIT_TIMEOUT

size_t seconds

Once mtaDequeueMessage() determines that there are no more messages to process, it waits for all processing threads to complete their work and exit. By default, mtaDequeueMessage() will wait no longer than 1800 seconds (30 minutes).

This item code must be followed by one additional argument: the maximum number of seconds to wait. 

0

Normal, successful completion. 

MTA_BADARGS

This value is returned for one of following reasons: 

1. A NULL value was supplied for the dq_ctx call argument.

2. An invalid dequeue context was supplied for dq_ctx.

3. A NULL value was specified for the process_message routine.

4. A NULL value was supplied for a required item code argument.

MTA_FOPEN

Unable to initialize the MTA SDK. Unable to read one or more configuration files. 

For further information, issue the following command: 

imsimta test -rewrite

MTA_NETWORK

Error communicating with the Job Controller. 

MTA_NO

Unable to initialize the MTA SDK. 

For further information, issue the following command: 

imsimta test -rewrite

MTA_NOMEM

Insufficient virtual memory. 

MTA_NOSUCHCHAN

Specified channel is not defined in the MTA configuration file. If no channel was explicitly specified, then the channel name specified with the PMDF_CHANNEL environment variable is not defined in the MTA configuration file. This error may also be returned when the Job Controller’s configuration file lacks a CHANNEL section matching the specified channel.

MTA_NOSUCHITEM

An invalid item code was specified.