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.

Table 4-1: Network Object Properties

PROPERTY	DESCRIPTION
ComputerName	Name of the local computer.
UserName	Name of the user logged into the local computer.
UserDomain	Name of the domain the user is currently logged into. Returns the computer name if it is not a member of the domain.

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.

Table 4-2: MapNetworkDrive Parameters

PARAMETER	DESCRIPTION
strDrive	Local drive letter to map the network share to.
strShare	Name of share in UNC format (e.g., \serversharename).
bUpdateProfile	Optional Boolean parameter that indicates if drive connection is remembered for next session.
strUserID	Optional user ID to use when connecting to network share.
strPassword	Optional password specified to use when connecting to network share. This is used together with the strUserID parameter.

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.

Table 4-3: RemoveNetworkDrive Parameters

PARAMETER	DESCRIPTION
strDrive	Local drive letter to remove
bForce	Optional Boolean parameter that if True will attempt to forcefully disconnect share, even if resources are in use on the share
bUpdateProfile	Optional Boolean parameter that indicates if drive removal is remembered for next session

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.

Table 4-4: AddWindowsPrinterConnection Parameters

PARAMETER	DESCRIPTION
strPrinterPath	Path to the printer in UNC format (e.g., \serverprintername).
strDriverName	Name of the driver to use. Required on Windows 95/98/ME; ignored if used on Windows NT/2000 or XP platform.
strPort	Optional. Specifies the port to attach the printer to on Windows 95/98/ME. Default is LPT1. Ignored if used on Windows NT/2000 or XP platform.

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.

Table 4-5: AddPrinterConnection Parameters

PARAMETER	DESCRIPTION
strPrinterPort	The local printer port to connect the network printer to (e.g., LTP1:).
strPrinterPath	Path to the printer in UNC format (e.g., \serverprintername).
bUpdateProfile	Optional Boolean parameter that determines if printer connection is stored in user profile and reconnected in future sessions.
strUserID	Optional user ID for connecting to remote printer with.
strPassword	Optional password for connecting to remote printer. This is used in combination with the strUserID parameter.

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.

Table 4-6: RemovePrinterConnection Parameters

PARAMETER	DESCRIPTION
strPort	Local printer port for the printer to remove
strForce	Optional Boolean parameter that if True will attempt to forcefully disconnect the shared printer, even if the printer is in use
bUpdateProfile	Optional Boolean parameter that indicates if printer share removal is remembered for next session

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.