Scripting SMS: Making a Connection

• The COM API for WMI. Unless you have an uncontrollable desire to write code in C++, this API is not for you. The COM API is required for certain WMI operations (like writing your own WMI provider, event providers, etc.), but you are not interested in those -- you just want to manipulate SMS, which does not require any of this stuff.
• The Scripting API for WMI. Usable from just about any development tool or language, the scripting API offers nearly all the functionality of the COM API. This is the one you want.

If you choose the COM API, you're on your own. The remainder of this (and probably every other) article will focus on the Scripting API.

So which parts of this API will you need to know? At this point, since we are only talking about connecting to SMS, we need to be concerned with only two object classes:

• SWbemLocator, the object used to make the connection to WMI - in our case, to the SMS WMI provider.
• SWbemServices, the object returned by the SWbemLocator object after successfully connecting to the WMI provider. This is then used to talk to SMS.

Sound relatively simple? It is. While the documentation for these two object classes might look a bit intimidating, you need to realize that one method, ConnectServer, is all that is required at this point. (More of the SWbemServices methods will be used later.)

Since the WMI Scripting API is designed to be used from multiple tools or languages, which should you use? Well, here are some of the (reasonable) choices:

• Visual Basic. A good language, a great development environment. The context-sensitive editor and debugger are indispensible.
• VBScript. A reasonable second choice: a stripped-down version of the same good language, with no development environment needed or provided. Great for quick-and-dirty scripts.
• Visual Basic for Applications. Embedded in many software products, such as Microsoft Excel or Visio, this is basically VBScript with added application-specific features.

What about some of the other choices, such as JavaScript, Java, COBOL, FORTRAN, PL/1, LISP, Perl, etc.? You are on your own there - my preference is to use Microsoft technologies to work with Microsoft technologies.

What about C++? If you are determined to use it, go ahead - I won't stop you. But don't try to convince me that this makes you a real programmer, no matter how many Twinkies you consume in the process.

So which of the "reasonable" choices above should we use? My choice: all of them. Each article will focus primarily on stand-alone VBScripts, but will also provide Visual Basic, Microsoft Excel, and Active Server Page examples. Obviously to make use of the Visual Basic examples, you'll need a copy of Visual Basic, and to use the Excel examples you'll need Excel.

What about the VBScript examples? All you really need is Notepad, but there are other tools that could be valuable. Two types of tools are particularly useful: context-sensitive editors, and debuggers. Some of the editor choices include:

• Visual InterDev. Works great for Active Server Pages, but for every-day VBScripts it does not do quite as well (although it does work). See Q249024 for more information.
• Microsoft Script Editor (MSE.EXE). Installed as part of Office 2000, this editor can be tricked into editing VBScript files as well. See Gunter Born's Windows Script Host Bazaar web page or "Microsoft Windows Script Host 2.0 Developer's Guide" book (a good WSH how-to book) for more information.
• PrimalScript. A good commercial script editor, available from Sapien Technologies.

Having a good editor is always useful, but when working out the kinks a good debugger is essential. Some possibilities:

• Microsoft Script Debugger. Included with Windows 2000 or downloadable, the Microsoft Script Debugger isn't fancy, but it gets the job done.
• Visual InterDev. This works really well for debugging VBScripts - my tool of choice.

There are two easy ways to make use of a debugger, once it is installed: either include a "stop" statement in the VBScript code, or run the script using the "//x" (always debug) or "//d" (debug if any errors occur)parameters. (See the Windows Script documentation. Trying to debug WSF files on Windows 2000 and can't? See Q252895 for more information.)

After all of that, this will be the anti-climax. All you need to do to connect to SMS are the following statements:

' Create the object to make the WMI connection
Set locator = CreateObject("WbemScripting.SWbemLocator")

' Connect to server SERVER hosting SMS site XXX
Set sms = locator.ConnectServer("SERVER", "root\sms\site_XXX")

' Perform whatever you want here

' Disconnect and clean up
Set sms = Nothing
Set locator = Nothing

Save that chunk of code (substituting the proper values for SERVER and XXX) into a VBS file, and you're set to go. With some error handling thrown in, this is actually useful code: it verifies that the SMS provider is functioning, a good quick check of the health of your SMS server.  (If you can't connect, something is wrong.)

Believe it or not, there is actually an easier way using the "GetObject" function:

' Connect to server SERVER host SMS site XXX
Set sms = GetObject("winmgmts://SERVER/root/sms/site_XXX")

' Perform whatever you want here

' Disconnect and clean up
Set sms = Nothing

While this does the exact same thing, I normally use the first method, as it is a bit more obvious what it is doing. The second method is documented (kind of) in the Platform SDK, so feel free to explore this more on your own.

Next time, we'll take this a little further by developing a function to encapsulate this simple code, with some additional features, then "transform" this code into Visual Basic, Active Server Pages, and Microsoft Excel templates. In the process, we'll write our first query (which will explain why the SMS Administrator only asks for a server name and not a site code).

Until then, be sure to send me e-mail with any comments or suggestions you may have, and rate this article below. These serve as motivation for the creation of more articles...

Also, if you haven't already checked out the introduction article, be sure to read that one as well.