 | ||
|
| ||
| ||
|
| ||
Wayne Berry
Editor, 15 Seconds
January 12, 1998
Download this
document in Microsoft Word format (zipped, 8.4K).
Contents
Introduction
The Basics
Properties
Methods
Arguments
Collections
The Default Method or
Property
Instantiating an Object
Built-in COM Objects
ProgID
The Documentation
Read and Write Properties
Read-Only Properties
Optional Method Arguments
Summary
If you are an Active Server Pages (ASP) developer, you have already used Component Object Model (COM) objects to create your ASP pages. However, unless you have developed COM objects or read a detailed book on COM, you might not know about the multitude of COM objects that you can use in ASP. Also, without sufficient COM knowledge, you might not be able to infer the methods and properties that exist for those objects when reading the documentation. One of the wonderful things about COM is that once you learn the standards and restrictions, you can quickly learn to implement other COM objects. In this tutorial, I explain how COM works from the perspective of someone who writes Visual Basic® Scripting Edition (VBScript), and this knowledge will help you master the world of COM.
This tutorial demonstrates the basics of COM to those familiar with VBScript and COM objects, and is especially useful to those who have used COM objects like ActiveX™ Data Objects (ADO) without knowing that they are COM. This tutorial is for you if have ever wondered any of the following:
COM is the
standard for the interface to objects. By definition, COM
objects have only methods and properties; there are no
other interfaces. There isn't much difference between
properties and methods from a programmer's standpoint:
Methods can take arguments, properties can't. Properties
can be read/write; methods -- if they return a value -- are
read-only.
Component designers use methods and properties for different functionality. Properties usually represent some aspect of the object's state, whereas a method can be a function that performs regardless of whether the object's state is involved.
Properties do not take any arguments and are usually used to describe or set the state of an object. All properties return a value, however some properties are read-only, and some are read/write. Here is an example of the VBScript syntax for reading a property:
Example 1
value = object.property
Note there are no parentheses, not even a blank set; that is, (). Here is the Visual Basic(r) syntax for setting a property:
Example 2
object.property = value
Methods can return values and take arguments. They are most often used to initiate an event within the object. Methods can be used to set values, but only when passing the value through the argument list. If a method returns a value but doesn't take an argument, the syntax will be:
Example 3
value = object.method()
Note in Example 3 that the method has a set of blank parentheses. Methods that have a return value must have arguments encapsulated in parentheses. For example, the Connection object has an Execute method that returns a RecordSet object. Here is an example:
Example 4
Set RS = Conn.Execute("SELECT * FROM TABLE")
Methods that do not return values do not have parentheses around the arguments. For example, the Close method of the Connection object is not encapsulated in parentheses:
Example 5
Conn.Close
Methods can take one or more arguments, or take none at all. However, arguments might be optional. If they are, you do not have to enter anything for an argument. Once one argument is optional, all arguments following it are also optional. For example, if arguments one and two are required, and three is optional, argument four has to be optional. A good example of an optional argument method is the Open method of the Connection object. The Open method has eight optional arguments. The first three are for establishing the database and the logon information. You can call the Open method as in Example 6:
Example 6
Conn.Open "DSN","sa",""
This indicates a DSN of "DSN", a logon of "sa", and a password of "". You can also call the Open method as in Example 7.
Note that we used three of the optional arguments in Example 6 and we used only one in Example 7, with the same result.
Calling the arguments by delimiting with the argument and leaving it blank causes the method to execute with nulls instead of the optional argument's default values. In Example 6, the default value of the optional arguments is used. In Example 8, nulls are used for the optional arguments:
Example 8
Conn.Open "DSN","sa","", , , ,
Example 8 calls the optional methods with null values, which is different than Example 6.
Collections are objects that represent a set of objects. All collections have predefined methods and properties. A collection object has an Item method, a Count property, and a _NewEnum method. A collection can also create objects of the collection type. In other words, if a particular object can be grouped in a set, that object will have a collection object that can create an instance of an object within the set. For example, a Drives collection object will contain a set of drives that can represent all the drives on a particular computer.
The Count property returns a LONG value that specifies how many objects are in the collection. By passing a LONG value -- that is between one and the value returned by the Count property -- to the Item method, the collection method will return the object in the set that is associated with that position. Accessing an item in an array works similarly.
The _NewEnum method enables a programmer to iterate through the collection in a For…Next statement. Example 9 shows _NewEnum in action:
Example 9
For Each Object in Collection ... Next Object
Note that the _NewEnum method is not referenced within the syntax of the statement in Example 6. This is because the _NewEnum method has a special index that is used for the For…Next statement. In fact, all methods and properties in a COM object are indexed and certain indexes are used for particular tasks. For example, the zero index is used for the default method or property.
The method or property that has the COM index of zero is called the default property. Visual Basic enables a programmer to not use the regular method/property syntax when calling the default value; you can leave the syntactical call to the method/property off altogether. For example, the default method in all collections is the Item method. Example 10 shows how to call the Item method:
Example 10
Set Object = Collection.Item(2)
This would get the second item in the collection and assign the object variable to that object. Because the Item method is the default method, you can also call the Item method as in Example 11:
Example 11
Set Object = Collection(2)
Note that both the period and the actual name of the method are missing; only the argument to the method remains.
To create an instance of a COM object in ASP, you can use a statement like the following:
Example 12
Set Object Server.CreateObject("SMUM.XCheck.1")
There is only one argument to the CreateObject method of Server that is the ProgId (the program ID). The ProgId is assigned by every component vendor to uniquely identify the COM object. To create an instance of the COM object, you must know the ProgId of the COM object.
There is another way to get an instance of a COM object. You can have another COM object create the object and return the newly created object to you. This is how a collection works. You call the Item method of a collection, and a COM object is returned that represents the subset of the collection, which you index. Whenever a COM object is returned by another object, you must preface the statement with Set as in Example 13:
Example 13
Set Object = Collection.Item(2)
Because Server is a COM object, Examples 12 and 13 are much alike. They both return COM objects with a call to another COM object. The difference is that the CreateObject method of the Server object can return any COM object, and the Item method can only return COM objects that are stored in the collection. If you need to have a COM object to create another COM object, where did the Server object come from? ASP has a set of built-in COM objects that solve this chicken-or-the-egg problem.
There are six built-in COM objects in the ASP environment:
The difference between these COM objects and the others is that you do not need to create an instance of these objects to call them. Built-in objects are present in the page without instantiation. They adhere to all the other rules of COM and have their own methods and properties. You do not need to know their ProgIds because you don't have to call the CreateObject method to instantiate them.
If one of the major ways to create a COM object is by using the CreateObject method, knowing the ProgIds of the objects you are creating is very important. So where are the ProgIds located? The component vendor should supply the component ProgIds as part of the documentation.
However, not all ProgIds are supplied, because a vendor doesn't always want you to create an instance of the object using the CreateObject method. Some objects inherit properties from the object that creates them, so if they are not created from calling a method in that object they are not initialized correctly. For example, creating an instance of an ADO Field object would not do you much good without going through the RecordSet object, because the ADO Field object would not contain any data unless you went through the RecordSet object.
Now that we have established the differences between methods and properties along with their different attributes, we need to understand how the documentation for the objects represents these attributes. For example, we are going to look at 15 Seconds' component section, which is in the same format as the IIS 4.0 component documentation.
A good example of a read/write property is that of the PhoneTranslate property of the XCheck object, shown here in Example 14:
Example 14
object.PhoneTranslate[= value]
Note the value syntax -- this indicates a property to which
you can write. The brackets denote that the property is
optional, that is, you do not need to set the property to
use the object. Here's a pointer to the full documentation on the 15 Seconds
site.
A good example of a read-only property is the Expires property of the ASPMail object.
Example 15
object.Expires
Note that, unlike Example 14, there is no equal symbol,
which indicates that this property is read-only. Here's a
pointer to the full documentation on the 15 Seconds
site.
A good example of the optional arguments is the SendX method of the OCXMail object. The documentation syntax can be seen here in Example 16.
Note that the only required argument is in the mailserver
argument. All the others, as indicated by the brackets, are
optional. Here's a pointer to the full documentation on the 15 Seconds
site.
With a fundamental understanding of COM, its abilities, and good documentation, you can expand the flexibility of your ASP programming. Take the information that you already know about programming Internet Information Server (IIS) objects, like Session objects and ADO, and expand on that by adding more COM objects to your repertoire. Third-party COM objects will enable you to expand your Active Server applications and accomplish tasks rapidly by leveraging the Component Object Model.
15
Seconds is a free
Internet resource for developers working with Microsoft
Internet Solutions and product lines of Sign Me Up
Marketing
SMUM is a leader in
Internet marketing. Established in 1996, SMUM is a
Seattle-based business owned by Wayne Berry, a well-known
global programming consultant and co-author of Active X
Programming Unleashed, Windows NT 4 Registry, and IIS 4.0
Special Edition.
Did you find this material useful? Gripes? Compliments? Suggestions for other articles? Write us!
© 1999 Microsoft Corporation. All rights reserved. Terms of use.
Back to top