Export (0) Print
Expand All
6 out of 6 rated this helpful - Rate this topic

Language Reference for Administrative Template Files

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
noteNote
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.

CATEGORY

After you define the CLASS component, you can use the CATEGORY component to display a node name under which your policy setting is displayed in the Group Policy Object Editor.

noteNote
You can create child nodes by nesting a CATEGORY within another CATEGORY.

Syntax

To specify a CATEGORY, use the following syntax.

CATEGORY!!name 
    KEYNAME key name 
    [policy definition statements] 
END CATEGORY

name

The CATEGORY name as it should appear in the Group Policy Object Editor list box. Optionally, you can enclose the variable name in quotation marks ("). Names with spaces must be enclosed in quotation marks.

key name

The key name is an optional path to the registry key to use for the CATEGORY.

Do not use HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER in the registry path as the preceding CLASS statement specifies the keys to use. If you specify a key name, all child categories, policies, and parts will use this key name, unless they specifically provide a key name of their own. Names with spaces must be enclosed in double quotation marks.

If a key name is not specified and if no higher level category specifies a key name, each policy in this category must specify its own key name: otherwise, the key name for the next category that does specify a key name will be used.

policy definition statements

A CATEGORY can include zero or more POLICY statements. A POLICY definition statement cannot appear more than once within a single category, as shown in the following sample code.

Example

CLASS USER 
 
; The following categories will be displayed 
; under User Configuration 
 
CATEGORY !!Desktop 
   KEYNAME "Software\Policies\System" 
 
   ; <INSERT POLICIES HERE> 
 
   CATEGORY !!InternalApps 
   KEYNAME "Software\Policies\InternalApps" 
 
    ; <INSERT POLICIES HERE> 
 
   END CATEGORY 
END CATEGORY 
 
[strings] 
Desktop="Desktop Settings" 
InternalApps="Line of Business Apps settings"

Supported Tag

The Group Policy Object Editor uses the Supported tag to populate the Requirements field. This tag informs the Group Policy administrator about the platforms or applications for which the policy setting is supported. For example, many of the policy settings included in the System.adm file use a Supported tag that specifies a specific service pack release. Often, the string used for the Supported tag will make reference to multiple operating system or service packs.

While operating system components generally use an operating system or service pack reference in this field, applications – which can be updated outside the release of a service pack – can refer to a specific version of an application. The Supported tag is an essential element in the data presented to Group Policy administrators to ensure they are equipped with the right information to make informed decisions about the use of the policy setting.

Because your .adm file may be localized, it is highly recommended that the Supported tag use the !!Stringname construct, which allows the referenced string to be localized easily. In addition, since the Supported tag is only supported in Windows XP and later operating systems, it should be enclosed within a Version construct, as follows (this ensures that the Windows 2000 version of Group Policy Object Editor does not attempt to interpret the Supported tag):

#if version >= 4 
        SUPPORTED!!SUPPORTED_MyApplication 
    #endif

CATEGORY Keywords

The valid keywords for CATEGORY are:

  • KEYNAME

  • CATEGORY

  • POLICY

  • END

  • SUPPORTED

noteNote
If you have a CATEGORY defined with a default KEYNAME in it, and the same category is found again later in the .adm file, that same default KEYNAME is still in effect. This means that you can get an error message about KEYNAME being defined twice, when it was actually just defined in the same category earlier. To remove the error condition, remove the duplicate category entry.

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.

If a key name is not specified and if no higher level category specifies a key name, each policy in this category must specify its own key name: otherwise, the key name for the next category that does specify a key name will be used.

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

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.

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.

noteNote
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

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 !! in front of the variable name.

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

noteNote
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

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.