xp_findnextmsg (Transact-SQL)

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.

Note

This feature will be removed in a future version of Microsoft SQL Server. Avoid using this feature in new development work, and plan to modify applications that currently use this feature.

Transact-SQL Syntax Conventions

Syntax

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

Arguments

• [ @type=] type
  Is the input message type based on the MAPI definition:

  IP[M|C].Vendorname.subclass

  If type is NULL, message types that start with IPM appear in the inbox of the mail client and are found or read by xp_findnextmsg. Message types that start 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. SQL Mail supports message types of IPM and IPC.

• [ @unread_only=] 'unread_value'
  Is whether only unread (N'TRUE') messages are considered. The default is N'FALSE', which means all messages are considered. unread_value is of type nvarchar(5).

• [ @msg_id=] 'message_id'
  Is an input and output parameter that specifies the string of the message on input and the string of the next message on output. If message_id for the input is NULL, then by default, the output @msg_id will be the ID for the most recently delivered message in the Inbox. message_id is varchar(255), with a default of NULL.

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

Return Code Values

0 (success) or 1 (failure)

Result Sets

xp_findnextmsg returns a message when passed a valid message ID.

When @msg_id is NULL, xp_findnextmsg returns the following result set.

Column name	Data type	Description
Message ID	varchar(255)	Message ID for the next message.

Remarks

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

Permissions

Requires membership in the sysadmin fixed server role, but EXECUTE permissions can be granted to other users. However, for security reasons, we recommend that permissions for this stored procedure be limited to members of the sysadmin fixed server role.

Examples

The following 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) ;

EXEC @status = xp_findnextmsg @msg_id = @message_id OUTPUT ;

See Also

Reference

sp_processmail (Transact-SQL)
System Stored Procedures (Transact-SQL)
xp_deletemail (Transact-SQL)
xp_readmail (Transact-SQL)
xp_sendmail (Transact-SQL)
xp_startmail (Transact-SQL)
xp_stopmail (Transact-SQL)

Help and Information

Getting SQL Server 2005 Assistance