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

`mtaChannelToHost()`

Determine the host name associated with a channel.

Syntax

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

Arguments

Arguments	Description
`host`	A pointer to receive the host name. The host name will be NULL terminated. NULL can be passed for this call argument.
`host_len`	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.
`item_code`	An optional list of item codes. The list must be terminated with an integer argument with value `0`.

Description

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:

Implicitly specified. For this case, no item codes other than the terminating 0 are specified and the channel name is the one for the running program. The channel name is set using the PMDF_CHANNEL environment variable.
Explicitly specified with the MTA_CHANNEL item code.
Set using the MTA_DQ_CONTEXT item code, which is taken to be the channel name associated with a specified dequeue context.

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	Description
`MTA_CHANNEL`	`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: The channel name. 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_CONTEXT`	`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`	`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.

Item Codes

Additional Arguments

Description

MTA_CHANNEL

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:

The channel name.
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_CONTEXT

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

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	Description
`MTA_BADARGS`	A NULL value was supplied for either of these two argument: The `host` argument in the routine call. An argument to an item code.
`MTA_FOPEN`	Unable to initialize the MTA SDK. Unable to read one or more configuration files. Issue the following command for further information: `imsimta test -rewrite`
`MTA_NO`	One of the following errors occurred: Unable to determine the channel name from the runtime environment. Unable to initialize the MTA SDK. For further information, issue the following command: `imsimta test -rewrite`
`MTA_NOSUCHCHAN`	The selected channel name does not appear in the MTA configuration file, `imta.cnf`.
`MTA_NOSUCHITEM`	An invalid item code was specified.

Example

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