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.
.gif "Topic link icon")
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.subclassIf type is NULL, message types that start with
IPMappear in the inbox of the mail client and are found or read by xp_findnextmsg. Message types that start withIPCdo 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 ofIPMandIPC.
- [ @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)