Creating Logon Scripts with KiXtart

If you've ever wanted to create one logon script for your network or distribute a Registry change to all workstations during client logon, you need to get acquainted with KiXtart. KiXtart is a freeware scripting language that Ruud van Velsen of Microsoft Benelux developed. KiXtart provides powerful scripting capabilities that you can use during client logons or in a standalone script. KiXtart goes far beyond the capabilities of batch files by including common functions that logon scripts typically perform.

For example, rather than calling and using the external Microsoft Windows NT Server 4.0 Resource Kit utility ifmember.exe, KiXtart includes an InGroup function that makes it easier to test for group membership. Using KiXtart is much easier than calling resource kit utilities from a batch file, because KiXtart provides almost everything you need in one scripting language.

Microsoft includes KiXtart with the resource kit. However, you can download the latest version, KiXtart 3.5, from http://netnet.net/~swilson/kix.html. The examples in this article use KiXtart 3.5.

KiXtart is easy to learn. In this article, I'll first explain what's in the KiXtart package that you download and what's included in the language's main components. Then I'll show you how to create, debug, and run scripts. From that point, you can explore KiXtart on your own. KiXtart 3.5 includes 94 pages of documentation and several sample scripts. For additional information, you can point your browser to the KiXtart discussion group in the General discussion board (http://www.extracheez.com/boards) or the Win32 Scripting page (http://cwashington.netreach.net).

The KiXtart Package
KiXtart consists of five files. They are

NT needs only one file to run KiXtart scripts: kix32.exe. For Win95, you must also install kx16.dll and kx32.dll. These two DLLs provide a thunking layer for Win95 clients. Thunking is the process of converting 16-bit API calls into 32-bit calls.

In a mixed NT and Win95 environment, you might also need to install kxrpc.exe and kx95.dll, depending on the macros you use. Kxrpc.exe implements an RPC service on the NT machine; Win95 clients use the kx95.dll to connect to this service. The RPC service provides information for some KiXtart macros. The KiXtart documentation lists the macros that require the RPC service. You install the RPC service only if you're using a macro that requires the RPC service. Otherwise, the RPC service generates unnecessary network traffic.

You can run KiXtart scripts from a local hard disk or from a network drive. If you run the scripts locally on a Win95 machine, you might consider placing the kx16.dll and kx32.dll into the C:Windows or C:WindowsSystem directory. In the case of logon scripts, you must locate all the needed files in the Netlogon share on all NT domain controllers. If you're using directory replication, the needed files are in the export directory of the export server.

Key KiXtart Components
The KiXtart scripting language uses three key components: commands, functions, and macros. KiXtart also uses syntax characters and basic operators. Kix95.doc, a documentation file included with KiXtart, lists all the commands, functions, macros, characters, and operators. KiXtart is a free-format language and is not case-sensitive. However, to help you differentiate between the three components, I'm using uppercase for commands, title case for functions, and lowercase for macros.

Commands. You use commands to perform actions such as clearing the screen, setting text color, changing text size, and mapping drives. For example, the USE command lets you connect to or disconnect from a network resource. You can add conditional statements to your script with the IF ELSE ENDIF command or the SELECT CASE...ENDSELECT command. (KiXtart supports nested IF ELSE ENDIF statements.) To control the flow of execution, you can use the WHILE-LOOP command or the DO UNTIL command. In addition, you can use GOSUB and GOTO commands to jump to subroutines, the RUN command to run external programs, and the CALL command to start a separate KiXtart script.

Functions. Functions go beyond the capabilities of commands and usually require one or more string expressions as parameters. (You can put strings in either double quotation marks or single quotation marks.) Most functions return a string or numeric value and set the value of @error to signify problems that prevent successful completion of the script. Here are a few of the many tasks you can perform with KiXtart functions:

You can also use KiXtart's AddKey or DelKey functions to add or delete Registry keys. However, you must be extremely careful when working with either of these two functions, because you can accidentally overwrite keys. When a KiXtart script runs as a user's logon script, it runs under the context of the user and has access only to the HKEY_CURRENT_USER portion of the Registry on NT machines. You must have administrator rights to modify the HKEY_LOCAL_MACHINE portion of an NT Registry. Thus, you might want to use the System Policy Editor (SPE) instead. SPE runs under the SYSTEM context to distribute HKEY_LOCAL_MACHINE Registry changes during client logon. For Win95, a user's logon script has access to any portion of the Registry.

Macros. You use macros to provide information, such as a machine's network card address, a user's logon server, and a user's password age. Table 1 contains some commonly used macros, including userid. This handy macro provides the current user's NT user ID

In Win95, some macros require the use of the KiXtart RPC service. The KiXtart RPC service must run on an NT machine, and the Win95 machine must have the kx95.dll file. (For more details about the KiXtart RPC service, see the KiXtart documentation.)

Syntax characters and operators. KiXtart uses several syntax characters, including the $ character (which signifies a variable), the @ character (which specifies a macro), and the % character (which denotes an environment string). KiXtart uses environment strings to obtain the value of environment variables. You can see the environment variables on your system by typing SET at a command prompt. To use these characters in a string, you must use @@, %%, or $$.

KiXtart supports the AND and OR logical operators. KiXtart also supports these conditional operators: < (less than), <= (less than or equal to), > (greater than), >= (greater than or equal to), = (equal to), and <> (not equal to).

Creating and Debugging a Logon Script
Batch files are too limited to accomplish such tasks as testing a user's group membership, connecting a user to a specific printer, and changing a user's Registry setting during logon. You can, however, use a KiXtart logon script for these tasks.

For example, suppose a company's accounting department uses server ATLS005 and its engineering department uses server ATLS006, and you want to use a KiXtart logon script to map the H drive to a user's home directory on the proper server. Listing 1 gives an example of the code you can use to complete this task. (You can download all the listings in this article from http://www.winntmag.com/newsletter/scripting.) To begin this script, you use the InGroup function with the IF ELSE ENDIF command to test whether the user is a member of the accounting or engineering department. If the user is an accounting group member, you set the variable server ($server) to the string ATLS005; if the user is an engineering group member, you set $server to the string ATLS006. You then apply the USE command with $server and the @userid macro to map the H drive to the user's home directory.

After you create a logon script, you need to debug it. In KiXtart 3.5, kix32.exe supports the /d command-line switch, which runs the script debug mode. (Previous versions don't support this switch. KiXtart 3.5 also supports the /n command-line switch, which prevents KiXtart from retrieving user information from a logon server and thus results in faster processing.) The debug mode shows each line of the script in a blue header at the top of the command window. You can use the F8 or Enter key to move through the script. Table 2 lists other keys that you might need to navigate through the script in the debug mode. You can also type in variable names at any point to see their value.

Running a Logon Script
After you create your KiXtart logon script, you can run it manually or automatically. To run a KiXtart script manually, you open a command window and type

kix32.exe script name

where script name is the name of the script you want to run. The script file can have any extension; .kix and .scr are the default extensions. You can also manually run a script within NT Explorer by dragging the script file on to kix32.exe.

To automatically run KiXtart logon scripts, you need to copy kix32.exe to the Netlogon share on all domain controllers (%systemroot%system32replimportscripts). If you're using directory replication, you can simply copy kix32.exe to the export directory of the export server. If you have Win95 clients, you must also copy kx16.dll and kx32.dll to the Netlogon share.

After you have the proper files in place, you assign the logon script to the users' accounts. In an NT environment, you can have kix32.exe start automatically when the user logs on. Follow these four steps:

This four-step process doesn't work on Win95 clients. For Win95 users, you must call and run kix32.exe from a batch file that serves as the user's logon script. If you don't designate a specific logon script for a particular user (e.g., marysmith.kix), kix32.exe looks for a script named kixtart.kix by default. Most networks with a mixture of NT and Win95 clients use one logon script named kixtart.kix. In such a mixed network, you specify KIX32 in the Logon Script Name text box, as Screen 1 shows.

A More Complex Script
Now that you know how to create, debug, and run a basic KiXtart logon script, you're ready to create a more elaborate script, such as the logon script in Listing 2. You can easily modify Listing 2 for your organization.

You start the logon script with the CLS command, which clears the screen of any color and moves the cursor to the neutral position of row 0, column 0 (0,0). You then use the COLOR command to set the foreground and background color of the screen. The command's syntax is COLOR x/y, where x is the foreground color (i.e., the color of the text) and y is the background color. A plus sign (+) after the foreground color specifies that you want a bright color. A plus sign (+) after the background color specifies that you want that color to blink. You can choose from many colors, including black (value of normal, or n), blue (b), green (g), and white (w). So, for example, the COLOR b+/n command in Listing 2 specifies that you want the screen to have bright blue text on a black background.

After you set the color, you use the Box function to paint a grid background. The first four values represent the coordinates of the box's four corners. The first value represents the top left row, the second value represents the top left column, the third value represents the bottom right row, and the fourth value represents the bottom right column. The fifth value specifies the line style. You can choose from single, double, full, or grid.

The subsequent three lines in Listing 2 further change the screen's appearance. In the midst of a black background, the color of the text first changes to a bright green, then a box appears in the center of the screen, and finally the color of the text changes to a bright white.

The next section of the script uses nested IF ELSE ENDIF commands to check the time and select an appropriate greeting for the user. You use the @time macro, which uses military time, and the logical AND operator. For example, the segment highlighted at callout A of Listing 2 specifies that if the time is after midnight and before noon, the screen displays the greeting Good Morning. The At function specifies where the greeting starts on the screen. In this case, the greeting starts at row 9, column 20.

After the greeting, you use the At function and the @fullname macro to display the user's full name (i.e., the name that the user's NT account properties specify) on the screen. Two rows down on the screen, you use the At function to display the message Please Wait For Logon Script Execution.

At this point, you need to synchronize the workstation's time with that of a server named ATLS001. If the user logs on from ATLS001, there is no need to set the time. To test for logon to ATLS001, you use an IF ELSE ENDIF command with the @wksta macro. The @wksta macro returns the name of the computer used for interactive logon. If the user logs on from any computer other than ATLS001, the SETTIME command synchronizes the workstation's time with ATLS001.

After setting the time, you use the SELECT CASE...ENDSELECT command with the InGroup function to determine the user's group membership and assign the correct server to the $homeserver variable. SELECT CASE...ENDSELECT is similar to IF ELSE ENDIF. However, SELECT CASE...ENDSELECT lets you test multiple cases without having to nest statements as you would with IF ELSE ENDIF. In this case, you use the SELECT CASE...ENDSELECT command because it lets you easily extend the statement to include many groups.

Next, you issue the USE "*" /del command to delete persistent drive mappings the user might have during logon. Without this command, you might encounter a situation in which a user has a persistent connection to a drive and your USE command in KiXtart doesn't work because the drive letter is already in use. As you did in Listing 1, you apply the USE command to map the P and H drives. The @error macro captures any error codes that occur during the attempt to map the drives. The system stores any error code returned by @error in the $mapHerror and $mapPerror variables.

After you map the drives, you test the $mapHerror and $mapPerror variables. If either variable equals a nonzero value, an error has occurred. (The KiXtart documentation has a complete list of error codes.) If an error occurs, you use the SendMessage function to send a message to a user named "admin". You use the @userid and @time macros to report the user who encounters the drive map failure and the time of the failure.

If the $ReturnCode variable has a value of zero, you've sent the message correctly. After notifying the administrator, you present a message box to the user with the MessageBox function. Screen 2 shows an example of a message box that the user might receive.

Finally, you apply the At function to display the message Press any key to continue. You use the GET command with the variable x ($x) to detect when the user presses a key. The script then exits.

Beyond the Examples
The KiXtart utility can accomplish almost any task you can imagine. Although the examples here focus on logon scripts, you can also use KiXtart to develop standalone scripts. I have used KiXtart to perform such tasks as disabling the Win95 browser service, consolidating machines into one workgroup, and generating an HTML report that detailed various client settings. I encourage you to explore the KiXtart documentation and think of potential uses for each command.