Language Reference for Administrative Template Files

Article
10/08/2009

Applies To: Windows Server 2003

This section includes a complete reference guide for using the .adm language to create policy settings.

Each .adm file can contain zero or more policy settings, and each policy setting in turn can contain zero or more parts. The .adm language includes the following components:

Comments
Strings
CLASS
CATEGORY
POLICY
PART
ITEMLIST
ACTIONLIST

.Adm File Language Versions

You can specify that any part of your .adm file be evaluated only in specific versions of the Group Policy editing tools. Table 5 lists the versions of the Group Policy editing tools.

Table 5 Versions of Group Policy Editing Tools

Operating System(s)	Version	Type
Windows XP SP2	5.0	Group Policy
Windows Server 2003 and Windows XP	4.0	Group Policy
Windows Server 2000	3.0	Group Policy
Windows NT® 3.x and 4.x	2.0	System Policy
Windows 95	1.0	System Policy

Comments

You can use two methods to add comments to an .adm file. You can precede the comment either with a semicolon (;) or with two forward slashes (//). You can place comments at the end of any valid line.

Strings

To add strings to an .adm file, precede the text with two exclamation points (!!). At the end of the .adm file, all strings must be defined in the [strings] section. The strings must be enclosed in quotation marks ("). Optionally, you can enclose a variable name or hard-coded string in quotation marks.

Example

POLICY 34]!!LimitSize 
   EXPLAIN!!LimitSize_Explain   ; This string is stored in the strings section 
   TIP1 "Limit Profile Size to"   ; This string is hard coded 
 
[strings] 
LimitSize="Limit profile size" 
LimitSize_Explain="Limits the size of user profiles"

Best Practice

Place all strings in the [strings] section of the .adm file. This facilitates conversion of the .adm file to other languages (that is, for localization), as you only need to modify the [strings] section of an .adm file to port it to different languages.

CLASS

This component defines where your policy setting is displayed in the Group Policy Object Editor.

The first entry in the .adm file is the keyword CLASS. This specifies whether the subsequent entries should be displayed under the Computer Configuration or User Configuration node of Group Policy Object Editor.

Syntax

The CLASS syntax is as follows:

CLASS name

Name

This defines the name of the CLASS, which must be MACHINE or USER.

If the .adm file contains a CLASS other than the valid classes (MACHINE or USER), the errors are ignored when loaded in Group Policy Object Editor.

Example

The following examples illustrate the use of the CLASS component.

CLASS MACHINE 
CLASS USER

Note

You can define multiple CLASS USER or CLASS MACHINE sections in an .adm file. When the file is processed, all the CLASS USER sections are merged, and all CLASS MACHINE sections are merged. However, for ease of ongoing .adm file management, it is recommended that you define CLASS USER or CLASS MACHINE once.

POLICY

To identify a policy setting that the user can modify, use the keyword POLICY. The policy and its associated controls are displayed in a dialog box that administrators use to set the state of the policy. You can use multiple POLICY key names under one KEYNAME.

The following examples illustrate the syntax of POLICY.

Syntax

POLICY name 
   [KEYNAME key name] 
   [EXPLAIN help string] 
   [VALUENAME value name] 
   [CLIENTEXT guid] 
   [part definition statements] 
END POLICY

name

The name of the policy as it should be displayed in the Group Policy Object Editor namespace.

key name

This is an optional path to the registry key to use for the category. Do not include HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER in the registry path as the preceding CLASS statement determines which of these keys is used.

If you specify a key name, all PART definition statements will use this key name unless they specifically provide a key name of their own.

help string

The Help string is the text displayed in the Explain tab of the dialog box for the policy setting.

value name

Value name is the registry value to modify. Selecting this option sets the value as a REG_DWORD of 1. Clearing the option removes the registry value. To specify values other than the default values, use the VALUEON and VALUEOFF statements directly following the corresponding VALUENAME statement. These statements are specified as follows:

VALUEON on value 
VALUEOFF off value

When you use these statements, the behavior is modified such that if the administrator selects the option, the value is set to on value. If the administrator clears the option, the value is set to off value.

guid

This is an optional value that specifies the globally unique identifier (GUID) of the snap-in extension.

part definition statements

A policy can contain zero or more PART statements to specify various options, including drop-down list boxes, text boxes, and text in the lower pane of the Group Policy Object Editor.

POLICY Example

CLASS MACHINE 
 
CATEGORY!!DiskQuota 
 
   KEYNAME "Software\Policies\MS\DiskQuota" 
 
   POLICY!!DQ_Enable 
      EXPLAIN !!DQ_Enable_Help 
      VALUENAME "Enable" 
         VALUEON  NUMERIC 1 
         VALUEOFF NUMERIC 0 
      CLIENTEXT {3610eda5-77ef-11d2-8dc} 
 
      PART!!DQ_EnableTip1    TEXT     
      END PART 
   END POLICY 
 
END CATEGORY 
 
[strings] 
DiskQuota="Disk Quotas" 
DQ_Enable="Enable disk quotas" 
DQ_Enable_Help="Enables and disables disk quota management" 
DQ_EnableTip1="Enable disk quotas for all NTFS volumes"

POLICY Keywords

The valid keywords for POLICY are:

KEYNAME
PART
VALUENAME
VALUEON
VALUEOFF
ACTIONLISTON
ACTIONLISTOFF
END
HELP
CLIENTEXT
POLICY

PART

Use PART to specify various options, such as drop-down list boxes, text boxes, and text in the lower pane of Group Policy Object Editor.

For a simple policy where you only need to set a registry key to either 1 or 0, you do not need to use PART. PART allows a richer system administrator experience, and collects more information from the administrator through simple controls.

Syntax

PART name part-type type-dependent data 
  [KEYNAME key name] 
  [VALUENAME value name] 
END PART

name

Specifies the PART name as it should appear in Group Policy Object Editor. You can enclose it in quotation marks ("). Names with spaces must be enclosed in quotation marks (").

part-type

A policy PART type. Table 6 lists the valid types for POLICY.

Table 6 Policy PART Types

Type	Description
CHECKBOX	Displays a check box. The value is set in the registry with the REG_DWORD type. The value is other than zero if the check box is selected and zero if it is not selected.
COMBOBOX	Displays a combo box.
DROPDOWNLIST	Displays a combo box with a drop-down list style. The user may choose only one of the entries supplied.
LISTBOX	Displays a list box with Add and Remove buttons. This is the only PART type that can be used to manage multiple values under one key.
EDITTEXT	Displays a text box that accepts alphanumeric text. The text is set in the registry with either the REG_SZ or the REG_EXPAND_SZ type.
TEXT	Displays a line of static text. There is no associated registry value with this PART type.
NUMERIC	Displays a text box with an optional spin control that accepts a numeric value. The value is set in the registry with the REG_DWORD type.

type-dependent data

This is information about the PART.

key name

This is an optional path to the registry key to use. Do not include HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER in the registry path as the preceding CLASS statement determines which of these keys is used.

If no key name is specified, the previous key name in the hierarchy is used.

value name

The value name indicates the registry value to modify. Selecting this option sets the value to a REG_DWORD of 1, and clearing the option removes the registry value. If you want to specify values other than the default values, use the VALUEON and VALUEOFF statements directly following the corresponding VALUENAME statement. You specify these statements as follows:

VALUEON on value 
VALUEOFF off value

Keywords

The valid keywords for PART are:

CHECKBOX
TEXT
EDITTEXT
NUMERIC
COMBOBOX
DROPDOWNLIST
LISTBOX
END
CLIENTEXT
PART

Using PART Types to Add Controls to the User Interface

Using the valid keywords along with the PART component allows you to add text and various user interface controls to the properties page of the policy.

Because much of the syntax is related, the next section presents a task-based approach to writing the syntax for these PART types used to create the user interface elements above.

Using the different PART types, you can add text and controls to enhance a policy setting. These types need to be used with the PART component as previously defined.

CHECKBOX PART Type

This PART type displays a check box on the Property page of a policy setting. The value is set in the registry with the REG_DWORD type. The default behavior is as follows:

By default the check box is not selected.
A check box writes the value 1 to the registry if it is selected and 0 if it is not selected.

Syntax

PART text CHECKBOX 
   VALUENAME value name  
END PART

text

This represents the text to be displayed on the right of the check box that you are creating. You can hard code it and enclose it in quotation marks (") or you can make the string a variable by putting !! in front of the variable name.

value name

Indicates the registry value to which the selected value will be written. Selecting the option sets the value as a REG_DWORD of 1. Clearing the option removes the registry value. To specify values other than the default values, use the VALUEON and VALUEOFF statements directly following the corresponding VALUENAME statement. These statements are specified as follows:

VALUEON on value 
VALUEOFF off value

To override the default behavior:

To have the check box selected by default use DEFCHECKED. In the preceding sample, the syntax would be:

PART !!SampleChkBox_NotChked CHECKBOX 
         DEFCHECKED 
           VALUENAME "test1" 
    END PART

You can use VALUEON and VALUEOFF. This example accomplishes the following::

Writes the string "Enabled" to the registry when the check box is selected.

Writes a numeric value of 12 when the check box is not selected.

PART !!SampleChkBox_NotChked CHECKBOX 
     VALUENAME "test1" 
     VALUEON "Enabled"  
     VALUEOFF NUMERIC 12    
   END PART

To modify more than one registry key, use an ACTIONLIST.

The valid keywords for CHECKBOX are:

KEYNAME
VALUENAME
VALUEON
VALUEOFF
ACTIONLISTON
ACTIONLISTOFF
DEFCHECKED
CLIENTEXT
END

TEXT PART Type

The PART type TEXT can be used to display text on the Property page of a policy setting. Text uses the following syntax.

PART text TEXT 
END PART

text

Text that is to be displayed is entered here. You can hard code it and enclose it in quotation marks ("), or you can make the string a variable by putting !! before the variable name.

The following example illustrates the use of TEXT. The Disable Active Desktop policy deactivates Active Desktop and prevents users from enabling or disabling Active Desktop, or from modifying the configuration.

TEXT Example

POLICY !!NoActiveDesktop 
 
   KEYNAME "Software\Microsoft\Windows\CurrentVersion\Policies\Explorer" 
   EXPLAIN!!NoActiveDesktop_Help 
     VALUENAME "NoActiveDesktop" 
 
     PART !!NoActiveDesktop_Tip    TEXT     
     END PART 
 
END POLICY

The valid keyword for TEXT is END.

EDITTEXT PART Type

The EDITTEXT option allows the user to input alphanumeric text into an edit field. The text is set in the registry with the REG_SZ type.

Syntax

PART !!text EDITTEXT 
   VALUENAME value name 
END PART

text

Text to be displayed is entered here. You can hard code it and enclose it in quotation marks (") or you can make the string a variable by putting two explanation points (!!) before the variable name. This text is displayed on the left side of the edit box.

value name

The value name indicates the registry value to which the users input entered in the Edit Text box will be written.

Table 7 lists the options for EDITTEXT.

Table 7 Options for EDITTEXT

Option	Description
DEFAULT value	Specifies the initial string to place in the edit field. If this option is not specified, the field is initially empty.
MAXLEN value	Specifies the maximum length of a string. The string in the edit field is limited to this length.
REQUIRED	Specifies that the Group Policy Object Editor does not allow a policy containing this PART to be enabled, unless a value has been entered for this PART.
OEMCONVERT	Sets the ES_OEMCONVERT style in the edit field so that typed text is mapped from ASCII to OEM and back. ES_OEMCONVERT converts text entered in the edit control. The text is converted from the Windows character set (ASCII) to the OEM character set and then back to the Windows set. This ensures proper character conversion when the application calls the CharToOem <JavaScript:hhobj_1.Click()> function to convert an ASCII string in the edit control to OEM characters. This style is most useful for edit controls that contain file names.
EXPANDABLETEXT	Specifies that the text is set in the registry with the REG_EXPAND_SZ type. By default, the text is set in the registry with the REG_SZ type

The valid keywords for EDITTEXT are:

KEYNAME
VALUENAME
DEFAULT
REQUIRED
MAXLENGTH
OEMCONVERT
END
EXPANDABLETEXT
CLIENTEXT

EDITTEXT Example

An example of use of the PART component with EDITTEXT and TEXT follows:

CLASS USER 
CATEGORY !!DesktopLockDown 
 
  KEYNAME "Software\Policies\System" 
   POLICY !!Wallpaper    
    EXPLAIN !!Wallpaper_Explain 
 
     PART !!Wallpaper_Tip1       TEXT 
     END PART 
 
     PART !!Wallpaper_Filename   EDITTEXT 
        VALUENAME Wallpaper 
        MAXLEN 60 
     END PART 
 
   END POLICY 
 
END CATEGORY 
 
[strings] 
DesktopLockDown="Desktop Settings" 
Wallpaper="Desktop Wallpaper" 
Wallpaper_Explain="Used to set the desktop wallpaper" 
Wallpaper_FileName="Filename" 
Wallpaper_Tip1="Specify UNC Path for selected wallpaper"

In the preceding example, the text entered into the edit field is written to the registry key HKEY_CURRENT_USER\Software\Policies\System\Wallpaper. The text can be a maximum of 60 characters.

When this policy setting is Not Configured or Disabled, this key is not written.

EXPANDABLETEXT Example

The following example writes a value to registry with data type REG_EXPAND_SZ.

For example:

PART!!MyVariable    EDITTEXT EXPANDABLETEXT 
VALUENAME ValueToBeChanged 
END PART

REQUIRED Example

The following example generates an error if the user does not enter a value when required.

PART!!MyVariable    EDITTEXT REQUIRED 
  VALUENAME ValueToBeChanged 
END PART

MAXLEN Example

The following example specifies the maximum length of text.

PART!!MyVariable    EDITTEXT 
  VALUENAME ValueToBeChanged 
  MAXLEN 4 
END PART

DEFAULT Example

The following example specifies a default value. This can be used for text or numeric data.

PART!!MyVariable    EDITTEXT 
  DEFAULT !!MySampleText 
  VALUENAME ValueToBeChanged 
END PART

NUMERIC PART Type

Displays an edit field with an optional spinner control (an up-down control) that accepts a numeric value.

NUMERIC Syntax

PART text NUMERIC  
   VALUENAME value name  
   MIN value  
   MAX value 
   DEFAULT value 
   SPIN value  
END PART

text

This represents the text to be displayed on the right of the spin control that you are creating. You can hard code it and enclose it in quotation marks (") or you can make the string a variable by putting !! before the variable name.

value name

Indicates the registry value to which the selected value will be written.

NUMERIC Default Behavior

The default behavior for the NUMERIC PART type is as follows:

The value is set in the registry as a REG_DWORD type.
You can optionally have the value written as a REG_SZ type by using the TXTCONVERT keyword.

Table 8 shows the options for the NUMERIC type.

Table 8 Options for NUMERIC

Option	Description
DEFAULT value	Specifies the initial numeric value for the edit field. If this option is not specified, the field is initially empty.
MAX value	Specifies the maximum value for the number. The default value is 9999.
MIN value	Specifies the minimum value for the number. The default value is 0.
REQUIRED	Specifies that the Group Policy Object Editor does not allow a policy containing this PART to be enabled unless a value has been entered for this PART.
SPIN value	Specifies increments to use for the spinner control. The default is SPIN 1. SPIN 0 removes the spinner control.
TXTCONVERT	Writes values as REG_SZ strings ("1", "2", or "128") rather than as binary values.

The valid keywords for NUMERIC are:

KEYNAME
VALUENAME
MIN
MAX
SPIN
DEFAULT
REQUIRED
TXTCONVERT
END
CLIENTEXT

Examples of NUMERIC Use

The following example illustrates use of the NUMERIC PART type using the DEFAULT option.

PART!!MyVariable    NUMERIC 
  DEFAULT 5 
  VALUENAME ValueToBeChanged 
END PART

The following example illustrates use of the minimum and maximum valid values for a variable.

PART!!MyVariable    NUMERIC 
  MIN 100 
  MAX 999 
  DEFAULT 55 
  VALUENAME ValueToBeChanged 
END PART

The following example illustrates use of the NUMERIC PART type using SPIN. In this case, increments of 100 are used for the spin control.

PART !!ProfileSize    NUMERIC REQUIRED SPIN 100 
 
        VALUENAME "MaxProfileSize" 
        DEFAULT 30000 
        MAX     30000 
        MIN     300 
END PART

The following example illustrates use of the NUMERIC PART type using the TXTCONVERT option, which writes values as REG_SZ strings (such as "60") instead of binary values.

PART !!ScreenSaverTimeOutFreqSpin    NUMERIC DEFAULT 900 
 
        MIN 0 MAX 599940 SPIN 60 
        TXTCONVERT 
        VALUENAME "ScreenSaveTimeOut" 
END PART

COMBOBOX PART Type

This PART type displays a combo box. It accepts the same options as EDITTEXT, as well as the SUGGESTIONS option, which begins a list of suggestions to be placed in the drop-down list. SUGGESTIONS are separated with spaces and must be enclosed in quotation marks (") when a value includes spaces. If a suggestion name includes white space, it must be enclosed in quotation marks. The list ends with END SUGGESTIONS.

Example

The following example illustrates the use of the SUGGESTIONS option.

SUGGESTIONS 
  Alaska Alabama Mississippi "New York" 
END SUGGESTIONS

Keywords

The valid keywords for COMBOBOX are:

KEYNAME
VALUENAME
DEFAULT
SUGGESTIONS
REQUIRED
MAXLENGTH
OEMCONVERT
END
NOSORT
EXPANDABLETEXT
CLIENTEXT
END

DROPDOWNLIST PART Type

Displays a combo box with a drop-down list style. The user may choose only one of the entries supplied.

Note

GPMC requires that you define the key name and value name before you specify DROPDOWNLIST.

DROPDOWNLIST Syntax

DROPDOWNLIST uses the following syntax.

PART !!text DROPDOWNLIST  
   ITEMLIST 
     NAME name VALUE value 
     .. 
     NAME name VALUE value  
   END ITEMLIST 
END PART

text

name

This is text that will be displayed in the drop-down list for a particular item.

value

The value to be written to the specified registry key if this item is selected. Values are assumed to be strings, unless they are preceded by NUMERIC. The following example shows both string and numeric values:

VALUE "Some value"  
VALUE NUMERIC 1

The valid keywords for DROPDOWNLIST are:

KEYNAME
VALUENAME
REQUIRED
ITEMLIST
END
NOSORT
CLIENTEXT

LISTBOX PART Type

The LISTBOX PART component specifies various options such as drop-down list boxes, text boxes, and text in the lower pane of the Group Policy Object Editor. LISTBOX accepts the options shown in Table 9.

Table 9 LISTBOX Options

LISTBOX Option	Description
ADDITIVE	By default, the content of list boxes overrides any values set in the target registry. This means that a control value is inserted in the policy file that causes existing values to be deleted before the values set in the policy file are merged. If this option is specified, existing values are not deleted, and the values set in the list box is in addition to whatever values exist in the target registry.
EXPLICITVALUE	This option makes the user specify the value data and the value name. The list box shows two columns, one for the name and one for the data. This option cannot be used with the VALUEPREFIX option.
VALUEPREFIX prefix	The prefix you specify is used in determining value names. If a prefix is specified, the prefix and an incremented integer are used, instead of the default value naming scheme described previously. For example, a prefix of "SampleName" generates the value names "SampleName1", "SampleName2", and so on. The prefix can be empty (""), which causes the value names to be "1", "2", and so on.

By default, only one column appears in the list box, and for each entry a value is created whose name and value are the same. For instance, a "name" entry in the list box creates a value called "name" that contains data called "name". When using a LISTBOX, use the ADDITIVE keyword unless you have a specific reason not to do so.

The valid keywords for LISTBOX are:

KEYNAME
VALUEPREFIX
ADDITIVE
NOSORT
EXPLICITVALUE
EXPANDABLETEXT
END
CLIENTEXT

Note

Windows XP SP2 fixed issues relating to the LISTBOX ADDITIVE functionality. For more information, see the "Changes to LISTBOX ADDITIVE" section in this document.

ACTIONLIST

You can use an action list to specify a set of arbitrary registry changes to make in response to a control being set to a particular state.

Syntax

The ACTIONLIST syntax is as follows:

ACTIONLIST 
[KEYNAME key name] 
VALUENAME value name  
VALUE value  
END ACTIONLIST

key name

This is an optional path to the registry key. Do not include HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER in the registry path as the preceding CLASS statement determines which of these keys is used. If no key name is specified, the previous key name in the hierarchy is used.

value name

Indicates the registry value to modify. Selecting this option sets the value to a REG_DWORD of 1, and clearing the option removes the registry value. If you want to specify values other than the default values, use the VALUEON and VALUEOFF statements directly following the corresponding VALUENAME statement. You specify these statements as follows:

VALUEON on value  
VALUEOFF off value

value

Values are treated as strings unless they are preceded by NUMERIC, as in the following examples:

VALUE "Some value"  
VALUE NUMERIC 1

If VALUE is followed by DELETE (for example, VALUE DELETE), the registry entry is deleted.

Table 10 lists the two variants for ACTIONLIST that can be used with POLICY and CHECKBOX.

Table 10 Variants for ACTIONLIST

Variant	Description
ACTIONLISTON	Specifies an optional action list to be used if the check box is selected.
ACTIONLISTOFF	Specifies an optional action list to be used if the check box is not selected.

ACTIONLIST Example

The following example illustrates the use of ACTIONLISTON and ACTIONLISTOFF.

POLICY  "Deny connections requests" 
    EXPLAIN "If enabled, TS will stop accepting connections" 
    ACTIONLISTON 
       VALUENAME "fDenyTSConnections"    VALUE NUMERIC 1 
    END ACTIONLISTON 
    ACTIONLISTOFF 
       VALUENAME "fDenyTSConnections"    VALUE NUMERIC 0 
    END ACTIONLISTOFF 
END POLICY

Additional Elements

The .adm language supports the following elements:

KEYNAME

The KEYNAME keyword is used within a CATEGORY to define which key within the registry is modified as a result of an action here. KEYNAME should be followed by the registry path to the key that contains the value that you want to change. Do not include HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER in the registry path as the preceding CLASS statement determines which of these keys is used.

If the KEYNAME contains a space, you must enclose the string in quotation marks (").

VALUENAME

Defines the options available within a POLICY. First identify the registry value that is to be modified as a result of using the keyword VALUENAME. For example, VALUENAME MyFirstValue.

The following example illustrates the use of VALUENAME. The Disable Boot / Shutdown / Logon / Logoff status messages policy prevents the display of system status messages.

POLICY!!DisableStatusMessages 
    KEYNAME "Software\Microsoft\Windows\CurrentVersion\Policies\System" 
       EXPLAIN!!DisableStatusMessages_Help 
       VALUENAME "DisableStatusMessages" 
END POLICY

Unless you specify otherwise, the value is written in the following format when the user checks or clears the option:

Checked. Uses a REG_DWORD type with a value of 1.
Cleared. Removes the value.

You can specify options other than these defaults by using VALUEOFF and VALUEON. If the option is to be selected within the lower pane of the Group Policy Object Editor, the VALUENAME needs to be within a PART scope.

CLIENTEXT

The CLIENTEXT keyword is used to specify which client-side extension to the Group Policy Object Editor needs to process the particular settings on the client computer. By default, the registry extension processes all settings configured under the Administrative Templates node. The CLIENTEXT keyword changes the default behavior and causes the specified extension to process these settings after the registry extension has placed them in the registry.

CLIENTEXT must be used within either the POLICY scope or the PART scope and should follow the VALUENAME statement.

The following example illustrates use of CLIENTEXT.

POLICY !!DQ_Enforce 
 
            #if version >= 4 
                 SUPPORTED !!SUPPORTED_Win2k 
            #endif 
 
            EXPLAIN !!DQ_Enforce_Help 
                 VALUENAME "Enforce" 
                 VALUEON  NUMERIC 1 
            VALUEOFF NUMERIC 0 
            CLIENTEXT {3610eda5-77ef-11d2-8dc5-00c04fa31a66} 
 
        END POLICY

The GUID that follows the CLIENTEXT keyword is the GUID of the client-side extension. The client-side extensions are listed in the registry under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WindowsNT \CurrentVersion\Winlogon\GPExtensions.

VALUEON and VALUEOFF

You can use VALUEON and VALUEOFF to write specific values based on the state of the option. To enable this functionality, you can write the .adm file as described in the following examples:

KEYNAME key name 
   POLICY!!MyPolicy 
     VALUENAME ValueToBeChanged 
     VALUEON "Turned On" VALUEOFF "Turned Off" 
   END POLICY

KEYNAME key name  
   POLICY!!MyPolicy 
     VALUENAME ValueToBeChanged 
     VALUEON 5 VALUEOFF 10 
   END POLICY

Using Simple Policies and Policies with the VALUEOFF and VALUEON Statements

This section presents two examples that illustrate the difference between using the default policy states and specifying VALUEON and VALUEOFF statements. There is a significant difference between the two example policies.

Example 1

In this example, no explicit VALUEON or VALUEOFF statements are used. This means that the Administrative Templates use the default behavior when the user changes the state of this policy.

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

Table 11 lists the default behavior.

Table 11 Example 1 Policy Defaults

State	Behavior
Policy setting enabled	A DWORD with the value 1 is written to the registry.
Policy setting disabled	The registry value is deleted.
Policy setting not configured	Nothing is changed in the registry.

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 fall back to using the default in the code.

Example 2

In this example, the state values are explicitly defined, so when the user changes the policy, the Administrative Templates use these values.

POLICY!!EnableSlowLinkDetect 
    EXPLAIN!!EnableSlowLinkDetect_Help 
    KEYNAME "Software\Policies\Microsoft\Windows\System" 
    VALUENAME "SlowLinkDetectEnabled" 
        VALUEON NUMERIC 1 
        VALUEOFF NUMERIC 0 
END POLICY

Table 12 lists the behaviors in Example 2.

Table 12 Example 2 Policy Defaults

State	Behavior
Policy setting enabled	A DWORD with the value 1 is written to the registry.
Policy setting disabled	A DWORD with the value 0 is written to the registry.
Policy setting not configured	Nothing is changed in the registry.

EXPLAIN

The EXPLAIN keyword is used to provide online Help text for a specific Group Policy. In Windows 2000, the Properties page for each policy setting includes an Explain tab, which provides details about the policy settings.

Each Group Policy that you create should include one EXPLAIN keyword, followed by at least one space, and then the EXPLAIN string in quotation marks (") or a reference to the Help string. For example:

POLICY!!Pol_NoConfigCache 
#if VERSION >= 3 
EXPLAIN!!Pol_NoConfigCache_Help 
#endif 
    VALUENAME "NoConfigCache" 
    PART!!Lbl_NoConfigCacheHelp1       TEXT 
END PART 
END POLICY 
       ..... 
 
[Strings] 
Pol_NoConfigCache_Help="Prevents users from changing the automatic  
synchronization behavior at logoff."

In the preceding example, Help is offered for one of the Offline Files options. The EXPLAIN keyword wrapped in the #if VERSION allows this .adm file to be used with the Windows 2000 Group Policy Object Editor (version 3).

Line Breaks

To start text on a new line or to create a line break, use this syntax:

\n = Starts a new line 
\n\n = Creates a line break

#If Version for Version Comparison

The IF VERSION conditional statement is used to control the display of certain policy settings and features in the Administrative Templates node, based on the version of the Group Policy Object Editor that you are using. IF VERSION allows for part of the .adm files to be conditionally parsed and ignored by earlier versions of the Group Policy Object Editor tool. For example, the SUPPORTED tag is not supported on versions of the Group Policy Object Editor earlier than version 4. For this reason any statement using the SUPPORTED tag should be enclosed by #If Version...#endif.

You can specify that any part of your .adm file be evaluated only in specific versions of the Group Policy editing tools, as shown in Table 5, in the ".Adm File Language Versions" section of this document.

To compare versions, use the following syntax:

#if Version (operator) x 
#endif

The valid operators are listed in Table 13.

Table 13 Valid Operators for the Version Statement Number

Operator	Signifies
> (GT)	Greater than. For example, a > b means a is greater than b.
< (LT)	Less than. For example, a < b means a is less than b.
== (EQ)	Equal. For example, a == b means a is equal to b.
!= (NE)	Not equal.
>= (GTE)	Greater than or equal to. For example, a >= b means a is greater than or equal to b.
<= (LTE)	Less than or equal to. For example, a <= b means a is less than or equal to b.

.Adm File String/Tag Limits

Various restrictions apply to .adm files and settings. Table 14 provides a complete list of these restrictions.

Table 14

File String	Tag Limits
Maximum string length for Explain text	4096
Maximum string length for Category Explain text	255
Maximum string length for EDITTEXT string	1023

Language Reference for Administrative Template Files

.Adm File Language Versions

Comments

Strings

Example

Best Practice

CLASS

Syntax

Name

Example

CATEGORY

Syntax

name

key name

policy definition statements

Example

Supported Tag

CATEGORY Keywords

POLICY

Syntax

name

key name

help string

value name

guid

part definition statements

POLICY Example

POLICY Keywords

PART

Syntax

name

part-type

type-dependent data

key name

value name

Keywords

Using PART Types to Add Controls to the User Interface

CHECKBOX PART Type

Syntax

text

value name

TEXT PART Type

text

TEXT Example

EDITTEXT PART Type

Syntax

text

value name

EDITTEXT Example

EXPANDABLETEXT Example

REQUIRED Example

MAXLEN Example

DEFAULT Example

NUMERIC PART Type

NUMERIC Syntax

text

value name

NUMERIC Default Behavior

Examples of NUMERIC Use

COMBOBOX PART Type

Example

Keywords

DROPDOWNLIST PART Type

DROPDOWNLIST Syntax

text

name

value

LISTBOX PART Type

ACTIONLIST

Syntax

key name

value name

value

ACTIONLIST Example

Additional Elements

KEYNAME

VALUENAME

CLIENTEXT

VALUEON and VALUEOFF

Using Simple Policies and Policies with the VALUEOFF and VALUEON Statements