Click or drag to resize

IMcObjectsCheckForLegalName Method

Checks a name string for legal syntax and collision with existing names. Optionally produces a legal name based on the supplied name.

Namespace:  MediaCy.IQL.ObjectManager
Assembly:  MediaCy.IQL.ObjectManager (in MediaCy.IQL.ObjectManager.dll) Version: 10.0.6912.0
Syntax
VB
Copy
Function CheckForLegalName ( 
	bstrName As String,
	<OptionalAttribute> varParentIMcObject As Object,
	Optional bstrNamespace As String = "",
	<OptionalAttribute> <OutAttribute> ByRef pvarbstrClosestLegalName As Object,
	Optional lStartingNumberToPostpend As Integer = -2,
	<OptionalAttribute> <OutAttribute> ByRef pvarlNumberPostpended As Object
) As Integer

Parameters

bstrName
Type: SystemString
[in] McObject name to check. The name may NOT use the "double colon" syntax for namespaces; if any '::' is found in the name string, then a zero is returned. If the name has a trailing number, that will be used as the starting number for lookups, overriding any lStartingNumberToPostpend argument. VARIANT varParentMcObject - : [in, optional] The parent object of the McObject that will be given the tested name. Missing (VT_EMTPY, VT_ERROR or VT_NULL), implies an object with no parent.
varParentIMcObject (Optional)
Type: SystemObject
bstrNamespace (Optional)
Type: SystemString
[in, optional] Namespace to use for the lookup of the object name supplied by bstrName, or NULL or empty to use the default Namespace (see the Namespace property, and the Item method). Supply a value of "::" (double colon) to specify the global namespace, irrespective of the current default Namespace property.
pvarbstrClosestLegalName (Optional)
Type: SystemObject
[out, optional] If given, the closest legal name to the bstrName is returned as a VT_BSTR variant.
lStartingNumberToPostpend (Optional)
Type: SystemInt32
[in, defaultvalue(-2)] The first number to postpend to the name. If this is negative (-2 is the default), then bstrName is first looked up with no number postpended, and only if a name collision occurs is a number postpended for more lookups; the initial number postpended is -lStartingNumberToPostpend-1 (e.g., 1 for the -2 default). If lStartingNumberToPostpend is positive, then it is postpended for the initial lookup, and then incremented as necessary until there is no name collision. If the supplied bstrName has a trailing number, then that value is used instead of this one. If lStartingNumberToPostpend is the special value of 0x80000000, then a number is never postpended, even if there is a name conflict. In this case the returned pvarbstrClosestLegalName will be a "parseable" name of suitable length, but may also be the same as the name of an existing McObject.
pvarlNumberPostpended (Optional)
Type: SystemObject
[out, optional] The number actually postpended to the name is returned via this argument. You can use this value+1 as lStartingNumberToPostpend in subsequent calls if you want numbers postpended to NOT repeat as names with lower numbers are deleted. Otherwise, just keep passing lStartingNumberToPostpend in as -2, -1, 0 or 1, depending on how you want the name numbering to start (i.e., no number then 1, no number then 0, at zero or at one, respectively). If no number was postpended, then a negative value will be returned.

Return Value

Type: Int32
Plus or minus the length of the resulting pvarbstrClosestLegalName string. It will be the negative length if the original string was changed in any way (including postpending a number) in order to make it parseable and/or to avoid name collisions. Any value except zero indicates that the returned pvarbstrClosestLegalName string can be sucessfully passed to the Add method (along with the associated varParentIMcObject and bstrNamespace). A value of zero indicates that not even one character could be salvaged from the bstrName argument (e.g., maybe it was all numbers).
Remarks
In order to be parseable by programming languages, McObject names must contain only alpha or numeric characters or the underscore character, and may not begin with a numeric. Names are limited to 195 characters. Furthermore, object names must not collide with the names of other McObject's sharing the same parent McObject in the same namespace. The name to be checked is first tested to see if it is a file specification. If the name is a file specification, then only the FileName.Ext portion is retained (i.e., the leading drive and path specification portion is removed). Then the name is converted into a parseable name by removing all illegal leading and trailing characters and substituting underscores for any interior illegal characters (including the "dot" before the "Ext" portion of any file name). If this process leaves a name of one or more characters, then a lookup is made to test for collision with existing names. If a collision is found, a number is postpended to the name and incremented until no collision is found. You can supply a starting number for the postpended number or indicate whether a number should always be postpended. The method returns plus or minus the number of characters in the final legal name (the negative number if any change had to be made to the supplied name). Optional return values are the "legalized" name and any number that needed to be postpended. This method can be used both to test for a legal name (the return value will be less than some minimum desired length if the name is too short or had to be changed). Or it can be used to synthesize a legal name from user input (though note that you must always check for a zero return value, since some user input will be so badly formed that zero is returned and no legal name will be synthesized). The reason that the "::" syntax is disallowed here, while it is allowed in the Add and ChangeObjectName methods (where the name will presumably be used), is that this method will mostly be used to coerce user input into legal form. This will almost never involve having the user input "::" syntax; it would just confuse things. Thus, any '.' in the string is converted to an underscore and the presence of any '::' in the name string is considered an error, and a zero is returned.
See Also