Networking Resources

Networked environments play an important role in today's corporate computer systems. WSH provides the ability to programmatically manipulate network resources. This functionality allows for operations to be performed that would be impossible using the old command-line programs, such as net use.

These operations are exposed through the WScript.Network object. This object provides methods that can perform network-related functions, such as network share and printer connection, and they can also query network-related information, such as user name and computer name.

Identifying a User

Problem

You want to find out who is currently logged on the local computer.

Solution

You can create an instance of the WScript.Network object and reference the UserName property:

'create an instance of the Wscript.Network object Set objNetwork = CreateObject("Wscript.Network") 'output user name Wscript.Echo "You are logged on as "& objNetwork.UserName

Discussion

The WScript.Network object exposes a number of properties that can be used to determine the computer, user, and domain information for the local computer. Table 4-1 lists Network object properties.

On the Windows 9x/ME platforms you may encounter problems referencing the UserName property in logon scripts. The problem is that the user ID doesn't get assigned immediately during the logon process.

To ensure the user name of the logged-on user is returned correctly in these instances, create a loop that continuously assigns the UserName property to a variable until it returns a valid user ID, as demonstrated in the following code snippet:

'create an instance of the Wscript.Network object Dim objNetwork, strName Set objNetwork = CreateObject("Wscript.Network") On Error Resume Next 'loop until a user ID is assigned While strName = "" strName = objNetwork.UserName Wscript.Sleep 100 WEnd

Finding an Available Network Drive

Problem

You want to find the next available network drive.

Solution

You can use the Scripting File System Object's DriveExists method to determine if a drive exists. The following function returns the next available drive:

'ReturnNextDrive.vbs Function ReturnNextDrive() Dim nF, objFSO Set objFSO = CreateObject("Scripting.FileSystemObject") 'loop through drives starting from D: For nF = ASC("d") To ASC("z") 'if drive doesn't exist, it's available If Not objFSO.DriveExists(Chr(nF) & ":") Then ReturnNextDrive = Chr(nF) & ":" Exit Function End If Next End Function

Discussion

The ReturnNextDrive function listed in the Solution script returns the next available drive letter. If all drives are connected, it returns a Empty variant. It assumes the first potentially available drive starts at the D: drive.

The function uses the FSO library to determine if the drives exist. See Chapter 5 for more information on FSO-related operations.

The WScript.Network object's EnumNetworkDrives property returns a collection of connected network drives. The collection returned is a WSH collection, which operates in a slightly different manner than other object collections. The collection is represented as an array with items starting at 0 offset. For each connected drive, the array contains an element for the drive letter and an element for the share name. If you have two connected network drive shares (H: and P:), the collection array would contain four elements: the first element contains the H: drive, the second element contains the share H: is connected to in UNC format, the third element contains the P: drive, and the fourth element contains the share P: is connected to.

Use the EnumNetworkDrives property's Count property to determine the number of elements in the collection. The number represents double the number of connected shares.

The following code snippet demonstrates how to list details on the first share as well as listing details on all connected shares:

'listshares.vbs 'lists connected network shares Dim objNetwork, objShares, nf Set objNetwork = CreateObject("Wscript.Network") Set objShares = objNetwork.EnumNetworkDrives 'output the first connected share and associated drive letter Wscript.Echo "Drive " & objShares(0) & " is connected to " & objShares(1) 'loop through all connected shares and output details For nf = 0 To objShares.Count - 1 Step 2 Wscript.Echo objShares(nf) & " is connected to " & objShares(nf + 1) Next

Mapping Network Drives

Problem

You need to connect clients to their home directory on a server and then to an applications and public data area when they log on.

Solution

You can use the WScript.Network object's MapNetworkDrive method to connect drives to network shares. Add the following code to their logon scripts:

'logon.vbs Dim objNetwork, strName Set objNetwork = CreateObject("Wscript.Network") On Error Resume Next 'get user name While strName = "" strName = objNetwork.UserName Wscript.Sleep 100 WEnd 'map user to home drive objNetwork.MapNetworkDrive "H:", "\THOR" & strName & "$", True 'connect to public area objNetwork.MapNetworkDrive "P:", "\THORPublicArea", True 'connect to apps share objNetwork.MapNetworkDrive "W:", "\THORApps", True

Discussion

The MapNetworkDrive method connects a drive to a network share. The syntax for this method is as follows:

objectNetwork.MapNetworkDrive strDrive, strShare, [bUpdateProfile], [strUserID], [strPassword]

Table 4-2 lists the parameters for the MapNetworkDrive method.

An error will occur if you try to connect to a drive that is already connected to a share or if the specified share does not exist. Use the On Error Resume Next statement to trap any errors when connecting to network resources.

If you want to connect a share to a drive letter that is already connected to another share, you must first remove the existing connection using the WScript.Network object's RemoveNetworkDrive method. The syntax for the method is as follows:

objNetwork.RemoveNetworkDrive strDrive, [bForce], [bUpdateProfile]

Table 4-3 lists the parameters for the RemoveNetworkDrive method.

The following (forcefully) removes the T: drive connection and updates the user's profile so the removal is remembered at the next logon:

objNetwork.RemoveNetworkDrive "T:", True, True

For user home directories, there is no comparable command like the command-line net use /h, which maps a user to his or her home directory defined under the NT User Manager. This is not as much a problem with Windows NT/2000/XP workstations and servers that map these drives automatically, but Windows 9x and ME clients don't.

Using the Network object's Username property to return the name of the current user can solve this problem. You can use this name to connect to the home directory. This assumes that you follow a naming convention that uses the user name in the naming of the network shares. This is a common naming convention for home shares.

Set objNetwork = CreateObject("Wscript.Network") objNetwork.MapNetworkDrive "H:", _ "\odin" & objNetwork.UserName & "$" , True

The last parameter in the MapNetworkDrive method is an optional Boolean value that determines if the user's profile is to be updated or not. It is important to set this to True so the connection is remembered the next time the user logs on.

Migrating File Services from One Server to Another Server

Problem

You have migrated file services from one NT server (ODIN) to a new server (THOR). ODIN contained all user home directories, as well as a number of application file shares and miscellaneous shares that were created for users. Because ODIN will remain in place performing other operations, all of the existing shares must be remapped from ODIN to THOR.

The standard network connections, such as home drives, will connect to THOR in the logon script, but there is no set standard as to where users may map other drives. Some users may have any combination of mapped drives to the old server. To minimize support calls, you want to automatically remap any drives from ODIN to THOR.

Solution

The following code is run during the logon script for each client. The THOR server is the new file server, while the ODIN server is the old server.

'migrate.vbs Dim objWshNetwork, nF Dim sShare, sDrive, objEnumNetwork Set objWshNetwork = CreateObject("WScript.Network") Set objEnumNetwork = objWshNetwork.EnumNetworkDrives For nF = 0 To objEnumNetwork.Count - 1 Step 2 'get the drive letter and share name for the current share sShare = objEnumNetwork(nF) sDrive = objEnumNetwork(nF + 1) 'check if the current share is connected to ODIN. If StrComp(Left(sShare, 7), "\ODIN", vbTextCompare) = 0 Then 'remove the existing share objWshNetwork.RemoveNetworkDrive sDrive, True, True 'remap the drive to the new server objWshNetwork.MapNetworkDrive sDrive, _ "\THOR" & Mid(sShare, 8), True End If Next

Discussion

In order for this to work, the shares on ODIN must not actually be deleted until the migration is complete. The contents of the shares should be moved to THOR, but the shares themselves shouldn't be removed until all the users have logged on and have been connected to the new server.

You can enumerate the collection using a For Each statement, but it is more practical to access the collection as an array.

The collection/array starts at element 0:

'display the drive letter of the first connection Wscript.Echo objWshNetwork.EnumNetworkDrives.Item(0) 'display the share name of the first connection Wscript.Echo objWshNetwork.EnumNetworkDrives.Item(1)

When a drive is disconnected, the EnumNetworkDrives collection is automatically resized to reflect the change. Two items are removed from the collection: the local drive letter and the corresponding share.

So, if you have three network connections and you remove the second connection, the collection is resized and the third connection becomes the second connection.

If you assign the EnumNetworkDrives collection to a variable, the variable makes a copy of the collection. If a drive is added or disconnected, the variable, which is a copy of the collection, is not updated. In the following example, an EnumNetworkDrives collection is assigned to a variable before a drive is connected to a share:

Dim objEnumNetwork, objNetwork Set objNetwork = CreateObject("WScript.Network") Set objEnumNetwork = objNetwork.EnumNetworkDrives 'display the count of items in collection WScript.Echo objEnumNetwork.Count 'connect to share objNetwork.MapNetworkDrive "T:", "\odindata" 'display count of WScript.Echo objEnumNetwork.Count WScript.Echo objNetwork.EnumNetworkDrives.Count

After the share is connected, the count of items in the EnumNetworkDrives collection and the variable is displayed. The count will be different because the EnumNetworkDrives collection is bigger as a result of connecting to the new drive.

When the remote share is disconnected, the user's profile must be updated. This ensures that when the drive is reconnected at the next logon time, the user's profile will have reflected the change. Note that the second parameter, forceful disconnect, is set to guarantee that the network connection is disconnected:

objNetwork.RemoveNetworkDrive sDrive, True, True

The same applies when you want to add the new share. You must set the update profile flag to True to ensure the share is reconnected at the next logon.

Connecting to a Network Printer

Problem

You want to connect to a networked printer.

Solution

You can use the WScript.Network object's AddWindowsPrinterConnection method to connect to a networked Windows printer:

Dim objNetwork Set objNetwork = CreateObject("WScript.Network") objNetwork.AddWindowsPrinterConnection "\odinBrother HL-730"

Discussion

The AddWindowsPrinterConnection method adds a networked printer to the local machine and was introduced in WSH 2.0. The syntax for the method is as follows:

objNetwork.AddWindowsPrinterConnectionstrPrinterPath, [strDriverName] [,strPort]

Table 4-4 lists the parameters for the AddWindowsPrinterConnection method.

Using this method is the same as using the Control Panel Printers applet to add a printer connection. In Windows 95/98/ME, the printer driver must already be installed on the machine in order for the AddWindowsPrinterConnection method to work, which reduces the usefulness of this method on these platforms. Windows NT/2000/XP will download the driver if the driver is not installed on the local computer the printer is being installed on. An error will occur if the driver does not successfully install.

Once you have added a printer, you may want to make it, or an existing printer, the default printer for your Windows applications. A default printer is automatically selected when you attempt to print from a Windows application. The syntax for the method is as follows:

objNetwork.SetDefaultPrinter(strPrinterPath)

The strPrinterPath parameter specifies the UNC path of the printer you want to make the default printer. The printer must be installed as a Windows printer appearing under the Control Panel Printer applet. The following code snippet sets the default printer to the network printer \odinrother:

Dim objNetwork Set objNetwork = CreateObject("WScript.Network") objNetwork.SetDefaultPrinter "\odinrother"

WSH has supported the addition of printers since the initial release using the AddPrinterConnection method. This method is useful only if you need to connect to printers from the command-line environment; the method is the equivalent of using the net use command. Printers that are connected using this method are not available from Windows applications.

The syntax for this method is as follows:

objNetwork. AddPrinterConnection strPort, strPrinterPath,[bUpdateProfile], [strUser], [strPassword]

Table 4-5 lists the parameters for the AddPrinterConnection method.

The following code snippet connects the LPT2 port to the remote printer laserjet on computer Odin:

Set objNetwork = CreateObject("Wscript.Network") objNetwork.AddPrinterConnection "LPT2", "\odinlaserjet"

Listing Connected Network Printers

Problem

You want to list all the connected networked printers.

Solution

You can use the WScript.Network object's EnumPrinterConnections property to loop through connected printers:

'lstprinters.vbs Set objNetwork = CreateObject("Wscript.Network") Set objPrinters = objNetwork.EnumPrinterConnections 'loop through and display all connected printers.. For nF = 0 To objPrinters.Count - 1 Step 2 Wscript.Echo objPrinters(nF) & _ " is connected to " & objPrinters(nF + 1) objNetwork.RemovePrinterConnection objPrinters(nF + 1) Next Set objNetwork = Nothing

Discussion

The EnumPrinterConnections method returns a special WSH collection, which is similar to the collection that is returned by the EnumNetworkDrives property (as described in Solution 4.2). The collection is represented as an array.

Each connected printer stores two elements to the array: the first being the printer port and the second being the UNC path to the printer. The collection returns twice as many elements as there are connected printers.

The number of elements in the collection can be determined by the EnumPrinterConnections collection's Count property. This returns the double the number of actual connected printers, so to determine the number of connected printers, divide this value by two.

The EnumPrinterConnections collection returns Windows as well as MS-DOS connected network printers, such as those added using net use on the command prompt or the WScript.Network object's AddPrinterConnection method.

Disconnecting Network Printers

Problem

You want to disconnect a networked printer.

Solution

You can use the WScript.Network object's RemovePrinterConnection method to remove a connection to a shared network printer:

Set objNetwork = CreateObject("Wscript.Network") objNetwork. RemovePrinterConnection "LPT1:", True

Discussion

The RemovePrinterConnection method disconnects connected network printers. The syntax for the method is as follows:

objNetwork.RemovePrinterConnection strPort, [bForceDisconnect], [bUpdateProfile]

Parameters for the RemovePrinterConnection method are listed in Table 4-6.

Prior to WSH version 5.6, the RemovePrinterConnection method could only remove MS-DOS networked printers added using net use from a command prompt or the WScript.Network object's AddPrinterConnection method. This is fixed in WSH 5.6, so any networked printer can be removed.