|
Overview
If you are an Active Server page (ASP) developer, you have already used COM objects to create your ASP pages. However, unless you have developed COM objects or read a detailed book on COM, you might not understand COM enough to make use of the multitude of COM objects that are available to use in ASP. Also, without sufficient COM knowledge you might not be able to read some of the documentation that comes with other COM objects or infer the methods and properties that must exist. One of the wonderful things about COM is that once you learn the standards and the restrictions, you can use this knowledge to quickly learn how to implement other COM objects. In this Tutorial, we will try to explain how COM works from a Visual Scripter's reference point and give you the knowledge you need to master the world of COM.
The Audience
This tutorial is intended to demonstrate and describe the basics of the component object model to people that have used the Visual Basic Scripting language and COM, especially if you have used COM objects like ADO and didn't know that they are COM. This tutorial is for you if have ever wondered any of the following:
- What is the difference between a property and a method?
- Does a property take an argument?
- What does it mean for a property to be read only?
- What is a collection object?
- What properties are standard with every collection object?
- Why can I index a collection object without calling a method?
- How many COM objects can there be in a single DLL?
The Basics
COM is the standard for the Interface to objects. By definition COM Object only have methods and properties, there are not other interfaces. There isn't much difference between properties and methods from a programmer's standard point. Methods can take arguments, properties can't. Properties can be read/write, methods if they return a value, are read only.
Even though programmatically methods and properties are not much different, component designers use methods and property for different functionality. Properties usually represent some aspect of the state of the object. Where as a method can be a function to do anything whether it involves the state of the object or not.
Properties
Properties do not take any arguments and are usually used to describe the state of the object or to 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 Visual Basic Scripting syntax for reading a property:
Example 1
value = object.property
Notice there are no parenthesis, not even a blank set, i.e. (). Here is the Visual Basic syntax for setting a property:
Example 2
object.property = value
Methods
Methods can return values and take arguments, the are usually 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()
Notice in example 3 that the method has a set of blank parenthesis. Methods that have a return value must have arguments encapsulated with parenthesis. 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 parenthesis around the arguments. Such as the Close methods of the Connection Object:
Example 5
Conn.Close
Arguments
Methods can take one or more arguments, or take none at all. However, arguments might be optional, if they are, it is not required to enter anything for the argument. Once one argument is optional, all arguments following that are also optional. For example, if argument one and two are required, and three is optional, then argument four has to be optional too. A good example of an argument optional 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 login information. You can call the Open method like in example 6:
Example 6
Conn.Open "DSN","sa",""
To indicate a DSN of "DSN", a login of "sa", and a password of "". Or you can call the Open method like example 7:
Example 7
Conn.Open "driver=SQL Server;server=yourServerName;uid=someUID;" &_
"pwd=somePWD;database=someDatabase;"
Notice that in example 6 we used three of the optional arguments and in example 6 we used only one with the same result.
Calling the arguments by delimiting with and leaving the argument blank causes the method to be executed with nulls instead of the default value of the optional arguments. 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 then example 6.
Collections
Collections are objects themselves that represent a set of objects. All collections have predefined methods and properties. A Collection has an Item method, a Count property and a _NewEnum method. A collection also by definition has the ability to create objects of the collection type. In other words, if a particular object can be group in a set then that object will have a collection object that can create an instance of an object within the set. For instance, a Drives collection object will contain a set of drives that might 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 to the Item method, that is between one and the value returned by the Count property, the collection method will return the object in the set that is associated with that position. Accessing an item in an array works in similarly.
The _NewEnum method allows the programmer to iterate through the collection in a For Next statement. Example 9 is an example of _NewEnum in action:
Example 9
For Each Object in Collection
Next Object
Notice 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 Visual Basic recognizes as being used for the For Next statement. As a little background, 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 Default Method or Property
The method or property that has the COM index of zero is called the default property. Visual Basic allows the 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 all together. For example, the default method in all collections is the Item method. If you where going to call the Item method, you could do it like it in example 9.
Example 9
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 like in example 10:
Example 10
Set Object = Collection(2)
Notice that both the period and the actual name of the method are missing, only the argument to the method remains.
Instantiating an Object
To create an instance of a COM object in ASP, you can use a statement like the one in example 11:
Example 11
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. In order 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 a Set like in example 12:
Example 12
Set Object = Collection.Item(2)
Since Server is a COM object, example 11 and example 12 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, the Item method can only return COM object that are stored in the collection. So if you need to have a COM object to create another COM object, where did the Server object come from? To solve the chicken vs. the egg problem there are a set of built-in COM objects in Active Server Pages.
Built In COM Objects
In the Active Server page environment there are six built in COM objects:
- Server
- Request
- Response
- ObjectContext
- Application
- Session
The only different between these COM objects and all the others is that you do not need to create an instance of these COM objects in order to call them. Built in objects are present in the page without instantiation. They behave with all the other rules of COM and have their own methods and properties. Because these are built into the Active Server you do not need to know the ProgId, since you will not be calling the CreateObject method.
Prog Id
If one of the major ways to create a COM object is by using the CreateObject Method, then knowing the ProgIds of the objects you are creating is very important. So where are the ProgId located? The component vendor should be able to supply you with ProgIds for their components as part of the documentation.
However, not all ProgIds are available, the vendor doesn't always want you to create an instant 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 then they are not initialized correctly. For this reason the vendor doesn't always supply the ProgId since he would like you to get the object from calling one of the methods from another of the vendors objects. For example, creating an instance of a ADO Field object would not do you much good without the going through the RecordSet object, the ADO Field object would not contain any data.
The Documentation
Now that we have established the understanding between methods and properties along with their different attributes, we need to understand how the documentation for the objects represents these attributes. For examples, we are going to look at 15 Seconds' component section, which is in the same format as the IIS 4.0 component documentation.
Read and Write Properties
A good example of a read/write property is that of the PhoneTranslate property of the XCheck object, shown here in example 11:
Example 13
object.PhoneTranslate[= value]
Notice the value syntax, this is the indication of a property that can be written to. The brackets denote that the property is optional, in other words you do not need to set the property to use the object. Click here to view the full documentation.
Read Only Properties
A good example of a read only property is the Expires property of the ASPMail object.
Example 14
object.Expires
Notice that unlike example 11 there is not an equal symbol, indicating this is read only. Click here to view the full documentation.
Optional Method Arguments
A good example of the optional arguments is the SendX method of the OCXMail object. The documentation syntax can be seen here in example 12:
Example 12
object.SendX(mailserver[, fromName[, fromAddress[, priority[, returnReceipt[, toAddressList[, ccAddressList[, bccAddressList[, attach[, messageSubject[, messageText]]]]]]]]]])
Notice that the only required argument is the mailserver argument. All the rest, noted by the brackets are optional. Click here to view the full documentation.
Summary
With a fundamental understanding of COM and it's abilities, coupled with good documentation you can expand the flexibility of your Active Server page programming. Take the information that you already know about programming IIS objects, like Session objects and ADO, and expand on that by adding more COM objects to your repertoire. Third party COM object will allow you to expand your Active server applications and accomplish tasks rapidly by leveraging the component object model.
|
