Windows Server 2008 and Windows Vista : Using .adm Template Language (part 2) - Syntax for Updating the Registry

2. #if version

Instead of creating an .adm template for each set of operating system settings, you can use the #if version syntax within one .adm template to break up the settings. The #if version syntax breaks up the .adm template into zones, with each zone targeting a specific operating system range. The standard .adm templates use this method to create these zones, providing settings for older operating systems and newer operating systems in a single .adm template.

Each operating system matches up with a specific version number within the .adm template. The following chart specifies each operating system and the .adm template #if syntax version number associated with it.

Operating System	Version	Type
Microsoft Windows Server 2003 Service Pack 1 (SP1)	5.0	Group Policy
Windows XP SP2	5.0	Group Policy
Windows Server 2003 and Windows XP	4.0	Group Policy
Windows Server 2000	3.0	Group Policy
Microsoft Windows NT 3.x and 4.x	2.0	System Policy
Windows 95	1.0	System Policy

In some instances, the #if version syntax can be omitted and the .adm code can span multiple operating system generations. This is possible when the registry value and the location of the setting is the same for the different operating systems.

You can control the #if version syntax by adding operators to control ranges of operating systems that the .adm syntax should affect. Here are the operators that can be used with the #if version syntax.

>	Greater than
<	Less than
==	Equal to
!=	Not equal to
>=	Greater than or equal to
<=	Less than or equal to

3. Syntax for Updating the Registry

You know that the .adm template generates the interface for the GPME and specifies the registry path, value, and data. Specific syntax is used within the .adm template to handle all of these variables.

The syntax that builds the GPME interface is essential within the .adm template. If any syntax for one of these components is missing, the file will fail to load properly. The syntax used to build the registry path, value, and data includes CLASS, KEYNAME, VALUENAME, VALUEOFF/VALUEON, and PART.

CLASS

There are two CLASS options: MACHINE and USER. The CLASS syntax specifies two things within the .adm template. First it indicates which portion of the registry will be modified. If the MACHINE option is specified, the GPO will modify the HKEY_LOCAL_MACHINE handle in the registry. If the USER option is specified, the GPO will modify the HKEY_CURRENT_USER handle in the registry.

Note

The registry contains only two primary handles: HKEY_LOCAL_MACHINE and HKEY_USERS. The other three handles are subsets of these two primary handles. The HKEY_CURRENT_USER handle is a subset of the HKEY_USERS handle. The HKEY_CURRENT_USER handle is the current user’s profile that is placed in the registry when the user logs on.

You need to use the CLASS syntax only once for each of the MACHINE and USER options. All of the registry settings that fall under the HKEY_LOCAL_MACHINE handle will be grouped together, after you list the CLASS MACHINE syntax. The same is true for the registry settings that fall under the HKEY_CURRENT_USER handle and the CLASS USER syntax.

Note

If an .adm template contains multiple CLASS MACHINE or CLASS USER sections, they will be merged together when the GPME interface is created.

If the .adm template you are creating will refer to only one of the registry handles, you list only that CLASS syntax in the .adm template.

The CLASS syntax also places the interface changes under Computer Configuration\classic administrative templates\ or User Configuration\classic administrative templates\, based on MACHINE or USER, respectively. When the GPME accesses the .adm template, it places the interface settings under the proper node.

Note

There is no END CLASS statement associated with the CLASS syntax.

KEYNAME

The KEYNAME syntax is not optional within the .adm template. KEYNAME specifies the path from the HKEY to the registry value. KEYNAME comes after the CATEGORY syntax and either before or after the POLICY syntax, depending on how you choose to structure the .adm template. However, KEYNAME must come after the CLASS syntax and before the PART or VALUENAME syntax.

Note

If you want to group multiple policy settings that reside under the same path in the registry, you can place the KEYNAME entry after the CATEGORY syntax. This results in a grouping of all the entries following the CATEGORY syntax under the same folder in the GPME.

The KEYNAME syntax indicates the path to the registry value. Do not include HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER in the registry path—this is handled by the CLASS syntax. You also do not need to use an introductory slash (/) to start the path within the KEYNAME text. For our example, the KEYNAME entry is as follows:

KEYNAME SOFTWARE\Microsoft\WindowsNT\CurrentVersion\Winlogon

If a space follows the KEYNAME syntax within the path, you must put quotation marks (“) around the entire path string, but do not include the KEYNAME word in the quotes. Here is an example of an entry that requires quotes:

KEYNAME "SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon"

Note

There is no END KEYNAME statement associated with the KEYNAME syntax.

VALUENAME

VALUENAME references the registry value that will be updated. You must find the approved registry value name—you are not allowed to make up registry values. If the computer registry is updated with an incorrect registry value, the computer might experience a stop error. Values in the registry are typically cryptic words that are not found in a dictionary.

You can use two methods to modify the values specified with the VALUENAME syntax. These methods are controlled by the values that the registry can handle.

• Many registry values support only two numeric values: 0 and 1. If the numeric value is 0, the registry value is off. If the numeric value is 1, the registry value is on. When the registry value is controlled in this fashion, you use the VALUEOFF/VALUEON syntax.

• The other registry values require text or more than just 0 or 1 numeric values. These registry values are controlled using the PART syntax.

When you use the VALUEOFF/VALUEON syntax, you are directly affecting the behavior of the registry value. When you use the PART syntax, you are modifying the GPME, which allows for a more complex entry to be set for the registry value.

Note

There is no END VALUENAME statement associated with the VALUENAME syntax.

VALUEOFF/VALUEON

The VALUEOFF/VALUEON syntax works like a switch. The registry value is either off or on, reflecting the simple use of binary values of 0s and 1s. When you look at many of the registry entries in the Registry Editor, you will see that they actually support the string data type, which is denoted at REG_SZ. This does not alter the behavior or the limited values that the registry value supports.

Here is an example of a standard .adm entry that uses VALUEON and VALUEOFF.

KEYNAME "Software\Microsoft\Windows\CurrentVersion\Policies\System"
VALUENAME "HideStartupScripts"
VALUEON NUMERIC 0
VALUEOFF NUMERIC 1

For this .adm entry, no input is required after you edit the setting in the GPME. You have only the ability to enable or disable the policy to toggle between the VALUEOFF and VALUEON numeric values. The GPME shows this policy with the standard interface, as shown in Figure 1.

Figure 1. The GPME shows when a registry value is determined by the VALUEON/VALUEOFF syntax in the .adm template.

The policy setting includes the following three settings options:

• Not Configured Does not set any entry for the registry value; instead, it leaves the registry value as it is set on the computer.

• Enabled Sets the registry value to the VALUEON specified numeric value.

• Disabled Sets the registry value to the VALUEOFF specified numeric value.

You can use a second method that is indirectly associated with the VALUEOFF/VALUEON syntax, and that you use when you do not explicitly use the VALUEOFF and VALUEON statements. Here is an example of what that might look like:

POLICY!!EnableSlowLinkDetect
   EXPLAIN !!EnableSlowLinkDetect_Help
   KEYNAME "Software\Policies\Microsoft\Windows\System"
   VALUENAME "SlowLinkDetectEnabled"
END POLICY

Notice that there is no explicit use of VALUEON/VALUEOFF, but the behavior is similar. In this example, the three settings of the GPO policy behave in the following manner:

• Not Configured Changes nothing in the registry.

• Enabled Sets the registry value to a numeric value of 1.

• Disabled Deletes the registry value.

Note the policy-disabled state. The value is not written to the registry with the value of 0; instead, it is explicitly deleted. This means that a component reading the policy will not find the value in the registry and will revert to using the default in the code.

Note

There is no END VALUEON/VALUEOFF statement associated with the VALUEON/VALUEOFF syntax.