3.1.5.5 proc_ChangeLevelForDoc

The proc_ChangeLevelForDoc stored procedure is invoked to update the publishing level of a document. Depending on the settings in effect on the containing list and the permissions of the specified user making the request, proc_ChangeLevelForDoc also can update the document's Moderation Status (section 2.2.3.13), UI version number, and properties to reflect the change.

 PROCEDURE proc_ChangeLevelForDoc(
       @SiteId                        uniqueidentifier,
       @DirName                       nvarchar(256),
       @LeafName                      nvarchar(128),
       @Level                         tinyint                     OUTPUT,
       @NewLevel                      tinyint,
       @ModerationStatus              int,
       @EnableMinorVersions           bit,
       @Moderated                     bit,
       @CreateVersion                 bit,
       @UserId                        int,
       @Comment                       nvarchar(1023),
       @bUpdateModified               bit,
       @@DoclibRowId                  int                         OUTPUT,
       @@DocUIVersion                 int                         OUTPUT,
       @@DocFlagsOut                  int                         OUTPUT,
       @@DocVersionOut                int                         OUTPUT,
       @RequestGuid                   uniqueidentifier   = NULL   OUTPUT
 );

@SiteId: The site collection identifier (section 2.2.1.9) of the site collection containing the document.

@DirName: The directory name of the document.

@LeafName: The leaf name of the document.

@Level: A Publishing Level type (section 2.2.2.6) value indicating the document's current publishing level. This output parameter also reflects the new publishing level value for the document.

@NewLevel: A Publishing Level type value indicating the requested publishing level for the document.

If @Level is set to 255 (Checked Out) or 2 (Draft), and @NewLevel is set to 1 (Published), then the document's level value MUST be changed to 1 (Published). If @Moderated is 0, @EnableMinorVersions is 0, @Level is not set to 255 (Checked Out) and @NewLevel is not set to 1 (Published), then the document's level value MUST NOT change, and output parameters MUST NOT be changed. If @Level is 1 (Published) and @NewLevel is 2 (Draft), then the document's level value MUST be changed to 2 (Draft). If @Level is 255 (Checked Out) and the @NewLevel is 1 (Published), the document's CheckOutUserId, CheckoutDate, and CheckoutExpires values MUST be set to NULL, and the document's container (document library or list) value for tp_CheckOutUserId MUST be set to NULL.

@ModerationStatus: An integer value indicating the specified document's Moderation Status (section 2.2.3.13).

@EnableMinorVersions: A bit indicating whether minor versions are enabled within the containing list. If the list containing the specified document has minor versions enabled, then this MUST be set to 1; otherwise, this MUST be set to 0.

@Moderated: A bit indicating whether moderation is enabled on the containing list. If the list containing the specified document has moderation enabled, then this MUST be set to 1; otherwise, this MUST be set to 0.

@CreateVersion: A bit indicating whether versioning is enabled on the containing list. If the list containing the specified document has versioning enabled, then this MUST be set to 1; otherwise, this MUST be set to 0.

@UserId: A user identifier (section 2.2.1.13) for the user requesting the document change. This value MUST refer to an existing user identifier for the specified site collection.

@Comment: Descriptive text associated with the document on check in or publishing. When the document publishing level is updated from "Check Out" (255) to any other value, or from any value to "Publish" (1), @Comment can be set to a descriptive string or it can be NULL. In all other Publishing Level type value transitions, this parameter MUST be NULL.

@bUpdateModified: A bit indicating if change to the last modified date and time properties of the document is requested. If @bUpdateModified is set to 1, then proc_ChangeLevelForDoc MUST update document last modified date and time properties in the store to note that the document was updated at the current time. Otherwise, the last modified date and time properties MUST be left unchanged.

@@DoclibRowId: An output parameter containing the value of the DoclibRowId column in the Docs View (section 2.2.7.4) for the document after the change.

@@DocUIVersion: An output parameter containing the UI version of the document after the change.

@@DocFlagsOut: An output parameter containing the Doc Flags (section 2.2.2.3) of the document after the change.

@@DocVersionOut: An output parameter containing the internal version number of the document after the change.

@RequestGuid: The optional request identifier for the current request.

Return Values: The proc_ChangeLevelForDoc stored procedure returns an integer return code, which MUST be included in the following table.

Value

Description

0

Successful execution.

87

The specified document could not be found, or the specified publishing level is not the current level of the specified document.

The proc_ChangeLevelForDoc stored procedure MUST NOT return a result set.