Sun Java System Messaging Server 6 2005Q4 MTA Developer's Reference


Determine the host name associated with a channel.


const char *mtaChannelToHost(char  **host,
                             size_t *host_len,
                             int     item_code, ...);





A pointer to receive the host name. The host name will be NULL terminated. NULL can be passed for this call argument. 


An optional pointer to a size_t to receive the length in bytes of the returned host name. This length does not include the NULL terminator that terminates the host name. A value of NULL can be passed for this call argument.


An optional list of item codes. The list must be terminated with an integer argument with value 0.


This routine is used to determine the host name associated with a particular channel.

The channel name can be specified in one of three ways:

In all cases, the official host name of the selected channel is the host name that is returned. The official host name for a channel is the one that appears on the second line of the channel definition in the MTA configuration file, imta.conf.

The following table lists the item codes and any associated arguments:

Item Codes  

Additional Arguments  



const char *channel

size_t channel_len

Explicitly specify a channel name for the official host name. This item code must be followed by the two additional call arguments, specifying: 

  1. The channel name.

  2. The length in bytes of that channel name.

    If a value of 0 is passed for the length, the channel name must be NULL terminated.


mta_dq_t *dq_ctx

Use the channel associated with the specified dequeue context. This item code must be followed by one additional call argument: a pointer to a dequeue context generated by mtaDequeueStart().


mta_item_list_t *item_list

Specify a pointer to an item list array that is terminated with a final array entry that has an item code value of 0. For further information on item lists, see Item Codes and Item Lists.

When none of the above item codes are specified, the channel name is taken from the runtime environment, using PMDF_CHANNEL environment variable.

On successful completion, the host name is stored in the buffer pointed at by the host argument, and the value of the host argument is returned.

Return Values

In the event of an error, mtaChannelToHost() will return NULL, but will set mta_errno. The following table lists the error status codes for this routine.

Error Status Codes  



A NULL value was supplied for either of these two argument: 

  1. The host argument in the routine call.

  2. An argument to an item code.


Unable to initialize the MTA SDK. Unable to read one or more configuration files. Issue the following command for further information: 

imsimta test -rewrite


One of the following errors occurred: 

  1. Unable to determine the channel name from the runtime environment.

  2. Unable to initialize the MTA SDK. For further information, issue the following command:

    imsimta test -rewrite


The selected channel name does not appear in the MTA configuration file, imta.cnf.


An invalid item code was specified. 


printf("Host name: %s\n",
       mtaChannelToHost(NULL, NULL, MTA_CHANNEL,
                        "tcp_local", 0, 0));