3.1.5.4 proc_AddListItem

The proc_AddListItem stored procedure is invoked to add a list item to a list or document library.

PROCEDURE proc_AddListItem (
      @SiteId                        uniqueidentifier,
      @WebId                         uniqueidentifier,
      @ListID                        uniqueidentifier,
      @RowOrdinal                    int,
      @ItemId                        int                           OUTPUT,
      @UserId                        int,
      @Size                          int,
      @TimeNow                       datetime,
      @CopySecurityFromMasterID      int                = NULL,
      @ExtraItemSize                 int                = NULL,
      @CheckDiskQuota                bit                = 1,
      @ItemDocType                   tinyint            = 0,
      @BaseRowItemId                 int                = NULL,
      @DocIdAdded                    uniqueidentifier   = NULL,
      @RetainId                      uniqueidentifier   = NULL,
      @RetainObjectIdentity          bit                = 0,
      @Level                         tinyint            = 1,
      @UIVersion                     int                = 512,
      @ItemCountDelta                int                = 1,
      @ItemName                      nvarchar(255)      = NULL,
      @UseNvarchar1ItemName          bit                = 1,
      @ItemDirName                   nvarchar(256)      = NULL     OUTPUT,
      @ItemLeafName                  nvarchar(128)      = NULL     OUTPUT,
      @ServerTemplate                int                = NULL,
      @IsNotUserDisplayed            bit                = NULL,
      @BaseType                      int                = NULL,
      @CheckSchemaVersion            int                = NULL,
      @OnRestore                     bit                = 0,
      @AddNamespace                  bit                = 0,
      @tp_Ordering                   varchar(512)       = NULL,
      @tp_ThreadIndex                varbinary(512)     = NULL,
      @tp_HasAttachment              bit                = NULL,
      @tp_ModerationStatus           int                = 0,
      @tp_IsCurrent                  bit                = 1,
      @tp_ItemOrder                  float              = NULL,
      @tp_InstanceID                 int                = NULL,
      @tp_GUID                       uniqueidentifier   = NULL,
      @tp_Id                         int                = NULL,
      @tp_Author                     int                = NULL,
      @tp_Editor                     int                = NULL,
      @tp_Modified                   datetime           = NULL,
      @tp_Created                    datetime           = NULL,
      @tp_Version                    int                = 1,
      @tp_ContentType                nvarchar(255)      = NULL,
      @tp_ContentTypeId              varbinary(512)     = NULL,
      @tp_CopySource                 nvarchar(260)      = NULL,
      @tp_HasCopyDestinations        bit                = NULL,
      @tp_WorkflowVersion            int                = 1,
      @tp_WorkflowInstanceID         uniqueidentifier   = NULL,
      @nvarchar1                     nvarchar(255)      = NULL,
      @nvarchar2                     nvarchar(255)      = NULL,
      @nvarchar3                     nvarchar(255)      = NULL,
      @nvarchar4                     nvarchar(255)      = NULL,
      @nvarchar5                     nvarchar(255)      = NULL,
      @nvarchar6                     nvarchar(255)      = NULL,
      @nvarchar7                     nvarchar(255)      = NULL,
      @nvarchar8                     nvarchar(255)      = NULL,
      @nvarchar9                     nvarchar(255)      = NULL,
      @nvarchar10                    nvarchar(255)      = NULL,
      @nvarchar11                    nvarchar(255)      = NULL,
      @nvarchar12                    nvarchar(255)      = NULL,
      @nvarchar13                    nvarchar(255)      = NULL,
      @nvarchar14                    nvarchar(255)      = NULL,
      @nvarchar15                    nvarchar(255)      = NULL,
      @nvarchar16                    nvarchar(255)      = NULL,
      @nvarchar17                    nvarchar(255)      = NULL,
      @nvarchar18                    nvarchar(255)      = NULL,
      @nvarchar19                    nvarchar(255)      = NULL,
      @nvarchar20                    nvarchar(255)      = NULL,
      @nvarchar21                    nvarchar(255)      = NULL,
      @nvarchar22                    nvarchar(255)      = NULL,
      @nvarchar23                    nvarchar(255)      = NULL,
      @nvarchar24                    nvarchar(255)      = NULL,
      @nvarchar25                    nvarchar(255)      = NULL,
      @nvarchar26                    nvarchar(255)      = NULL,
      @nvarchar27                    nvarchar(255)      = NULL,
      @nvarchar28                    nvarchar(255)      = NULL,
      @nvarchar29                    nvarchar(255)      = NULL,
      @nvarchar30                    nvarchar(255)      = NULL,
      @nvarchar31                    nvarchar(255)      = NULL,
      @nvarchar32                    nvarchar(255)      = NULL,
      @nvarchar33                    nvarchar(255)      = NULL,
      @nvarchar34                    nvarchar(255)      = NULL,
      @nvarchar35                    nvarchar(255)      = NULL,
      @nvarchar36                    nvarchar(255)      = NULL,
      @nvarchar37                    nvarchar(255)      = NULL,
      @nvarchar38                    nvarchar(255)      = NULL,
      @nvarchar39                    nvarchar(255)      = NULL,
      @nvarchar40                    nvarchar(255)      = NULL,
      @nvarchar41                    nvarchar(255)      = NULL,
      @nvarchar42                    nvarchar(255)      = NULL,
      @nvarchar43                    nvarchar(255)      = NULL,
      @nvarchar44                    nvarchar(255)      = NULL,
      @nvarchar45                    nvarchar(255)      = NULL,
      @nvarchar46                    nvarchar(255)      = NULL,
      @nvarchar47                    nvarchar(255)      = NULL,
      @nvarchar48                    nvarchar(255)      = NULL,
      @nvarchar49                    nvarchar(255)      = NULL,
      @nvarchar50                    nvarchar(255)      = NULL,
      @nvarchar51                    nvarchar(255)      = NULL,
      @nvarchar52                    nvarchar(255)      = NULL,
      @nvarchar53                    nvarchar(255)      = NULL,
      @nvarchar54                    nvarchar(255)      = NULL,
      @nvarchar55                    nvarchar(255)      = NULL,
      @nvarchar56                    nvarchar(255)      = NULL,
      @nvarchar57                    nvarchar(255)      = NULL,
      @nvarchar58                    nvarchar(255)      = NULL,
      @nvarchar59                    nvarchar(255)      = NULL,
      @nvarchar60                    nvarchar(255)      = NULL,
      @nvarchar61                    nvarchar(255)      = NULL,
      @nvarchar62                    nvarchar(255)      = NULL,
      @nvarchar63                    nvarchar(255)      = NULL,
      @nvarchar64                    nvarchar(255)      = NULL,
      @int1                          int                = NULL,
      @int2                          int                = NULL,
      @int3                          int                = NULL,
      @int4                          int                = NULL,
      @int5                          int                = NULL,
      @int6                          int                = NULL,
      @int7                          int                = NULL,
      @int8                          int                = NULL,
      @int9                          int                = NULL,
      @int10                         int                = NULL,
      @int11                         int                = NULL,
      @int12                         int                = NULL,
      @int13                         int                = NULL,
      @int14                         int                = NULL,
      @int15                         int                = NULL,
      @int16                         int                = NULL,
      @float1                        float              = NULL,
      @float2                        float              = NULL,
      @float3                        float              = NULL,
      @float4                        float              = NULL,
      @float5                        float              = NULL,
      @float6                        float              = NULL,
      @float7                        float              = NULL,
      @float8                        float              = NULL,
      @float9                        float              = NULL,
      @float10                       float              = NULL,
      @float11                       float              = NULL,
      @float12                       float              = NULL,
      @datetime1                     datetime           = NULL,
      @datetime2                     datetime           = NULL,
      @datetime3                     datetime           = NULL,
      @datetime4                     datetime           = NULL,
      @datetime5                     datetime           = NULL,
      @datetime6                     datetime           = NULL,
      @datetime7                     datetime           = NULL,
      @datetime8                     datetime           = NULL,
      @bit1                          bit                = NULL,
      @bit2                          bit                = NULL,
      @bit3                          bit                = NULL,
      @bit4                          bit                = NULL,
      @bit5                          bit                = NULL,
      @bit6                          bit                = NULL,
      @bit7                          bit                = NULL,
      @bit8                          bit                = NULL,
      @bit9                          bit                = NULL,
      @bit10                         bit                = NULL,
      @bit11                         bit                = NULL,
      @bit12                         bit                = NULL,
      @bit13                         bit                = NULL,
      @bit14                         bit                = NULL,
      @bit15                         bit                = NULL,
      @bit16                         bit                = NULL,
      @uniqueidentifier1             uniqueidentifier   = NULL,
      @ntext1                        ntext              = NULL,
      @ntext2                        ntext              = NULL,
      @ntext3                        ntext              = NULL,
      @ntext4                        ntext              = NULL,
      @ntext5                        ntext              = NULL,
      @ntext6                        ntext              = NULL,
      @ntext7                        ntext              = NULL,
      @ntext8                        ntext              = NULL,
      @ntext9                        ntext              = NULL,
      @ntext10                       ntext              = NULL,
      @ntext11                       ntext              = NULL,
      @ntext12                       ntext              = NULL,
      @ntext13                       ntext              = NULL,
      @ntext14                       ntext              = NULL,
      @ntext15                       ntext              = NULL,
      @ntext16                       ntext              = NULL,
      @ntext17                       ntext              = NULL,
      @ntext18                       ntext              = NULL,
      @ntext19                       ntext              = NULL,
      @ntext20                       ntext              = NULL,
      @ntext21                       ntext              = NULL,
      @ntext22                       ntext              = NULL,
      @ntext23                       ntext              = NULL,
      @ntext24                       ntext              = NULL,
      @ntext25                       ntext              = NULL,
      @ntext26                       ntext              = NULL,
      @ntext27                       ntext              = NULL,
      @ntext28                       ntext              = NULL,
      @ntext29                       ntext              = NULL,
      @ntext30                       ntext              = NULL,
      @ntext31                       ntext              = NULL,
      @ntext32                       ntext              = NULL,
      @sql_variant1                  sql_variant        = NULL,
      @error_sql_variant1            int                = 0,
      @sql_variant2                  sql_variant        = NULL,
      @error_sql_variant2            int                = 0,
      @sql_variant3                  sql_variant        = NULL,
      @error_sql_variant3            int                = 0,
      @sql_variant4                  sql_variant        = NULL,
      @error_sql_variant4            int                = 0,
      @sql_variant5                  sql_variant        = NULL,
      @error_sql_variant5            int                = 0,
      @sql_variant6                  sql_variant        = NULL,
      @error_sql_variant6            int                = 0,
      @sql_variant7                  sql_variant        = NULL,
      @error_sql_variant7            int                = 0,
      @sql_variant8                  sql_variant        = NULL,
      @error_sql_variant8            int                = 0,
      @eventData                     image              = NULL,
      @acl                           image              = NULL
);

@SiteId: The Site Collection Identifier for the site collection containing the list that the list item is being added to.

@WebId: The Site Identifier for the site containing the list that the list item is being added to.

@ListID: The List Identifier of the list that the list item is being added to.

@RowOrdinal: The 0-based ordinal index of the current row to add for this list item in the set of rows representing the list item in the AllUserData table. If a list item requires multiple rows to represent it in the AllUserData table because it contains more defined data columns than will fit in a single row, the WFE MUST call proc_AddListItem again, with the additional data using the next row value in the @RowOrdinal parameter. This parameter MUST NOT be NULL.

@ItemId: An output parameter that returns the identifier of the list item that has been added:

  • If @ItemId is not NULL, proc_AddListItem MUST use the value specified by @tp_Id.

  • If @BaseRowItemId is not NULL, proc_AddListItem MUST use the value specified by @BaseRowItemId.

  • If @BaseRowItemId is NULL, proc_AddListItem MUST generate a new value for the List Item Identifier that is unique within the AllUserData table.

@UserId: The User Identifier for the current user. proc_AddListItem uses this for purposes of permission-checking. This value MUST refer to an existing User Identifier for the specified site collection.

@Size: The size in bytes of the list item row to be added. This parameter MUST NOT be NULL.

@TimeNow: The current time, in UTC format, on the BEDS.

@CopySecurityFromMasterID: Specifies the OPTIONAL identifier of the list item to copy the scope security settings from for this list item. A list item that represents an exception to a recurrence item in a Meetings List (that is, a list with a List Server Template Type of 200) MUST have the same scope security settings as the master recurrence item. If this parameter is set to a master recurrence item's List Item Identifier, then if the list item to be added does not share the scope of the master recurrence item, the new list item MUST be set to have a unique scope with a copy of the security settings from the scope of the master recurrence item. This parameter MUST only be set for list items that are exceptions to recurrence items in a Meetings List.

@ExtraItemSize: The size of the predefined SQL parameter fields in the list item row being added.

@CheckDiskQuota: A bit flag specifying whether Disk Quota should be checked for this user before adding the list item.

@ItemDocType: The Document Store Type of the list item being added to the list.

@BaseRowItemId: An OPTIONAL value specifying the identifier of the list item to be added, if a value is not supplied by the @tp_Id parameter. If the @tp_Id parameter is NULL and this parameter is not NULL, proc_AddListItem MUST use this value for the identifier of the list item to be added.

@DocIdAdded: The OPTIONAL document identifier of the document to be inserted as a list item in the list, if one exists. If @DocIdAdded is not NULL and the document has a document identifier, this parameter MUST be the existing document identifier. If this parameter is NULL, a new document identifier MUST be generated for the list item. If this list item is being restored to the list as part of a backup restore operation, as specified by the value of @RetainObjectIdentity, this parameter MUST be ignored, and the value of the @RetainId parameter MUST be used as the document identifier.

@RetainId: The document identifier of the document to be inserted as a list item in the list, if this list item is being restored to the list as part of a back-up restore operation.

@RetainObjectIdentity: A bit flag specifying whether this list item is being restored to the list as part of a back-up restore operation. If @RetainObjectIdentity is set to 1, this list item is being restored to the list as part of a back-up restore operation and MUST have the @DocIdAdded value specified in @RetainId.

@Level: The Publishing Level Type value specifying the publishing status of this list item.

@UIVersion: The UI version number for the list item.

@ItemCountDelta: The number to be added to the list item count of the containing list:

  • For a list item added with a single call to proc_AddListItem, or for one call for a list item with multiple rows to be added, this value MUST be 1.

  • For the other calls to proc_AddListItem for the additional rows to be added for the list item, this value MUST be 0.

@ItemName: The display name of the list item.

@UseNvarchar1ItemName: If @ItemName is NULL, this bit flag specifies whether to use the content of @nvarchar1 for the display name of the list item.

@ItemDirName: An output parameter containing the directory name of the list item.

@ItemLeafName: An output parameter containing the leaf name of the list item.

@ServerTemplate: The identifier for the List Server Template defining the base structure of the list containing this list item.

@IsNotUserDisplayed: A bit flag specifying whether the user name is not displayed with list items.

@BaseType: The List Base Type of the list containing the list item.

@CheckSchemaVersion: This specifies an OPTIONAL schema version number to compare with the list schema version number. If this parameter is not NULL, the version numbers MUST match for successful completion.

@OnRestore: A bit flag that specifies whether this list item is being inserted by a back-up restore operation.

@AddNamespace: A Boolean value specifying whether metadata is being added to the list item. This parameter MUST NOT be NULL.

@tp_Ordering: This parameter specifies the threading structure for this list item in a previous discussion board list (a list with a List Base Type of 3) as a concatenation of time stamp values in yyyyMMddHHmmss format. For all list items in lists with other List Base Types, this parameter MUST be NULL.

@tp_ThreadIndex: This specifies the list item's position within a threaded discussion board list (a list with a List Base Type of 3) as a binary structure. For all list items in lists with other List Base Types, this parameter MUST be NULL.

@tp_HasAttachment: A bit flag that specifies whether the list item has an associated attachment.

@tp_ModerationStatus: A Moderation Status value specifying the current moderation approval status of this list item.

@tp_IsCurrent: A bit flag that specifies whether this is the current version of this publishing level of the list item.

@tp_ItemOrder: This specifies the relative positioning order in which to view the list item when displayed with other List Items from the same list. This value can be the same as that of other List Items in the list.

@tp_InstanceID: If this list item is associated with a particular instance of a recurring meeting, this specifies the integer ID of that instance. For all other list items, this parameter MUST be NULL.

@tp_GUID: A List Item Identifier value that uniquely identifies this list item within the AllUserData table.

@tp_Id: The OPTIONAL integer identifier specified for this list item. If this parameter is not NULL, proc_AddListItem MUST use this value for the identifier of the list item to be added.

@tp_Author: The User Identifier for the user who created the list item.

@tp_Editor: The User Identifier for the user who last edited the list item.

@tp_Modified: A time stamp, in UTC format, that specifies when this list item was last modified.

@tp_Created: A time stamp, in UTC format, that specifies when this list item was created.

@tp_Version: Specifies the value to set for the counter used for internal conflict detection.

@tp_ContentType: Specifies the name of the content type for this list item.

@tp_ContentTypeId: Specifies the ID of the content type for this list item.

@tp_CopySource: Specifies the URL used as a source for this list item. If this list item was not copied from a source list item, this value MUST be NULL.

@tp_HasCopyDestinations: A bit flag specifying whether destination locations have been set for this list item to be copied to. If this list item does not have a destination location set, this value MUST be false.

@tp_WorkflowVersion: If this list item is part of a workflow, this parameter specifies the value to set denoting the state of this list item within that workflow. If this list item is not part of a workflow, this MUST be NULL.

@tp_WorkflowInstanceID: A Workflow Identifier that specifies the currently active workflow instance on this list item. If this item is not part of a workflow, this MUST be NULL.

The next nine columns are duplicated a variable number of times, depending on the List Item's content type within the view definition, with each column referring to a separate List Server Template-defined field or user-defined field within the containing list. Each instance of these individual column names is differentiated by a suffix with a value indicated in the column description, which replaces the placeholder '#' symbol shown as follows.

@nvarchar#: User-defined columns in the list containing values of type nvarchar. There are 64 columns numbered from 1 to 64. If the column contains no data, the value MUST be NULL.

@int#: User-defined columns in the list containing values of type int. There are 16 columns numbered from 1 to 16. If the column contains no data, the value MUST be NULL.

@float#: User-defined columns in the list containing values of type float. There are 12 columns numbered from 1 to 12. If the column contains no data, the value MUST be NULL.

@datetime#: User-defined columns in the list containing values of type datetime. There are eight columns numbered from 1 to 8. If the column contains no data, the value MUST be NULL.

@bit#: User-defined columns in the list containing values of type bit. There are 16 columns numbered from 1 to 16. If the column contains no data, the value MUST be NULL.

@uniqueidentifier: A user-defined column in the list containing values of type uniqueidentifier. If the column contains no data, the value MUST be NULL.

@ntext#: User-defined columns in the list containing values of type ntext. There are 32 columns numbered from 1 to 32. If the column contains no data, the value MUST be NULL.

@sql_variant#: User-defined columns in the list containing values of type sql_variant. There are eight columns numbered from 1 to 8. If the column contains no data, the value MUST be NULL.

@error_sql_variant#: An integer specifying the type to be applied to the corresponding values specified as arguments for the parameter @sql_variant#. The possible types are listed in the following table.

Value

Description

1

Convert the argument value to a varbinary(2).

2

Convert the argument value to a bit.

3

Convert the argument value to a float.

4

Convert the argument value to a datetime.

@eventData: Contains implementation-specific event data significant to the WFE, but otherwise opaque to the BEDS, to be stored by the BEDS for eventual writing to a log file.

@acl: The binary serialization of the WSS ACL Format ACL for the data supplied in @eventData, to be stored with the data.

Return Values: The proc_AddListItem stored procedure returns an integer return code, which MUST be listed in the following table, or MUST be a SQL Server @@Error result value.

Value

Description

0

Successful execution.

2

Postprocessing of the list item failed because a prerequisite list item was not found.

3

The directory specified for the list item does not exist.

5

The attempt to create a directory or document failed because the user does not have sufficient permissions.

13

The list item to be added is not valid.

16

Adding the list item caused updating of an existing list item to fail.

33

Cannot move directories that contain checked-out files.

50

A list item could not be deleted.

80

The document being added to the list already exists.

87

Unable to add the list item because the input parameters do not match existing list items, or an error occurred during a table update operation.

138

The list could not be moved to the specified location.

160

Could not create a unique filename.

161

A directory that spans sites cannot be moved.

183

The list item being added already exists in the list.

206

The file or directory name is too long.

212

The database for the site collection is locked.

1150

Failed to update the list.

1359

An internal error occurred while moving a list item.

1638

The current schema version of the list does not match the value in @CheckSchemaVersion.

1816

The site collection is over its allocated size quota.

8398

A directory could not be deleted.

The proc_AddListItem stored procedure MUST return no result sets.

 
Show: