ICatalogManager3::CreateProperty Method [C++]

Article
11/12/2009

Use this method to create a new property.

Definition

[C++]

HRESULT ICatalogManager3::CreateProperty(BSTRstrPropertyName,
  CatalogDataTypeEnumeDataType,
  VARIANTvarMaxLength,
  _Recordset**ppRSProperty);

[Visual Basic]

Function CreateProperty(strPropertyName As String,
  eDataType As CatalogDataTypeEnum,
  Optional varMaxLength As Variant) As Recordset

Parameters

strPropertyName[C++]
[in] A BSTR that contains the name of the new property. This parameter cannot begin with a digit or contain a period (.); it can only contain characters that are acceptable in XML tags.
strPropertyName[Visual Basic]
A String that contains the name of the new property. This parameter cannot begin with a digit or contain a period (.); it can only contain characters that are acceptable in XML tags.
eDataType[C++]
[in] An enumeration value that specifies the data type of the new property. See the Remarks section for valid values.
eDataType[Visual Basic]
An enumeration value that specifies the data type of the new property. See the Remarks section for valid values.
varMaxLength[C++]
[in, optional] A VARIANT that contains the maximum length for the property. Even though this parameter is an optional value it must be given if the data type of the property is cscString. Properties of data type cscEnumeration have a fixed default value of 128 characters, which cannot be changed. Properties of data type cscFilePath have a fixed default value of 256 characters, which cannot be changed.
varMaxLength[Visual Basic]
A Variant that contains the maximum length for the property. Even though this parameter is an optional value it must be given if the data type of the property is cscString. Properties of data type cscEnumeration have a fixed default value of 128 characters, which cannot be changed. Properties of data type cscFilePath have a fixed default value of 256 characters, which cannot be changed.
ppRSProperty[C++]
[out, retval] A pointer used to return a Recordset object that will contain the new property.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object that contains the property attributes.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Name	Value	Description
E_CAT_CATMGR_NOT_INITIALIZED	[C++] 0x889800B5 [Visual Basic] &H889800B5	The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_PROPERTY_NAME	[C++] 0x889800A2 [Visual Basic] &H889800A2	The PropertyName you specified is invalid. property Names cannot be blank and cannot exceed 100 characters. property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_INVALID_DATATYPE	[C++] 0x88980074 [Visual Basic] &H88980074	The datatype you specified is invalid.
E_CAT_INVALID_PARAMETER	[C++] 0x889800B6 [Visual Basic] &H889800B6	The input parameter <parameter number> is invalid.
E_CAT_INVALID_COLUMN_LENGTH	[C++] 0x88980040 [Visual Basic] &H88980040	The length specified for this property does not lie between 1 and 4000.
E_CAT_INVALID_DATATYPE_FOR_ATTRIBUTE	[C++] 0x889800A6 [Visual Basic] &H889800A6	The enumeration or filename data types cannot be used for creating property attributes.
E_CAT_INBUILT_PROPERTY	[C++] 0x8898003E [Visual Basic] &H8898003E	The property name you specified is used as a Catalog Management Inbuilt property name.
E_CAT_PROP_EXISTS	[C++] 0x88980003 [Visual Basic] &H88980003	The property name you specified already exists.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The ppRSProperty parameter contains valid data only if the property was accessed successfully.

[Visual Basic] The Recordset object returned by this property is valid only if it is accessed successfully.

Property names, and therefore the strPropertyName parameter, are limited to a maximum length of 100 characters.

[C++] This method returns a single row Recordset object containing the newly created property. For more information about the fields in this Recordset object, see PropertyAttribute Recordset.

[Visual Basic] This method returns a single row Recordset object containing the newly created property. For more information about the fields in this Recordset object, see PropertyAttribute Recordset.

The following table shows the values of the CatalogDataTypeEnum enumeration, their associated names, and describes their use.

Name	Value	Description
cscInteger	0	Indicates an exact numeric value that holds whole numbers from –2[31] (-2,147,483,648) <= n <= 2[31] –1 (2,147,483,647).
cscBigInteger	1	Indicates an exact numeric value with precision 19 (if signed) or 20 (if unsigned), and scale 0 (signed: –2[63] <= n <= 2[63] – 1, unsigned: 0 <= n <= 2[64] – 1) [3], [9].
cscFloat	2	Indicates a positive or negative floating-point number. The range of positive values is approximately 2.23E –308 through 1.79E 308, and the range of negative values is approximately –2.23E –308 through –1.79E 308.
cscDouble	3	Indicates a positive or negative floating-point number. The range of positive values is approximately 2.23E –308 through 1.79E 308, and the range of negative values is approximately –2.23E –308 through –1.79E 308.
cscBoolean	4	Indicates a Boolean (bit), holds either a 1 or 0. Integer values other than 1 or 0 are accepted but are always interpreted as 1.
cscString	5	Indicates a variable-length character string with a maximum string length of 4000 characters.
cscDateTime	6	Indicates a Microsoft SQL Server DateTime data type.
cscCurrency	7	Indicates a Microsoft SQL Server money data type.
cscFilePath	8	Indicates a String that holds a file path.
cscEnumeration	9	Indicates an Integer associated with a defined constant.
cscText	10	Indicates a Microsoft SQL Server NText data type.
cscInvalid	-1	Reserved for future use.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.