Scripting Solutions with WSH and COM: Give Your PCs a Wake-Up Call

About 5 years ago, PC motherboard manufacturers implemented a new technology called Wake on LAN (WOL) that lets you remotely wake up PCs by sending a data packet, or magic packet, to them over the network. Products that support Wake on LAN include Computer Associates' (CA's) Unicenter TNG Framework, Hewlett-Packard's HP OpenView and HP Toptools, and IBM's Tivoli TME Network Management System.

Rather than purchase yet another product, however, why not use a script to remotely wake up your PCs? If you use NICs and have PCs that support Wake on LAN, you can take advantage of the SendMagicPacket.vbs and SendMagicPacketWithEvents.vbs scripts. To use these scripts, you need to meet several requirements. In addition, you need to know about the OLE custom control (OCX) that makes these scripts possible and how to customize the scripts.

The Scripts' Requirements
To use SendMagicPacket.vbs and Send-MagicPacketWithEvents.vbs, you must meet three requirements. These requirements involve the PC's hardware and software and the NIC's state.

The PC's hardware must support Wake on LAN. The hardware on the PC you want to wake up must support Wake on LAN, and that support must be enabled. Typically, you enable Wake on LAN support through the BIOS. The Web-exclusive sidebar "Wake on LAN Resources" on the Windows Scripting Solutions Web site (http://www.winscriptingsolutions.com) provides resources that you can use to learn about hardware support and configuration.

The PC's OS must support Wake on LAN. You must configure the target PC's Windows OS to support Wake on LAN, which means that you have to adjust the device permissions. In Windows XP, for example, you click Start, right-click My Computer, and select Properties to open the Control Panel System applet. In the applet, select the Hardware tab and click Device Manager to open the Microsoft Management Console (MMC) Device Manager snap-in. A shortcut is to type

%systemroot%system32devmgmt.msc

on the command line. After you open the Device Manager snap-in, right-click the appropriate network adapter, then select Properties. Finally, click the Advanced tab and enable Wake on LAN.

The wake-up method must be configured. Managing power in a NIC involves two states: standby or hibernate (the term depends on the Windows OS) and resume. These states are identical to a PC's sleep and wake states, respectively. Setting a NIC to the standby/hibernate state puts the card into a low-power state or, when a network isn't in use, to an off state. Setting a NIC to the resume state wakes up the card. User intervention or network traffic directed to the NIC from the network can prompt the NIC into the resume state. In the case of network traffic, the Network Device Class Power Management Reference Specification, which Microsoft and AMD created, details three default methods for creating events that can wake up a NIC: detection of a change in the network link state, receipt of a network wake-up frame, and receipt of a magic packet. (Manufacturers can also define and implement custom wake-up methods.) SendMagicPacket.vbs and SendMagicPacketWithEvents.vbs rely on the magic packet method.

When you install a NIC, the three default wake-up methods aren't configured for use. "Wake on LAN Resources" provides resources that you can access to learn how to configure a NIC.

A Welcomed Control
In the past, to create a magic packet, you had to write a script that automated the Winsock mswinsck.dll file. Microsoft licensed this version of Winsock from a third party, so you could install Winsock only as part of Microsoft Visual Studio (VS), for which you need a license. Thus, the DLL wasn't freely available. People who had access to this DLL wrote scripts to create magic packets. Listing 1 shows an example of such a script. If you find a script that looks like the one in Listing 1, however, don't use it. It's no longer a worthwhile solution because Ultrajones Software now offers a free OCX called UltraWOL (ultrawol.ocx). With UltraWOL, everyone—not just VS owners—can take advantage of magic packet technology.

To use UltraWOL, you need to install UltraWOL on the PC that will run the script and send the magic packet. You also need to install the Microsoft Visual Basic (VB) 6.0 runtime files on the same PC. "Wake on LAN Resources" includes links for downloading both UltraWOL and the VB 6.0 runtime files. I recommend that you download the VB 6.0 runtime files that have the most recent service pack. The runtime files in VB 6.0 Service Pack 5 (SP5) are

After you install UltraWOL, you can access its properties, methods, and events, which the Ultrajones Software Web site lists. However, when I use a new OCX, I'm always extra careful that I'm using it correctly. So, to explore the OCX's contents, I opened the Object Browser in Microsoft Word 2002 by selecting Tools, Macro, Visual Basic Editor, then pressing F2. (Previous versions of Word might not have F2 support. If pressing F2 doesn't work, you can open the Object Browser from the View menu.) UltraWOL wasn't in the list of available objects to browse, so I added a reference by selecting References on the Tools menu, clicking Browse, finding and highlighting ultrawol.ocx, then clicking Open. Figure 1 shows the References dialog box after I added the OCX reference.

With UltraWOL now in the list of available objects, I selected that object and explored its properties, methods, and events. As Figure 2 shows, the object has four properties (BroadcastAddr, LocalIP, MACAddr, and Version), one method (WakeUp), and two events (WOLComplete and WOLError). The Object Browser not only lists an object's properties, methods, and events but also tells you how to use them. Highlighting a property, method, or event prompts the Object Browser to display the syntax in the status bar at the bottom of the window, as Figure 2 shows.

Using the Scripts
Listing 2, page 12, contains SendMagicPacket.vbs, a modified version of one of the scripts that Ultrajones Software provides. This script creates an instance of the UltraWOL object, then uses the BroadcastAddr, MAC-Addr, and LocalIP properties to identify the target PC to wake up. Finally, the script uses the WakeUp method to send a magic packet to that target PC.

To use SendMagicPacket.vbs, you need to customize the lines that callout A in Listing 2 shows. You set the BroadcastAddr property to the broadcast address of the subnet that the target PC is on. Typically, the broadcast address is x.y.z.255, where x.y.z is the first three IP segments of the PC's IP address. You set the MACAddr property to your NIC's media access control (MAC) address. The MAC address must be in six hexadecimal segments separated by hyphens, as the second line at callout A shows. You can obtain the MAC address with the Windows OS tool msinfo.exe or msinfo32.exe, depending on the PC's OS. Some PCs have more than one NIC. For example, home PCs that connect to a cable modem and to a home network might have two NICs. When a PC has multiple cards, you need to target a specific card when you wake up the PC. To do so, you set the LocalIP property to the IP address of the NIC you want to target. If you don't have multiple NICs in the target PC, you need to remove or comment out the last line at callout A in Listing 2.

Listing 3 contains the script SendMagicPacketWithEvents.vbs, a modified version of another script that Ultrajones Software provides. Because it uses events, SendMagicPacketWithEvents.vbs is more advanced than SendMagicPacket.vbs. The two scripts start similarly, except for the code that callout A in Listing 3 shows. In this code, the WScript::CreateObject method has a new parameter: "objWOL_", the name of an event handler. An event handler is a subroutine that specifies the action to perform when a specified event occurs. In this case, the script looks for the WOLError and WOLComplete events. The objWOL_WOLError and objWOL_WOLComplete subroutines specify the actions to perform when the WOLError or WOLComplete event occurs, respectively. These subroutines appear at the end of the script.

If an error occurs during the script's execution, the event handler directs the script to the objWOL_WOLError subprocedure. The objWOL_WOL-Error subprocedure displays a message box that details the error. The script then quits.

When no error occurs during the script's execution, the event handler directs the script to the objWOL_WOLComplete subprocedure. The objWOL_WOLComplete subprocedure displays a message box that states the packet was sent. The message box also details the subnet broadcast address, NIC MAC address, and NIC IP address (if applicable) for the PC to which the packet was sent.

Note that the WOLComplete event confirms only the success of sending the packet. This event doesn't confirm that the target PC has responded to the packet. Also note that if you don't have multiple NICs in the target PC, you can remove or comment out the code that callout B in Listing 3 shows.

After you execute SendMagicPacket.vbs or SendMagicPacketWithEvents.vbs, the target PC needs time to resume from its state of suspension, so you need to wait about a minute before you try to connect to the target machine. I recommend that you first try the script on a PC in a test lab to see how the script works and to gauge the length of time it takes the PC to wake up.

Give the Scripts a Try
If you use NICs and have PCs that support Wake on LAN, have a go at using SendMagicPacket.vbs or SendMagicPacketWithEvents.vbs to wake up your sleeping PCs. In an upcoming article, I'll show you how to use SendMagicPacket.vbs and a few other scripts to schedule tasks. Task scheduling can make your life much simpler.