Transact-SQL Reference

xp_findnextmsg

Accepts a message ID for input and returns the message ID for output. xp_findnextmsg is used with sp_processmail in order to process mail in the Microsoft® SQL Server™ inbox.

Syntax

xp_findnextmsg [[@type =] type]
[,[@unread_only =] 'unread_value']
[,[@msg_id =] 'message_number' [OUTPUT]]

Arguments

[@type =] type

Is the input message type based on the MAPI mail definition:

IP[M | C].Vendorname.subclass

If type is NULL, message types beginning with IPM appear in the inbox of the mail client and are found or read by xp_findnextmsg. Message types beginning with IPC do not appear in the inbox of the mail client and must be found or read by setting the type parameter. The default is NULL.

[@unread_only =] 'unread_value'

Is whether only unread (true) messages are considered. The default is FALSE, which means all messages are considered.

[@msg_id =] 'message_number'

Is an input and output parameter that specifies the string of the message on input and the string of the next message on output.

OUTPUT

When specified, message_number is placed in the output parameter. When not specified, message_number is returned as a single-column, single-row result set.

Return Code Values

0 (success) or 1 (failure)

Result Sets

xp_findnextmsg returns this result set when passed a valid message ID:

The command(s) completed successfully.

Remarks

Any failure except an invalid parameter is logged to the Microsoft Windows NT® application log.

Permissions

Execute permissions for xp_findnextmsg default to members of the db_owner fixed database role in the master database and members of the sysadmin fixed server role, but can be granted to other users.

Examples

This example retrieves the status when searching for the next message ID (for only unread messages). The value from xp_findnextmsg is placed in the local variable @message_id.

DECLARE @status int, @message_id varchar(255)
-- SET @status = value would be here.
-- SET @message_id = value would be here.
EXEC @status = xp_findnextmsg @msg_id = @message_id OUTPUT