<TD width="320" valign="TOP"><FONT color="#000000">Describes the data as passed by reference</FONT></TD>
</TR>
<TR>
<TD width="60" valign="TOP">VT_ARRAY</TD>
<TD width="320" valign="TOP"><FONT color="#000000">An OLE Safearray</FONT></TD>
</TR>
</TABLE>
<BR>
In Perl, Automation and creation of Automation objects is provided by the Win32::OLE module,
Furthermore, Variant data types can be converted by the Variant() method or the OLE module although
Perl seamlessly takes care of most of the conversion needed.<BR>
<BR>
<A name="createwsc"></A>
<H2>Creating Windows Script Component's</H2>
When it comes to writing a WSC, it is a surprisingly quick and easy process. In fact, anybody who
has written an ASP page with some script commands and HTML will have completed a WSC in less than
five minutes. And although .wsc files are Extensible Markup Language (XML) files, no previous
experience with XML is necessary in order to build a successful component.<BR>
<BR>
<A name="10steps"></A>
<H3>Ten Easy Steps</H3>
In order to create a WSC, you can use the Windows Script Component Wizard. The wizard will produce a
valid skeleton for your WSC, and all you will have to do is enter your PerlScript. Let's create a
simple WSC that can be instantiated within a script and holds the basic functionality of being
passed a string and retuns the reversed string, so follow me on these steps.<BR>
<ol>
<li> Open the Windows Script Component Wizard</li>
<li>Enter "Easy" in the component name-field; progID automatically
becomes Easy.WSC, which is fine.</li>
<li>Click "Next"</li>
<li> Set the "Language"-option for the component to "Other"
and enter "PerlScript"</li>
<li> Click "Next"</li>
<li> Click "Next" in the "Properties" window</li>
<li> Enter "SayHello" as a method with no parameters</li>
<li> Click "Next"</li>
<li> Click "Next" in the "Events" windows</li>
<li> Click "Finish" </li>
</ol>
<A name="impps"></A>
<H4>Implementing the PerlScript</H4>
Following the simple steps above will create a nice skeleton to hold your code. With the exception
for the classid, which is unique each time one is generated, it will look as illustrated.<BR>
<pre>
<?xml version="1.0"?>
<component>
<registration
description="Easy"
progid="Easy.WSC"
version="1.00"
classid="{74bb1ba9-2e69-4ad6-b02c-c52f3cbe153b}"
>
</registration>
<public>
<method name="SayHello">
</method>
</public>
<script language="PerlScript"><BR>
<![CDATA[
]]>
</script>
</component>
</pre>
As seen above, you have a Window Script Component that is an XML file. The first declaration of the WSC enables strict XML. In that mode, the elements and attributes are case-sensitive, and attribute values must be enclosed within single quotes or double quotes. You may omit the XML declaration on top of the document and it will not be compiled as strictly, but in these examples, we will stick with XML conformity and leave the declaration in each document. To note about XML elements is that they, like HTML, have end-tags like "<registration>" and "</registration>"; however, as you will see, you can replace the end-tag in some operations by simply writing "<registration/>".
<P>
Secondly, you have a component element. This element is used to enclose each component. You will place one at the beginning, and one at the end. As an exception to the rule, there is an element that has a higher priority than the component, and that element must be used whenever you keep more than one component in your WSC file. Is is the package element. It will as a single element enclose all components; however, as mentioned, it is not required when you have one component within the file.
<P>
Next, the registration element contains the information about your component such as the progid, classid, description, and version number. Description is a string in which you can write a short abstract summary the funcitonality of your component. The progid is used by the program which creates an instance of your component, and the version number should be incremented if you release a new version of your component. The version number can also be appeneded to the progid as as Easy.WSC.1.00 when creating the instance of your component.
<P>
After the registration element, the data and functionality that the component expose are defined. The public element will hold properties, methods, and events. We declare a method by the name "SayHello" and then skip on down to the script-elements. As you can tell, there is no source code, so we need to fill that out. In the empty space, enter the following:
<P>
<pre>
sub SayHello {
my($param) = shift @_;
return reverse($param);
}
</pre>
<BR>
Aside of the elements that we've covered, it should look as below.<BR>
<pre>
<script language="PerlScript">
<![CDATA[
sub SayHello {
my($param) = shift @_;
return reverse($param);
}
]]>
</script>
</pre>
<BR>
<A name="regcom"></A>
<H4>Registering the Component</H4>
<p>Now, it's time to register the component on the system so that it can be used.
There are two ways to do this and we assume that the file is saved as c:\easy.wsc.</p>
<ol>
<li>Enter command-prompt and issue regsvr32 c:\easy.wsc</li>
<li> Locate it from Windows Explorer, right-click on the file and then choose
"Register". </li>
</ol>
<BR>
Either one of the above methods for registering a component should notify you upon success or
failure. After registering the component, you can use it from within Active Server Pages by
authoring a small script.<BR>
<pre>
<%@Language=PerlScript%>
<%
$obj = $Server->CreateObject('Easy.WSC');
$retval = $obj->SayHello("Hello World");
$Response->Write($retval);
%>
</pre>
<br>
<A name="comprop"></A>
<H3>WSC with Properties and Notification</H3>
Next, let's look at how to get a few properties included in the component, too. The following
example will display how to read and write properties.It also includes comments, and, in addition, a
custom subroutine is run when the component is registered and unregistered. What will happen is that
when the component has been registered, a message box pops up with the text "Windows Script
Component says: First.WSC has been registered!" and a similar tailored message when the
component is unregistered by either oone of the ways previously shown. So, open up the Windows
Script Component wizard, again, and this time enter the read/write property "YourName",
and the method "SayHello." The property is a global variable, and it internally is read
and written by subroutines that implement the functionality needed for performing the given
operation. The property can either use "get" and "set" attributes that point to
the mentioned subroutines or there can be separate "get" and "set" elements as
in the example. Their values point to internal Perl subroutines that do their thing on the property.
It is a simple example, and it is as follows.<BR>
<pre>
<?xml version="1.0"?>
<component>
<registration
description="First"
progid="First.WSC"
version="1.00"
classid="{d0ccb637-bd0c-4c90-a4bd-7473f499d35a}"
>
<comment>
This makes the messagebox pop up on registration and unregistation
</comment>
<script language="PerlScript">
<![CDATA[
sub register {
use Win32;
Win32::MsgBox('Windows Script Component says: First.WSC has been registered!');
}
sub unregister {
use Win32;
Win32::MsgBox('Windows Script Component says: First.WSC has been unregistered!');
}
]]>
</script>
</registration>
<comment>
The methods and properties to expose to the data consumer
</comment>
<public>
<property name="YourName">
<get internalName="hiddenGetProperty"/>
<put internalName="hiddenSetProperty"/>
</property>
<method name="SayHello">
</method>
</public>
<comment>
The code that implements the functionality of the component
</comment>
<script language="PerlScript">
<![CDATA[
use vars qw($YourName_Property);
sub hiddenGetProperty {
return $YourName_Property;
}
sub hiddenSetProperty {
my($param) = shift;
$YourName_Property = $param;
}
sub SayHello {
return "Hello $YourName_Property!";
}
]]>
</script>
</component>
</pre>
<BR>
<A name="elementref"></A>
<H2>XML Element Reference</H2>
Windows Script Components use XML to mark up the definition of the component and
what is exposed by the component. Listed below are the elements that are valid
XML elements for use within WSC components..<br><A name="elemcom"></A>
<H3>The Component Element</H3>
The component element is used to define the beginning and the end of the components.
It encapsulates all other WSC tags as illustrated.<BR>
<BR>
<pre>
<component>
.
.
.
</component>
</pre>
<br>
<A name="elemcom"></A>
You can also set a boolean value of true (1) or false (0) for error checking or debugging by using <CODE><? component error="true" debug="true" ?></CODE>
In case your file will contain more than one component, you use a <CODE>&component id=componentID></CODE> element for each, and you are required to then enclose all components within a <CODE><package></CODE> element.
<A name="elemcom"></A>
<pre>
<package>
<component id="ComponentA">
.
.
.
</component>
<component id="ComponentB">
.
.
.
</component>
</package>
</pre>
<BR>
<BR>
The default value for the component ID is ComponentCoClass, and when you define
your own, either to identify the components or for generating a typelibrary, the
name must be unique and it must begin with a letter and contain no spaces.<BR>
<BR>
When using more than one component within a package, you can create instances
of the other component within the current component by calling the <CODE>createComponent(componentID)</CODE>
function.<br> <A name="elemreg"></a>
<H3>The Registration Element</H3>
<CODE><registration></CODE> contains the necessary information in order
to successfully register the component as a COM component, and it has two ways
of writing. Syntax: <br>
<pre>
<registration
progid="progID"
classid="GUID"
description="description"
version="version"
[remotable=remoteFlag]
/>
</pre>
or <A name="elemreg"></a>
<pre>
<registration
progid="progID"
classid="GUID"
description="description"
version="version"
[remotable=remoteFlag]
>
<script>
(registration and unregistration script)
</script>
</registration>
</pre>
<BR>
<BR>
Most of the element attributes have been discussed in the introduction to the
COM. However, remotable, which is optional, specifies if the component can be
instantiated using DCOM. Its value can be true or false.<BR>
<BR>
<A name="elempub"></a>
<H3>The Public Element</H3>
The public element implements Automation, formerly known as OLE Automation, and
within the public elements you define the properties, methods, and events that
the component exposes after it has been registered. This is done using the property,
method, and event elements.
<pre>
<public>
<property name="myProperty"/>
<method name="myMethod"/>
<event name="myEvent"/>
</public>
</pre>
<A name="elemprop"></a>
<H4>The Property Element</H4>
Property declares a property exposed by the component. Syntax:
