Software Development Kit (SDK)

The Microsoft® Server Appliance Kit (SDK) provides the tools to develop software for your server appliance that takes advantage of the features provided by the Server Appliance Kit. These features make the server easier to manage as a remotely administered device by providing a basic user interface (UI) on the device itself and the capability to administer the server remotely.

With the SDK, you can utilize the three frameworks provided by the Server Appliance Kit:

  • The Web User Interface Framework supports an extensible Web-based user interface (Web UI) that provides a Web UI for the most common server-management tasks. You can use the Web UI framework to add support for other management tasks, and you can replace any or all of the default Web UI components with those specific to your organizational needs.
  • The Local User Interface Framework provides the programming interface for a small display and keypad located on the server. Administrators can use this interface to perform initial configuration tasks (such as setting the IP address of the server), monitor basic status, and perform basic management tasks.
  • Using the Localization Framework, you can dynamically provide your Web UI and Local UI elements in the language of the user's choice. You can create resource dynamic-link libraries (DLLs) for each language you want to support and install those DLLs in the specified locations. If the user selects a language that has a corresponding DLL as the preferred language, your Web and local UI elements will be displayed in that language.

The Server Appliance Kit includes a variety of samples that illustrate how to use these frameworks. For more information, see SDK Samples.

For information about changes made to the Server Appliance Kit 3.0 since the previous version, see Changes in this version.

Copyright© 2000-2003 Microsoft Corporation. All rights reserved.


SDK Samples

Included on the Microsoft Server Appliance Kit (SAK) CD-ROM are a number of samples that illustrate how to build applications using the SAK frameworks. The SDK folder on the CD-ROM contains three folders.

  • The Chime folder contains a complete application that demonstrates how to develop a variety of Web user interface (UI) elements that can be used to configure the application. For more information, see Chime sample application.
  • The Volmgmt folder contains code samples that an original equipment manufacturer (OEM) can use as a template for developing an application to manage disks and volumes through a Web UI. You can install the sample code to see how it works by running installvolmgmt.cmd in this folder. Once you have installed this sample, you cannot uninstall it.
  • Six folders in the Webui folder contain additional samples of how to use a particular feature in your application.
    Folder | Description
    Alerts | Shows how to add an alert to the status page of the Web UI.
    Hello world | Contains samples that illustrate how to create Web content using progressively more complex examples.
    Localize | Demonstrates how to access localized Web content in your application.
    OTS | Shows how to create an object/task selector page that displays a list of objects and a list of tasks associated with those objects.
    Resources | Illustrates how to display current system resource information on the status page of the Web UI.
    Templates | Provides simple templates you can use as the starting point for developing Web UI elements for your application.

    To see how the WebUI samples work, you can install each of the samples by running install.cmd in the folder containing the sample. To uninstall a sample, run uninstall.cmd in the same folder.

Another folder in Webui, named Debug, contains a file that can help you troubleshoot your Web UI add-in. For more information, see Debugging.


Chagnes in this version

Server Appliance Kit

Changes in this version

New paths to Web UI framework files

To avoid conflicts with certain Windows Server 2003 files, the Server Appliance Kit 3.0 installs localized files in a different location than in previous versions:

  • Localized Web UI framework and local UI framework resources are now located in %systemroot%\system32\ServerAppliance\mui3.
  • Localized Help files for Web UI add-ins are now located in %systemroot%\system32\ServerAppliance\web\Admin\help3.

Security enhancements

The Web User Interface (UI) framework of the Server Appliance Kit 3.0 contains two new features that help prevent the server from being attacked through the Web UI. The two methods of attack addressed by these new features utilize access to parent directories of active server pages and cross-site scripting.

Parent paths

An important change in the Server Appliance Kit 3.0 that may affect your current Active Server Pages (ASP) applications is that parent paths are not enabled for ASP applications by default. When parent paths are not enabled, an ASP page cannot use paths that are relative to the current directory (using the ../ notation). Enabling parent paths is a potential security risk because an "include" path can access critical or confidential files outside the root directory of the application.

For example, ASP pages developed for earlier versions of the Server Appliance Kit could contain the following instructions:

<!-- #include file="../inc_framework.asp" -->
<!-- #include file="./myincludefile.asp" -->

To run correctly on a server appliance created using the Server Appliance Kit 3.0, these directives must use the following syntax:

<!-- #include virtual="/admin/inc_framework.asp" -->
<!-- #include file="myincludefile.asp" -->

The first line in this example specifies an absolute path to the "include" file, avoiding the relative path that can be used to gain access to files outside of the root directory.

The use of the virtual keyword applies to the framework files in the Admin folder.

To provide maximum security, Microsoft recommends that any subfolders of the Web/Admin folder that you create inherit their permissions from the parent folder.

Cross-site scripting

A cross-site scripting attack can occur when a user unknowingly runs a malicious script that takes advantage of a user's authenticated connection to a computer or a Web site. In many cases, the malicious code sends a script to a form on another Web site causing that code to be executed with the user's privileges on that site. In other cases, it is not necessary for code to be sent to a form. Instead, the malicious code is directly executed by the user's computer, taking advantage of the user's privileges on that computer.

The Web UI framework has been enhanced to prevent this type of attack. The Web UI framework of the Server Appliance Kit 3.0 requires an ASP application using the Web UI framework to obtain and supply a session-specific secret key before the Web UI framework follows a hyperlink or accepts input through a form. You obtain the key by calling the SAI_GetPageKey function defined in inc_pagekey.asp. This function assigns the key the value of the SAI_FLD_PAGEKEY variable. You can then use this variable to pass the key as part of the hyperlink request or form-input validation.

The following code example illustrates how to use this function to obtain and pass the key to a form.

<FORM>

   <INPUT TYPE=”hidden” NAME=”<%=SAI_FLD_PAGEKEY%>” VALUE=”<%=SAI_GetPageKey()%>”>

</FORM>

In the following example, the SAI_GetPageKey function is used in an anchor tag to confirm that the requesting page is part of the administration site and is included in the current user’s session.

<A HREF=”/admin/samplepage.asp?<%=SAI_FLD_PAGEKEY%>=<%=SAI_GetPageKey()%>&otherarg=1">click here</A>

Finally, this example shows how to pass the value of SAI_FLD_PAGEKEY to the SA_MungeURL function.

<SCRIPT LANGUAGE=”Javascript”>
    function GoSomewhere()

    {

        var strURL = g_strDestinationURL;

        strURL = SA_MungeURL(strURL, SAI_FLD_PAGEKEY, g_strSAIPageKey);
        // These last two arguments are client-side variables declared by inc_pagekey.asp.

        top.location.href = strURL;

    }

</SCRIPT>

It is not necessary to call SAI_GetPageKey when constructing a URL to pass to a Web UI framework function, such as setting the URL for an Object/Task Selector task or calling SA_ServeOnClickButton. SAI_GetPageKey is required only when linking directly from one add-in page to another within the Web UI framework. Do not call SAI_GetPageKey when linking to a page outside the Administration web site (for example, to a page on the World Wide Web) because the page will not be able to use the page key, and the key will be sent on the network in plain text, creating a security risk.


Web User Interface Framework

The Web UI is an HTML-based application used to configure and manage the server appliance from a remote client. By extending the Web UI, you can build a consistent, reliable, and extensible UI. The Web UI supports client computers with Microsoft® Internet Explorer version 5.0 and later, or Netscape 6.01, and Microsoft Internet Information Services (IIS) 6.0 on the server appliance. All configuration data is accessed using the Windows Management Instrumentation (WMI) and Component Object Model (COM) interfaces, with the bulk being handled by WMI providers.

The Microsoft® Server Appliance Kit 3.0 Web UI framework supports a simplified interaction model that consists of three types of items: tasks, resources, and alerts. To present these items, the framework provides several page types. To effectively use the framework, you need to understand this model.

The framework provides navigation items and taskbars to allow the user to find the desired task quickly. The primary navigation bar bundles tasks into general categories, known as primary navigation pages. Each category can contain a set of specific tasks, called secondary navigation bar items. Secondary navigation bar items can either be navigation pages, task pages or area pages. Navigation and area pages allow for another level of selection. This flexibility allows you to create a sophisticated UI.

Tasks are used to configure the settings for an item or to perform an action. Examples include setting the server appliance name, IP address configuration, or date and time. The Web framework provides property pages, multitabbed property pages and wizards for implementing tasks. Multitabbed property pages and wizards are used for tasks that require multiple pages. Wizards provide more information to the user and allow for different options based on the user’s input.

Resources are items that have a dynamic status. Examples include printers, Internet connections, and disk drives. The Web framework provides one method for displaying simple status information for a resource, and another for displaying extended status information. Resources are displayed under the Status heading on the main status page and they can also be displayed on the Shutdown status page.

Alerts are pieces of information that are displayed to the user. Alerts may contain good or bad news. Examples include Date and time not set up, and Failed connection to the Internet. Alerts are displayed under the Alerts heading of the main status page.

The Web Element Manager service, which acts as a configuration database manager for UI elements, provides the overall flexibility and extensibility of the structure. With the Web Element Manager, everything from menu and navigation bar items to wizard pages may be added to the Web UI.

Prerequisites

This guide assumes you have a basic knowledge of Web development, with knowledge of scripting languages such as VBScript and JScript, as well as Active Server Pages (ASP) and HTML.

For detailed information about how to implement the framework and add custom pages, see Extending the Web UI.


Developing a Web UI add-in

The following instructions should lead you through the development of a Web UI add-in.

Prerequisites

  • Development system with Microsoft® Windows® Server 2003 installed on standard computer hardware
  • Microsoft® Server Appliance Kit (SAK) 3.0 CD-ROM

To develop a Web UI add-in

  1. Install the Server Appliance Kit. In the Setup Wizard, choose one of the two configurations: Windows Storage Server 2003 or custom. Accept the default components.
  2. Read the Web UI Framework section to understand the various ways you can add content to the server appliance Web UI, and to understand the different types of pages that are supported in the framework.
  3. Copy SDK Samples from the SAK CD-ROM to use as templates.
  4. Design your Web UI content, based on the guidelines presented in Web UI Design Requirements.
  5. Develop your Web UI content. This will include the following tasks:
    • Creating a Resource DLL
    • Adding a New Primary Navigation Page
    • Adding a New Secondary Navigation Page
    • Creating a Task Object
    • Adding pages of the appropriate page type
    • Adding an Alert to the Web Element Database
    • Adding a Resource to the Status or Shutdown Page
    • Adding Logs
  6. Add Localized Text Resources for your Web UI content.
  7. Package your add-in so that it can be installed by your customer, who is typically an engineer building a pre-installable image to manufacture an appliance. This can be a simple .bat or .msi file–see MSDN for more information. The installation package will copy your Web content into the %ServerApplianceWebRoot%\FeatureName folder and set up the registry correctly.
  8. Test your add-in. Install the add-in on your development machine or on a dedicated test machine and verify that it has no errors and does not cause any errors in the other add-ins that might be used with this feature.

Once you have verified the quality of your add-in, it is ready to distribute to your customers.


Server Appliance Tasks

The server appliance tasks are listed on navigation pages. A navigation page is a list of task elements. Each task element provides a link to another navigation page, an area page or a Web task that is implemented as either a property page, a multitabbed property page, or a series of wizard pages. Web tasks collect and validate information provided by the user, and then use the task coordinator service to execute low-level tasks, as shown in the following diagram.

The use of the task Coordinator as depicted in the diagram is optional. It is possible to perform any required configuration directly from the MyTask.asp file.

Server appliance task process flow

Related Topics


Alerts

Alerts inform the user about actions that need to be taken or about events that are occurring and that do not require any action. Alerts do not replace the Windows event log, which provides a history of events and errors that have occurred. Alerts apply solely to current information. If the condition is no longer true, the alert is automatically cleared. For example, there is an alert that indicates a backup is in progress. Once the backup is complete, the alert is cleared. Alerts can also provide the user with information about what needs to be configured. For example, there is an alert that informs the user that the date and time need to be set up. This alert is cleared when the user sets the date and time. The user can also manually clear an alert.

You should avoid raising alerts for many events that are essentially identical, such as separate disk errors.

The following diagram illustrates the process that an alert undergoes before it is displayed in the Messages section of the Status page.

Process flow for displaying an alert

The Server Appliance Kit provides a number of built-in alerts. The following table summarizes these alerts.

Alert log | Alert ID | Alert type | Web UI main status page | Shutdown status page | Local UI | Sent as an e-mail message | Alert definition
MSSAKitCore | 0xC0010001 | Critical | Yes | No | Yes | Yes | Raised when primary operating system failed and the system failed over to a backup operating system.
MSSAKitComm | 0x400100B0 | Informational | Yes | No | No | No | Raised when the date and time of the server appliance was never set up.
Backup | 1 | Informational | Yes | Yes | No | Yes | Event log entries are made when a backup is started and completed for source ntbackup. These are mapped to a shutdown-related alert. This alert is automatically cleared when the backup is complete.
Restore | 1 | Informational | Yes | Yes | No | Yes | Event log entries are made when a restore operation starts and completes for source ntbackup. This event log entry is mapped to a shutdown-related alert. This alert is automatically cleared when the restore operation completes.
ShutdownPending | 1 | Informational | No | Yes | No | No | An alert is generated when a shutdown is scheduled. The alert is automatically cleared after the scheduled time has passed or when the scheduled shutdown is cancelled.
RestartPending | 1 | Informational | No | Yes | No | No | An alert is generated when a restart operation is scheduled. The alert is automatically cleared after the scheduled time has passed or when the scheduled restart operation is cancelled.
MSSAKitComm | 0x4C00000B | Informational | Yes | No | No | No | Raised when the alert e-mail message of the server appliance was never setup.
Selfsigncertmsg.dll | 0x40010001 | Warning | Yes | No | No | No | Raised when the server appliance first starts up with a default certificate.

Related Topics


Resources

Resources represent items that have status, for example a printer or a network connection. Resources should be used to provide the user with important information about the system. Resources provide a single status indication but can also provide a link to more detailed information.

Resources can be displayed on the Status page, as shown in the following diagram.

Process flow for adding resources to status page

Related Topics


Page Types

The Microsoft Server Appliance Kit Web framework supports several types of Web pages, each geared toward a particular purpose.

Area pages provide information or navigation that is not suitable for a standard navigation page. There are two types of area pages, Object/Task Selector and custom. Object/Task Selector area pages consist of a title bar, an Object/Task Selector table, and possibly a Back button. Custom area pages consist of a title bar, possibly a Back button, and any other items you add. The Object/Tasks Selector control allows a developer to create a Web page that will launch a task that requires the selection of an object. Examples include actions performed on users, groups, disks, and volumes.

Help pages are rendered when a user either clicks the Help tab or invokes context-sensitive Help by clicking the ? icon.

Multitabbed property pages are used for complex input and configuration tasks that are easy to break up into sets of data, such as creating shares.

Navigation pages are completely data drive pages that provide a set of links to other pages.

Pagelets are used for resource alert details and IFRAMEs on alert details page. They can also be used on other types of pages that contain an IFRAME.

Property pages are used for simple input and configuration tasks that do not require more than one screen, such as setting the date and time of the server appliance.

Status page provides information about resources and alerts, and provides an area from which to launch tasks. The Status page consists of the following three sections:

  • The Resources section
  • The Alerts section
  • The Detail section

Wizard pages are implemented to lead users through a process and to provide helpful information about how to complete the process. Wizard pages are also used if automated tasks need to be tested.

For more information about a particular page type, choose one of the following topics:

Area Pages

Help Pages

Multitabbed Property Pages

Pagelet

Property Pages

Status Pages

Wizard Pages


Navigation

The Web UI of the Server Appliance Kit provides various navigation pages to help users move through the system and accomplish tasks. Navigation pages contain hyperlinks the user can click to move to other navigational pages, or to specific informational or task-oriented pages. Navigation pages contain the following elements:

  • Page Title The page title, for example, Welcome, and page description which provides information about the tasks the user can perform by clicking the hyperlinks on the page.
  • Large Image A graphic that helps the user quickly gain context. It is not required.
  • Links Links consist of an icon, a title and description, and optional hover text. These elements exist to give the user enough information to decide whether to click the task.

The following screenshot shows a typical navigation page.

Sample navigation page

Related Topics


Area Pages

Area pages provide information and allow users to navigate to pages that are not available through a standard navigation page.

In general, area pages consist of a title bar, an optional Object/Task Selector control, and navigation buttons.

The following illustration shows a typical area page.

Sample area page

Area page content is up to you as the developer. However, area pages generally incorporate an Object/Tasks Selector control and navigational buttons.

Related Topics


Custom Pages

Custom pages are area pages which do not have an Object/Task Selector control in them.

Related Topics


Pagelet

Pagelets are pages that are contained within another page using an IFRAME HTML tag. Pagelets are like area pages without a branding or status bar and without navigation bars.

The following screenshot shows three pagelets contained within an area page.

Three sample pagelets in an area page

Related Topics


Object Task Selector Pages

Server Appliance Kit

Object/Task Selector Pages

The Object/Task Selector page is created with the Object/Task Selector control display. An object/task selector page displays a list of objects and a list of tasks. It will launch a task that requires a selection of an object. Examples of this include the actions on users, groups, disks, and volumes.

The Object/Task Selector can include navigation buttons that allow users to maneuver through very large tables. The following illustration shows an Object/Task Selector that incorporates navigation buttons.

Sample object/task selector page with navigation buttons

The Object/Task Selector can include a drop-down list and a search field which allows users to select one of the visible columns and then type in a search string. This capability enables subsetting of the table data, which is very useful for large data sets.

The Object/Task Selector can allow the user to choose a column heading to change the sort order. It also allows the user to select more than one item. Tasks are enabled or disabled based on user's actions.

The following illustration shows an Object/Task Selector that incorporates these features.

Sample object/task selector page with column heads for sorting and allowing multiple selections@

Related Topics


Property Pages

Property pages are used for very simple input and configuration tasks that do not require more than one screen.

Use a property page for services that do not require complicated setup, such as setting the date and time of the server appliance. All configuration items must fit on a single page, and one item must not depend on the state of another item. Changes to the setup cannot be made until the user chooses OK.

The following illustration shows a typical property page.

Sample property page

Property page content is your decision. The footer, however, is static. The OK button will submit the form, apply any changes made, and return the user to the previous page. The Cancel button will discard any changes the user makes and return to the previous page.

Related Topics


Multitabbed Property Pages

Multitabbed property pages allow the user to make configuration changes. Multitabbed property pages are used for complex input and configuration tasks that are easy to break into sets of data, for example, creating user account groups. Use this control only if your data does not fit on a single page and if the related pages have meaningful defaults. In other words, the default values on each tab of a multitabbed property page should be valid, so that a user can make whatever changes are required and then click OK to completely close the task from the active tab, without modifying data in other tabs located on the property page.

The following illustration shows a multitabbed property page with the first tab visible.

Sample multitabbed property page showing first tab

The following illustration shows a multitabbed property page with the second tab visible.

multitabbed property page showing second tab

The content of the body of the multitabbed property page is your choice. The footer, however, is static. The OK button will submit the form, apply any changes made, and then return the user to the previous page. The Cancel button will discard any changes made and return the user to the previous page.

Related Topics


Wizard Pages

Wizard pages are implemented to lead users through a complicated setup or a multistep process, and to provide helpful information along the way. Wizard pages allow you to display different pages based on the user's choices. They also allow the tasks to perform before the user has accepted the configuration changes. For instance, you can have the user upload a file in one wizard page and then use that information in the next wizard page.

The footer on wizard pages provides three buttons for navigational control within the wizard. The Back button sends the user to the previous page of the wizard. The Next button will check the validity of any configuration items on the current page and take the user to the next page. The Cancel button will discard any pending changes made by the user and then return to the page from which the wizard was called. On wizard finish pages, the Next button is replaced by the Finish button, which performs the requested operation, and then returns the user to the page from which the wizard was called.

Introduction Page

The following screenshot shows the first page of a wizard, which explains what the wizard will set up, and what the user will need to complete the wizard.

Sample wizard introduction page

The header bar of the wizard introduction page describes the task at hand.

A wizard page must have the title, Welcome to the <wizard name> Wizard. The text must state what the wizard does and any information that the user will need to complete the wizard. Finally, the text must also include To continue, click Next.

The footer, however, is static. The Back button is inactive, the Next button will verify the contents of the page, and, if the contents are acceptable, the Next button will deliver the next page. The Cancel button will discard any changes made by the user, and then return to the page from which the wizard was called.

Interior pages

The interior pages of the wizard allow users to enter information necessary to configure the particular task. The following screenshot shows the actual wizard configuration pages that are displayed. These pages may vary depending on the selections of the user.

Sample wizard interior page

Similar to the wizard introduction page, the header bar of each interior wizard page provides the user with information about the task at hand. While the footer of the interior wizard pages is still static, the Back button on the interior pages sends the user to the previous page without checking the current page for content validity. The Next button on the interior pages verifies the contents of the page, and, if the contents are acceptable, delivers the next page. The Cancel button will discard any changes made by the user, and then return to the page from which the wizard was called.

Finish Page

The final page of the wizard lists all the configurable parameters and their new values. When the user clicks the Finish button, the server appliance will start using the new values. The following screenshot shows the wizard configuration page after the user has selected the chime settings and is being prompted to click the Finish button to accept the new settings.

Sample wizard finish age

As in the case of the wizard introduction and interior pages, the header bar of the finish page provides the user with information about the task at hand.

The wizard finish page content must display all the configurable elements addressed by the wizard and how they will be configured. Displaying this information provides a final verification to the user.

Related Topics


Status Pages

The status page provides information about resources and alerts, and provides an area where alerts and resources can display detailed information. The status page consists of the following three sections:

  • The Resources section, labeled Status
  • The Alerts section, labeled Alerts
  • The Detail section, labeled Install new certificate in the example below.

The following illustration shows a typical status page.

Sample status page

Related Topics


Alerts Overview

Alerts notify the user of the system’s status. Alerts range from normal to critical depending on the severity of the problem. Alerts are useful since they give the user valuable information about the system and help the user know about what is happening. There are four areas where alerts display: the local display, main status page, shutdown page, and (if the server is properly configured) alert e-mail.

When there are no alerts, the framework will display as such in the title and notification areas. However, when there are alerts present, the framework will display the icon that matches the severity of the alert. The icon and text link to more detailed information about the alert. One alert is displayed in each row.

There can be zero or more links to other pages. The link text is derived from the CaptionRID of the link and the link hover text is derived from the DescriptionRID of the link. There is also a clear alert link and the message text reads When you are finished viewing this message, choose Clear Message. Clicking on Clear Message will clear the message from the Status page.

Alerts fall into three different categories depending on their severity and the urgency in which the user needs to address them.

Informational Alert
This alert informs the user about things in the system which need attention, but which are not an urgent matter, for example, an alert to set the system date and time.
Warning Alert
A warning alert means that the user needs to address the issue as soon as possible since this may affect the performance of the appliance in the future.
Critical Alert
The critical alert is the most severe type of alert. The user needs to address the issue immediately and remedy the situation or the system might not function correctly.


Resource Items

A resource item is the icon, text, and status information that takes one line under Resources on the Status page.

It can provide a link to a detail page that provides more information.

Related Topics


Resource Detail

A resource detail page can be an area pagelet accessed from the main status page or an area page accessed from the shutdown page. A resource detail page provides more detail about the resource. In the case of the chime sample application, the resource detail page provides the chime type, interval, and time to next chime. It also provides a button to chime now.

Related Topics


Help Pages

Help pages render when a user either clicks the Help tab or invokes context-sensitive Help by clicking the ? icon.

The following illustration shows the introductory Help page.

Introductory Help page

For more information about Help pages and to learn more about the main Help system, which allows for a localizable, extensible Table of Contents with support for localized Help pages, see Help System.


Extending the Web UI

View the following topics for specific implementation information about extending the Web UI.

Web Element Database

Creating a Task Object

Debugging Routines

Adding Your Logo to the Web UI

Raising and Displaying Alerts Overview

System Resources

Localization Framework

Help System


Web Element Database

Web elements and the Web Element Manager service form a container-based organization of Web user interface (UI) information. A Web element is a collection of properties needed to define a component of the Web UI. Web elements were created to provide a UI-oriented connection to dynamic system information and, in some cases, to allow extensions of the Web UI without editing Active Server Page (ASP) files.

Many of the Web UI pages are built using Web elements. For example, the major and minor navigation bar items are defined as Web elements; therefore, adding an additional major or minor tab to the system requires defining a new Web element. Similarly, each link on the navigation pages are individual Web elements, so adding or removing task links involves adding or removing Web elements. The sections below describe the details of defining Web elements and how they can be used.

Note

  • You must restart the Web Element Manager service before you can view any changes. At a command prompt, use the command net stop elementmgr to stop the Web Element Manager service, and then use the command net start elementmgr to restart it.

Related Topics


Registry Values

There are many different types of Web elements that can be stored in the Web element database; however, they all use the same basic parameters. The following table shows the different types of elements and their specific different requirements.

Value | Type | Description
ElementID | Key | Unique name for this element. The naming convention for this value is <container name><unique part>. Start with the container name and concatenate a string which will make a unique name.
BigGraphic | REG_SZ | The large graphic symbol used on the navigation pages.
CaptionRID | REG_SZ | Caption resource identifier.
Container | REG_SZ | Name of the container for this element.
ContextURL | REG_SZ | URL for the Help page associated with this item.
CopyrightRID | REG_SZ | Resource identifier for the copyright string.
DescriptionRID | REG_SZ | Description resource identifier.
ElementGraphic | REG_SZ | The small graphic symbol used on navigation pages.
IsEmbedded | DWORD | Flag which tells system to process the element as an embedded page. This should be zero (0) for most pages.
LocalUIMsgCode | DWORD | The message code passed to the local display driver.
LogDirectory | String | Absolute path to the log file directory.
Logfile | String | Two cases apply: Single file log–This value is the name of the log file. Multiple file log–A regular expression representing the template for finding files in the LogDirectory.
LongDescriptionRID | REG_SZ | Resource identifier for the long description used on navigation pages.
Merit | DWORD | Integer indicating sort order in container. 0=no sorting. Items with lower merit values will be displayed before items with higher merit values.
ObjectClass | REG_SZ | Optional. WMI class name. Reserved for future use.
ObjectKey | REG_SZ | Optional. WMI instance key. Reserved for future use.
PageType | REG_SZ | Specifies the page type required for specific navigation pages.
PropertiesURL | String | Relative path (from Web root) to the property page .asp file for this log.
Source | REG_SZ | Name of resource DLL that contains the resources for this item.
URL | REG_SZ | Relative path from the Web root to the file.
VersionRID | REG_SZ | Resource identifier for the version string.
WindowFeatures | REG_SZ | Sets parameters for window of new task.
ElementID
This value must be unique for all the Web elements. Some types of elements place other constraints on this value. The naming convention for this value is <container name><unique part>, that is, start with the container name and concatenate a string which will make a unique name.
BigGraphic
The large graphic symbol used on the navigation page for this element.
CaptionRID
This is the identifier of the resource from the source DLL that is the short name for this item. Depending on the type of element that is using this registry value, it displayed on the navigation bar and is the heading for the task on the associated navigation page. Required for all elements.
Container
This is the bucket to which this element belongs. When the Web Element Manager is queried with this name, the Web Element Manager will return this element and any others that have the same container value. Required for all elements.
ContextURL
URL for the Help page associated with this item.
CopyrightRID
This is the identifier of the resource from the source DLL that is the copyright string for this item.
DescriptionRID
This is the identifier of the resource from the source DLL that is the description for this item. Depending on the type of element that is using this registry value, it constitutes the body of the clickable task element on a major task page. Required for all elements, this value can be blank.
ElementGraphic
This is the path to the graphic symbol that will be displayed on a navigation page. Required for all elements, this value can be blank.
IsEmbedded
This value indicates that the page specified in the URL value should be executed using server.execute. This value is used for About box items. The value must be 0, unless otherwise specified. Required for all elements.
LocalUIMsgCode
This value is the message code passed to the local display driver. The meaning of each message code is described in the table:
Bit # | Message text | Description
All zeroes | No state information.
0 | Ready | Operating system is running.
1 | Shutting down | The server is shutting down.
2 | Network error | Simple networking service has detected a local area network (LAN) error that potentially stops client computer communication.
3 | Hardware error | A service has detected a fatal hardware error that potentially stops client computer communication.
4 | Checking disks | Autochk.exe or chkdsk.exe is running.
5 | Backing up disks | The Server Appliance Kit backup service is backing up user partition.
6 | Replace tape | The Server Appliance Kit backup service has detected that the tape needs to be replaced or inserted.
7 | Replace disk | The Server Appliance Kit backup service has detected that the disk needs to be replaced or inserted.
8 | Starting | The Server Appliance Kit Local UI framework component will call at startup with this code and bitmap.
9 | N/A | Wide area network (WAN) connected.
10 | N/A | WAN error – for example, no dial tone.
11 | N/A | Disk error – for example, dirty bit is set.
12 | Running additional tasks | Startup is taking longer because CHKDSK is running.
13 | General error | The system has encountered a problem that may affect its normal operation. Microsoft recommends that you check the local and Web UIs for detailed information about the problem.
14 – 31 | N/A | Reserved for future use by Microsoft.
LongDescriptionRID
This is the identifier of the resource from the source DLL that is the long description for this item. Depending on the type of element that is using this registry value, it is displayed as hover text on the taskbar, and for the clickable task element on the navigation page.
Merit
This determines the order in which the Web Element Manager returns this element. The lower the number, the closer it will be to the top of the list, that is, the closer it will be to the left end of the navigation bar. Required for all elements.
ObjectClass
Reserved.
ObjectKey
Reserved.
PageType
This value specifies the type of page the ASP page file in the URL requires. It can have the values shown in the table.
Value | Description
NORMAL Renders a page that does not require the FRAMESET value in the current window.

Navigation, area, and Object/Task Selector pages do not require the FRAMESET value.
FRAMESET Renders a page that does require the FRAMESET value in the current window.

Property, multitabbed property, and wizard pages all require the FRAMESET value.
NEW | Renders a non-FRAMESET value page in a new window.
Source
This is the name of the DLL that contains the resources needed by this element. Required for all elements.
URL
This is the URL path for the item. Each type of Web element uses the URL differently. See Adding a Web Task and the associated topics for adding each type of Web element for details about how each uses this value. Required for all elements.
VersionRID
This is the identifier of the resource from the source DLL that is the version string for this item.
WindowFeatures
This is for items that need a new window. It sets the window parameters.

Related Topics


Containers

The following table below shows the Web element container names that are defined by the Server Appliance Kit.

Container | Description
AboutBox | Contains information for items that appear in the About box.
AlertDefinitions | Contains information for each alert that can appear in the Alerts section of the main status page of the Web UI.
AlertDefinitions<AlertLog><AlertID> | Contains information about hyperlinks for a particular alert that can appear in the Web UI.
ContextHelp | Contains information needed to provide context-sensitive Help.
HelpTOC | Contains information about items that appear in the top level of the TABLE="100%" of Contents of the main Help system.
<HelpTOCItemID> | Contains information about items that appear in a nested level of the TABLE="100%" of Contents of the main Help system.
LocalUIAlertDefinitions | Contains information about hyperlinks for a particular alert that can appear in the local UI.
OEMLocalUILogo | Contains information about the item that appears in the OEM logo area of the Local UI.
LocalUIResource | Contains information about items that can appear in the system resource area of the local UI.
LocalUITask | Contains information about items that can appear in the tasks area of the local UI.
OemLogo | Contains information about the item that appears in the OEM logo area of the Web UI.
<PrimaryNavigationID> | Contains information about items that appear in the secondary navigation bar of the specified primary navigation bar item.
Resource | Contains information about the system resource items that appear in the Status section of the main status page of the Web UI.
ShutdownAlertDefinitions | Contains information for each alert that can appear in the Alerts section of the Shutdown page of the Web UI.
ShutdownAlertDefinitions<AlertLog><AlertID> | Contains information about hyperlinks for a particular alert that can appear on the Shutdown page of the Web UI.
ShutdownResource | Contains information about the system resource items that appear in the Status section of the Shutdown page of the Web UI.
Tabs | Contains information about items that appear on the primary navigation bar.
Tabs<Subcontainer> | Contains information about items that appear in the secondary navigation bar when a primary navigation bar item is selected.

Related Topics


Web Framework API Overview

The Microsoft Server Appliance software development kit (SDK) supports several standard Web page types that can be created using the Web framework application programming interface (API). Each of these Web pages is designed for a specific-use scenario. For example, the user maintenance page requires the ability to add user accounts, change the properties of existing user accounts, and remove user accounts. Adding user accounts and changing their properties requires prompted input pages, while removing a user account simply requires confirmation of the remove action. Each of these scenarios is supported.

Related Topics


Web Framework Events

Web developers write event handlers to respond to Web framework events, which are events that occur during the life cycle of a Web page. Web events include initialization, rendering, submitting or canceling changes, closing, and final cleanup.

The Web framework manages state transition through these events and provides callback notifications to the Web page to signal that a Web framework event has occurred.

Related Topics


Understanding Property Pages

The Server Appliance Kit SDK includes a robust Web framework that makes creating Web content simple and straightforward. To create Web content, Web developers use API code to create and show a Web page, and then implement event handlers that are automatically called by the Web framework. The following code sample shows a Hello World example for creating a property page.

<!-- #include virtual="/admin/inc_framework.asp"-- >
<%
Dim page
Call SA_CreatePage( "Basic Property Page", "", PT_PROPERTY, page )
Call SA_ShowPage ( page )

Public Function OnInitPage(ByRef oPageIn, ByRef oEventArg)
   OnInitPage = TRUE
End Function

Public Function OnPostBackPage(ByRef oPageIn, ByRef oEventArg)
   OnPostBackPage = TRUE
End Function

Public Function OnServePropertyPage(ByRef oPageIn, ByRef oEventArg)
   OnServePropertyPage = TRUE
   Call SA_ServeDefaultClientScript()
   Response.Write("Hello World, Microsoft &reg; Server Appliance style!")
End Function

Public Function OnSubmitPage(ByRef oPageIn, ByRef oEventArg)
   OnSubmitPage = TRUE
End Function

Public Function OnClosePage(ByRef oPageIn, ByRef oEventArg)
   OnClosePage = TRUE
End Function
%>

Lines 1-5 show the basic requirements for creating a property page while the remaining lines show the event handlers needed to support a property page.

The Server Appliance Kit Web framework routines are imported in line 1. This is the base include file needed in all Web pages. Lines 4-5 show the routines for creating and displaying a property page (PT_PROPERTY). For more information about the Web API reference see SA_CreatePage and SA_ShowPage.

The remaining lines of this example, lines 6-23, show the five basic event handlers that are needed for a property page. The Web framework automatically calls these event handlers as needed.

When a property page is first created the following several events occur:

  • The page is initialized (OnInitPage)
  • The page is sent to the client Web browser (OnServePropertyPage)
  • Once the page has been rendered in the client Web browser, the user can make changes and then either submit the changes or discard them. If the changes are accepted, the following several events occur on the Web page:
    1. The page is posted back to the Web server (OnPostBack)
    2. The page is presented for processing (OnSubmitPage)
    3. If the changes were successfully made, the page is closed (OnClosePage)
    4. Otherwise, the page is sent back to the client browser, with the errors indicated (OnServePage)
  • If the changes are not accepted, the page is then closed (OnClosePage)

Each of these distinct states is communicated to the page by way of an event, for which the Web programmer needs to write code.

The following diagrams show the lifecycle of a property page. In each of the diagrams, the Web programmer should provide the items in yellow.

Property Page Initialization

Process flow during property page initialization

Initialization of a property page starts when a user selects a hyperlink from a navigation page, navigation bar, Object/Task Selector, or area page. The hyperlink requests the ASP page which calls the SA_CreatePage and SA_ShowPage framework functions.

The framework will call the OnInitPage function, which must be provided by the ASP page. This function can be used to initialize items, for example, a session variable. If the call is successful, the framework will provide output for the framework portion of the HTML and JavaScript that is needed to display the page. This includes the status bar and navigation bars.

The framework will then call the OnServePropertyPage function. This function is responsible for outputting the HTML, including JavaScript, which will display the contents of the page. The framework will output the HTML and JavaScript needed for the footer buttons.

Once everything is loaded in the browser, the framework will call the JavaScript Init function, which must be provided. This function can be used to initialize items on the client.

Property Page–Cancel Button Clicked

Process flow after Cancel button is clicked

If the user clicks the Cancel button, the framework posts back to the ASP page, which, in turn calls the framework SA_CreatePage and SA_ShowPage functions. The framework will detect that the Cancel button was clicked and call the OnClosePage function, which must be provided by the ASP page. This function can be used to perform any cleanup needed. If the call is successful, the framework will output a redirect page, which will direct the browser to load the page from which this page was called.

Property Page–OK Button Clicked

Process flow after OK button is clicked

When the user clicks the OK button, the framework will call the JavaScript ValidatePage function, which must be provided. If there is a problem with the data the user entered, ValidatePage can call SA_DisplayErr to display an error message. If ValidatePage returns successfully, the framework will call the JavaScript SetData function, which must also be provided. SetData can transform and transfer data to hidden form variables.

The framework will then post back to the ASP page. The ASP page calls the framework SA_CreatePage and SA_ShowPage functions. Once the framework detects that the OK button was clicked, it calls the OnPostBackPage function, which must be provided by the ASP page. This function is responsible for extracting the configuration parameters from hidden and visible form values.

The framework will then call the OnSubmitPage function. This function is responsible for making the configuration changes that were requested. It can do this by calling a task using the Task Coordinator or it can make calls to WMI or COM objects directly. If the task is not successful or the input data are not valid, OnSubmitPage must call SA_SetErrMsg to set the error message for the user. To display a general-purpose message, OnSubmitPage can call SA_SetGenericMessage instead. The framework will then call OnServePropertyPage.

If OnSubmitPage is successful, the framework will call the OnClosePage function, which must be provided by the ASP page. This function can be used to perform any cleanup needed. If the call is successful, the framework will output a redirect page, which will tell the browser to load the page from which this page was called.


Understanding Tabbed Property Pages

Tabbed Property Page Initialization

Process flow during tabbed property page initialization

Initialization of a tabbed property page starts when a user selects a hyperlink from a navigation page, navigation bar, Object/Task Selector, or area page. The link requests the ASP page which in turn calls the framework SA_CreatePage and SA_ShowPage functions.

The framework will call the OnInitPage function, which must be provided by the ASP page. This function can be used to initialize items, for example, a session variable. If the call is successful, the framework will output the framework portion of the HTML and JavaScript needed to display the page. This includes the status bar and navigation bars.

The framework will then call the OnServeTabbedPropertyPage function for each tab of the page with an indication if the tab is visible. If the tab is visible, this function is responsible for outputting the HTML, including JavaScript, which will display the contents of the page. If the tab is not visible, the function must output the form fields in the hidden format. This allows the page to preserve pending configuration changes as the user moves from tab to tab. The framework will output the HTML and JavaScript needed for the buttons in the footer.

Once everything is loaded in the browser, the framework will call the JavaScript Init function, which must be provided. This can be used to initialize items on the client.

Tabbed Property Page–Tab Pressed

Process flow after Tab button is clicked

When the user clicks one of the tabs, the framework will call the JavaScript ValidatePage function, which must be provided. If there is a problem with the data the user entered, ValidatePage can call SA_DisplayErr to display an error message. If ValidatePage returns success, the framework will call the JavaScript SetData function, which must be provided. SetData can transform and transfer data to hidden form variables.

The framework will then post back to the ASP page. The ASP page calls the framework SA_CreatePage and SA_ShowPage functions. The framework will detect that a tab was clicked and call the OnPostBackPage function, which must be provided by the ASP page. This function is responsible for extracting the configuration parameters from form values, both hidden and visible.

The framework will then call the OnServeTabbedPropertyPage function for each tab of the page, with an indication if the tab is visible. If the tab is visible, this function is responsible for outputting the HTML, including JavaScript, which will display the contents of the page. If the tab is not visible, the function must output the form fields in the hidden format. This allows the page to preserve pending configuration changes as the user moves from tab to tab. The framework will output the HTML and JavaScript needed for the buttons in the footer.

Once everything is loaded in the browser, the framework will call the JavaScript Init function, which must be provided. This can be used to initialize items on the client.

Tabbed Property Page–Cancel Button Clicked

Process flow after Cancel button is clicked

If the user clicks the Cancel button, the framework posts back to the ASP page. The ASP page calls the framework SA_CreatePage and SA_ShowPage functions. The framework will detect that the Cancel button was clicked and call the OnClosePage function, which must be provided by the ASP page. This function can be used to perform any cleanup needed. If the call is successful, the framework will output a redirect page, which will tell the browser to load the page from which this page was called.

Tabbed Property Page–OK Button Clicked

Process flow after OK button is clicked

When the user clicks the OK button, the framework will call the JavaScript ValidatePage function, which must be provided. If there is a problem with the data the user entered, ValidatePage can call SA_DisplayErr to display an error message. If ValidatePage returns successfully, the framework will call the JavaScript SetData function, which must be provided. SetData can transform and transfer data to hidden form variables.

The framework will then post back to the ASP page. The ASP page calls the framework SA_CreatePage and SA_ShowPage functions. The framework will detect that the OK button was clicked and call the OnPostBackPage function, which must be provided by the ASP page. This function is responsible for extracting the configuration parameters from form values, both hidden and visible.

The framework will then call the OnSubmitPage function. This function is responsible for making the configuration changes that were requested. All changes are committed at the same time. The framework does not provide a mechanism for comitting chantes on a single tab. If you need to commit changes in a particular page, you should develop it as a standalone property page. It can do this by calling a task using the Task Coordinator or it can make calls to WMI or COM objects directly. If the task is not successful or the input data are not valid, OnSubmitPage must call SA_SetErrMsg to set the error message for the user. To display a general-purpose message, OnSubmitPage can call SA_SetGenericMessage instead. The framework will then call OnServeTabbedPropertyPage function for each tab of the page, with an indication if the tab is visible.

If OnSubmitPage is successful, the framework will call the OnClosePage function, which must be provided by the ASP page. This function can be used to perform any cleanup needed. If the call is successful, the framework will output a redirect page, which will tell the browser to load the page from which this one was called.


Understanding Wizard Pages

Wizard Page Initialization

Process flow during wizard-page initialization

Initialization of a wizard page occurs when a user selects a hyperlink from a navigation page, navigation bar, Object/Task Selector, or area page. The link requests the ASP page. The ASP page calls the framework SA_CreatePage and SA_ShowPage functions.

The framework will call the OnInitPage function, which must be provided by the ASP page. This function can be used to initialize items, for example, a session variable. If the call is successful, the framework will output the framework portion of the HTML and JavaScript needed to display the page. This includes the status bar and navigation bars.

The framework will then call the OnServeWizardPage function for each page of the wizard, with an indication if the page is visible. If the page is visible, this function is responsible for outputting the HTML, including JavaScript, which will display the contents of the page. If the page is not visible, the function must output the form fields in the hidden format. This allows the wizard to preserve pending configuration changes as the user moves from page to page. The framework will output the HTML and JavaScript needed for the buttons in the footer.

Once everything is loaded in the browser, the framework will call the JavaScript Init function, which must be provided. This can be used to initialize items on the client.

Wizard Page–Cancel Button Clicked

Process flow after Cancel button is clicked

If the user clicks the Cancel button, it posts back to the ASP page. The ASP page calls the framework SA_CreatePage and SA_ShowPage functions. The framework will detect that the Cancel button was clicked and call the OnClosePage function, which must be provided by the ASP page. This function can be used to perform any cleanup needed. If the call is successful, the framework will output a redirect page, which will tell the browser to load the page from which this page was called.

Wizard Page–Back Button Clicked

Process flow after Back button is clicked

When the user clicks the Back button, the framework will post back to the ASP page. The ASP page calls the framework SA_CreatePage and SA_ShowPage functions. The framework will detect that the Back button was clicked and call the OnPostBackPage function, which must be provided by the ASP page. This function is responsible for extracting the configuration parameters from form values, both hidden and visible.

The framework will call the OnWizardNextPage function, which must be provided, to determine which page should be visible.

The framework will then call the OnServeWizardPage function for each page of the wizard, with an indication if the page is visible. If the page is visible, this function is responsible for outputting the HTML, including JavaScript, which will display the contents of the page. If the page is not visible, the function must output the form fields in the hidden format. This allows the wizard to preserve pending configuration changes as the user moves from page to page. The framework will output the HTML and JavaScript needed for the buttons in the footer.

Once everything is loaded in the browser, the framework will call the JavaScript Init function, which must be provided. This can be used to initialize items on the client.

Wizard Page–Next Button Clicked

Process flow after Next button is clicked

When the user clicks the Next button, the framework will call the JavaScript ValidatePage function, which must be provided. If there is a problem with the data the user entered, ValidatePage can call SA_DisplayErr to display an error message. If ValidatePage returns success, the framework will call the JavaScript SetData function, which must be provided. SetData can transform and transfer data to hidden form variables.

The framework will then post back to the ASP page. The ASP page calls the framework SA_CreatePage and SA_ShowPage functions. The framework will detect that the Next button was clicked and call the OnPostBackPage function, which must be provided by the ASP page. This function is responsible for extracting all the configuration parameters from form values, both hidden and visible.

The framework will call the OnWizardNextPage function, which must be provided, to determine which page should be visible. The framework will call the OnServeWizardPage function for each page of the wizard, with an indication if the page is visible. The framework will output the HTML and JavaScript needed for the buttons in the footer.

Once everything is loaded in the browser, the framework will call the JavaScript Init function, which must be provided. This can be used to initialize items on the client.

Wizard Page – Finish Pressed

Process flow after Finish button is clicked

When the user clicks the Finish button, the framework will call the JavaScript ValidatePage function, which must be provided. If there is a problem with the data the user entered, ValidatePage can call SA_DisplayErr to display an error message and return FALSE. If ValidatePage returns TRUE, the framework will call the JavaScript SetData function, which must be provided. SetData can transform and transfer data to hidden form variables.

The framework will then post back to the ASP page which calls the framework SA_CreatePage and SA_ShowPage functions. The framework will detect that the Finish button was clicked and call the OnPostBackPage function, which must be provided by the ASP page. This function is responsible for extracting the configuration parameters from form values, both hidden and visible.

The framework will then call the OnSubmitPage function. This function is responsible for making the configuration changes that were requested. It can do this by calling a task using the Task Coordinator or it can make calls to WMI or COM objects directly. If the task is not successful or the input data is not valid, OnSubmitPage must call SA_SetErrMsg to set the error message for the user. To display a general-purpose message, OnSubmitPage can call SA_SetGenericMessage instead. The framework will then call OnServeWizardPage function for each page of the wizard, with an indication if the page is visible.

If OnSubmitPage is successful, the framework will call the OnClosePage function, which must be provided by the ASP page. This function can be used to perform any cleanup needed. If the call is successful, the framework will output a redirect page, which will tell the browser to load the page from which this page was called.


Understanding OTS and Area Pages

Server Appliance Kit

Understanding Object/Task Selector and Area Pages

Area Page Initialization

Process flow during area page initialization

Area page initialization starts when a user selects a hyperlink from a navigation page, navigation bar, Object/Task Selector, or area page. The hyperlink requests the ASP page. The ASP page calls the framework SA_CreatePage and SA_ShowPage functions.

The framework will call the OnInitPage function, which must be provided by the ASP page. This function can be used to initialize items, for example, a session variable. If the call is successful, the framework will output the framework portion of the HTML and JavaScript needed to display the page. This includes the status bar and navigation bars.

The framework will then call the OnServeAreaPage function. This function is responsible for outputting the HTML, including JavaScript, which will display the contents of the page. The framework will output the HTML and JavaScript needed for the Back button, if it is needed.

Once everything is loaded in the browser, the framework will call the JavaScript Init function, which must be provided. This can be used to initialize items on the client.

Object/Task Selector Area Page–Sort Request

Process flow following sort request

When the user clicks a column heading that supports sorting, the framework will call the framework JavaScript OTS_SubmitSort function.

The framework will then post back to the ASP page. The ASP page calls the framework SA_CreatePage and SA_ShowPage functions. The framework will detect that a sort was requested.

The framework will call the OnInitPage function, which must be provided by the ASP page. This function can be used to initialize items, for example, a session variable.

The framework will then call the OnSortNotify function, which must be provided by the ASP page. This function is responsible for sorting the data or setting the sort function in the Object/Task Selector.

If this page supports searching, the framework will call the OnSearchNotify function, which must be provided by the ASP page. This function is responsible for searching the data for the information requested. The built-in Object/Task Selector search algorithm is a "string1 contains string2" comparison. If you implement your own search mechanism and want to emulate the search functionality of Object/Task Selector, you should use this algorithm.

If this page supports virtual paging, the framework will call the OnPagingNotify function, which must be provided by the ASP page. This function is responsible for limiting the data to the virtual page requested. For tables that are very large, virtual paging allows each page to contain a subset of the complete table and provides UI navigation buttons to move between subsets of the table.

The framework will output the framework portion of the HTML and JavaScript needed to display the page. This includes the status bar and navigation bars.

The framework will then call the OnServeAreaPage function. This function is responsible for outputting the HTML, including JavaScript, which will display the contents of the page. The framework will output the HTML and JavaScript needed for the Back button, if it is needed.

Once everything is loaded in the browser, the framework will call the JavaScript Init function, which must be provided. This can be used to initialize items on the client.

Object/Task Selector Area Page–Search Request

Process flow following search request

When the user clicks the search Go button, the framework will call the framework JavaScript OTS_SubmitSearch function.

The framework will then post back to the ASP page. The ASP page calls the framework SA_CreatePage and SA_ShowPage functions. The framework will detect that a search was requested.

The framework will call the OnInitPage function, which must be provided by the ASP page. This function can be used to initialize items, for example, a session variable.

If this page supports sorting, the framework will call the OnSortNotify function, which must be provided by the ASP page. This function is responsible for sorting the data or setting the sort function in the Object/Task Selector.

The framework will call the OnSearchNotify function, which must be provided by the ASP page. This function is responsible for searching the data for the information requested.

If this page supports virtual paging, the framework will call the OnPagingNotify function, which must be provided by the ASP page. This function is responsible for limiting the data to the virtual page requested.

The framework will output the framework portion of the HTML and JavaScript needed to display the page. This includes the status bar and navigation bars.

The framework will then call the OnServeAreaPage function. This function is responsible for outputting the HTML, including JavaScript, which will display the contents of the page. The framework will output the HTML and JavaScript needed for the Back button, if it is needed.

Once everything is loaded in the browser, the framework will call the JavaScript Init function, which must be provided. This can be used to initialize items on the client.

Object/Task Selector Area Page–Virtual Page Request

Process flow following virtual page request

When the user clicks one of the PAGE UP or PAGE DOWN buttons, the framework will call the framework JavaScript OTS_SubmitPageChange function.

The framework will then post back to the ASP page. The ASP page calls the framework SA_CreatePage and SA_ShowPage functions. The framework will detect that a virtual page change was requested.

The framework will call the OnInitPage function, which must be provided by the ASP page. This function can be used to initialize items, for example, a session variable.

If this page supports sorting, the framework will call the OnSortNotify function, which must be provided by the ASP page. This function is responsible for sorting the data or setting the sort function in the Object/Task Selector.

If this page supports sorting, the framework will call the OnSortNotify function, which must be provided by the ASP page. This function is responsible for sorting the data or setting the sort function in the Object/Task Selector.

The framework will call the OnPagingNotify function, which must be provided by the ASP page. This function is responsible for limiting the data to the virtual page requested.

The framework will output the framework portion of the HTML and JavaScript needed to display the page. This includes the status bar and navigation bars.

The framework will then call the OnServeAreaPage function. This function is responsible for outputting the HTML, including JavaScript, which will display the contents of the page. The framework will output the HTML and JavaScript needed for the Back button if it is needed.

Once everything is loaded in the browser, the framework will call the JavaScript Init function, which must be provided. This can be used to initialize items on the client.


Debugging

The Server Appliance Kit provides debugging functions that can help you isolate and correct errors in your code. To use these functions, copy inc_debug.asp from \SDK\webui\debug\ on the Server Appliance Kit CD-ROM to %windir%\system32\ServerAppliance\web\admin on the computer where you are developing your Web UI add-in, replacing the version that already exists in that folder. You can then use these functions in your code at appropriate locations to help you isolate and diagnose errors.

Important

  • The version of inc_debug.asp located on the SAK CD-ROM is intended to be used only to debug program code. It should not be installed on end-customers' computers.

The following table lists the functions you can use to debug your code.

Function | Description
SA_IsDebugEnabled | Determines whether debugging is enabled.
SA_TraceOut | Writes debugging information to the HTML stream or to a log file.
SA_TraceErrorOut | Writes debugging information to the HTML stream or to a log file. The information is prefixed with the string "ISSUE:".

To make full use of these functions, you must set values for registry entries in the following location:
HKEY_LOCAL_MACHINE\Software\Microsoft\ServerAppliance\WebFramework

The following table shows the debugging registry entries available to help you locate any errors or bugs.

Value | Type | Description | Example
Debug DWORD Enables debugging so the framework stops processing the ASP page if an error occurs. An error is indicated when the properties of the Err object have been set.
Value | Meaning
0 | Disable debugging
1 | Enable debugging
 1
TraceOption DWORD Specifies where trace information is sent.
Value | Meaning
0 | No output
1 | Output to HTML stream
2 | Output to trace log file
3 | Output to HTML stream and trace log file
 2
TraceFile | REG_SZ | Absolute full path of the trace log file. The path must exist. | %temp%\SAWebFramework.log

Important

  • Set these registry values only on computers being used to develop and debug a Web UI add-in. They should not be set on end-customers' computers.


Adding a Web Task

A Web task is a property page or wizard that is part of the Web UI. A Web task displays a full-screen window which allows the user to enter configuration data and then to either commit or cancel the changes. A property sheet displays OK and Cancel buttons while a wizard displays Back, Next, Cancel, and Finish buttons.

Creating a Web task requires that you complete the following three steps:

  1. Optional: Create a task object.
  2. Optional: Add a task to the Appliance Manager.
  3. Create one of the following types of ASP pages:
    • Property Page
    • Multitabbed Property Page
    • Wizard Page
  4. Add the task to a navigation page.


Creating a Task Object

In order to perform a task, one or more COM objects must be implemented. Each of these task objects must implement the IApplianceTask interface as described in the appliancetask.idl file. These task objects are registered and their PROGIDs are listed in the TaskExecuTABLE="100%"s value for the registry entry of this task. This registry entry is described in the Task Definition Elements section of the Adding a Task to the Appliance Manager topic. Task objects are executed in the order that they are listed.

The following functions must also be implemented in order to perform a task: lApplianceTask::OnTaskComplete, lTaskContext::SaveParameters, lTaskContext::RestoreParameters, lTaskContext::Clone, and lTaskContext::RemoveParameter. The developer also needs to look at the chime sample application for an example on how to create a task object.

Web property, tabbed property, and wizard pages call the ExecuteTask function, in the context of SA_ExecuteTask (TaskName, bExecuteAsync, TaskContext). Set TaskName to the task name as entered in the registry and bExecuteAsync the flag indicating whether the task should be executing asynchronously. These functions set up the task context object with the correct name value pairs by using the hidden form values collected in the task. A task can check the task context object to get return results from the server appliance tasks.

The task coordinator reads the registry to get the list of task objects for a given task name. The task coordinator invokes each task object by calling the IApplianceTask::OnTaskExecute method and then passes a handle to the task context object. Each object calls the ITaskContext::GetParameters method to get input parameters passed down from the task by using the handle passed by the task coordinator. The task objects call the ITaskContext::SetParameters method to send return values back to the task. The ITaskContext interface is specified in the taskctx.idl file.

To debug server appliance tasks, it is helpful to isolate problems in the front-end task from the back-end task COM objects.

Related Topics


Adding a Task to the Appliance Manager

This section describes the step-by-step procedure for creating an appliance task and associated task objects by adding a task to the Appliance Manager. Task definitions are stored in the registry beneath the HKLM\Software\Microsoft\ServerAppliance\ApplianceManager\ObjectManagers\Microsoft_SA_Task\<MyTaskKey> registry key.

Task Definition Elements

The following table describes the key and the various values that comprise a task definition.

Value | Type | Description | Example
MyTaskKey | Key | Unique string identifying a task. | ChimeTask
TaskName | String | Name of the task. | ChimeTask
CanDisable | DWORD | If set to 1, then this task can be disabled. | 0x0
IsEnabled | DWORD | If set to 1, then this task is enabled and will be run. If set to 0 and CanDisable is set to 1, then this task will not be run. | 0x1
IsSingleton | DWORD | Optional. For asynchronous tasks, if this value is set to 1, then only a single instance of this task will be run at any given time. If this value is set to 1 while there is an instance of the task executing, and if something else tries to execute the same task, the second instance of the task will fail with the E_FAIL error code. | 0x0
RestartAction | DWORD | Optional. If set to 1, then this task will be automatically restarted if the operating system is restarted before the task is complete. If this value name is not present, or if it is set to 0x0, then the task will not be restarted automatically. | 0x0
TaskExecuTABLE="100%"s | String | List of PROGIDs, delimited by a space. One entry per task COM object. | ChimeTask.CChimeTask.1


Code Examples

The following topics provide code examples for each of the page types listed.

Creating Web Task ASP Pages for a Property Page

Creating Web Task ASP Pages for a Multitabbed Property Page

Creating Web Task ASP Pages for a Wizard Page

Chime Sample Application


Creating Web Task ASP for a Property Page

Server Appliance Kit

Creating Web Task ASP Pages for a Property Page

To create the ASP page for a property page, complete the following steps.

  1. Include the library file. The following code sample shows how to do this.
    <!-- #include virtual="/admin/inc_framework.asp" -->
  2. Call the library function to create the page and display it. The following code sample shows how to do this.
    Dim retCode
Dim page
'
' Create a property page. Note that L_PAGE_TITLE and myImage
' are initialized elsewhere
retCode = SA_CreatePage(L_PAGE_TITLE, myImage, PT_PROPERTY, page)
If (retCode <> gc_ERR_SUCCESS) Then
' Handle error
End If
' show the page, which will allow the framework to call the
' needed event handlers
retCode = SA_ShowPage(page)
If (retCode <> gc_ERR_SUCCESS) Then
' Handle error
End If
  3. Provide the OnInitPage event to perform any initialization needed. The following code sample shows how to do this.
    Public Function OnInitPage(ByRef PageIn, ByRef EventArgIn)
' Begin initialization here
OnInitPage = True 'indicates success
End Function
  4. Provide the OnServePropertyPage event to supply output to the actual page. The following code sample shows how to do this.
    Public Function OnServePropertyPage(ByRef PageIn, ByRef EventArgIn)
' Provide code to output the page
' Make sure to define the Init() SetData()
' and ValidatePage() functions
%>
<script language='JavaScript' src='/admin/inc_global.js'>
</script>
<script language='JavaScript'>
function Init()
{ // do any initialization needed }
function SetData()
{ // modify hidden form fields if needed }
function ValidatePage()
{ // verify that the entered data is okay }
</script>
<%
OnServePropertyPage = True 'indicates success
End Function
  5. Provide the OnSubmitPage event to perform the requested task. The following code sample shows how to do this.
    Public Function OnSubmitPage(ByRef PageIn, ByRef EventArgIn)
' Provide code to process the action
' Can call WMI directly or call a backend task
OnSubmitPage = True 'indicates success
End Function
  6. Provide the OnPostBackPage event to extract the configuration data from the form variables. The following code sample shows how to do this.
    Public Function OnPostBackPage(ByRef PageIn, ByRef EventArgIn)
' Provide code to save the state of the page
OnPostBackPage = True 'indicates success
End Function
  7. Provide the OnClosePage event to perform needed cleanup. The following code sample shows how to do this.
    Public Function OnClosePage(ByRef PageIn, ByRef EventArgIn)
' Provide code to process the action
' Can call WMI directly or call a back-end task
OnClosePage = True 'indicates success
End Function

Related Topics


Creating Web Task ASP for a Multitabbed Property Page

Server Appliance Kit

Creating Web Task ASP Page for a Multitabbed Property Page

To create the ASP page for a multitabbed property page, you must complete the following steps.

  1. Include the library file:
    <!-- #include virtual="/admin/inc_framework.asp" -->
  2. Call the library function to create the page and show it:
    Dim retCode
Dim page
'
' Create a tabbed property page. Note that L_PAGE_TITLE and myImage
' are initialized elsewhere
retCode = SA_CreatePage(L_PAGE_TITLE, myImage, PT_TABBED, page)
If (retCode <> gc_ERR_SUCCESS) Then
' Handle error
End If
' add as many tabs as needed
retCode = SA_AddTabPage(page, L_TAB_TITLE, idTab)
If (retCode <> gc_ERR_SUCCESS) Then
' Handle error
End If

' show the page, which will allow the framework to call the
' needed event handlers
retCode = SA_ShowPage(page)
If (retCode <> gc_ERR_SUCCESS) Then
' Handle error
End If
  3. Provide the OnInitPage event function to perform any initialization needed:
    Public Function OnInitPage(ByRef PageIn, ByRef EventArgIn)
' Do initialization here
OnInitPage = True 'indicates success
End Function
  4. Provide the OnServeTabbedPropertyPage event function to output the actual page:
    Public Function OnServeTabbedPropertyPage(ByRef PageIn,
                                          ByVal iTab,
                                          ByVal bIsVisible,
                                          ByRef EventArgIn)
' Provide code to output the content for the requested tab
Select Case iTab
     Case idTab
          'provide code to ouput this tab
'output should be different
          'if the page is visible
     Case Else
          'handle error
End Select
OnServeTabbedPropetyPage = True 'indicates success
End Function
  5. Provide the OnSubmitPage event function to perform the requested task:
    Public Function OnSubmitPage(ByRef PageIn, ByRef EventArgIn)
' Provide code to process the action
' Can call WMI directly or call a back-end task
OnSubmitPage = True 'indicates success
End Function
  6. Provide the OnPostBackPage event function to extract the configuration data from the form variables:
    Public Function OnPostBackPage(ByRef PageIn, ByRef EventArgIn)
' Provide code to save the state of the page
OnPostBackPage = True 'indicates success
End Function
  7. Provide the OnClosePage event function to perform any cleanup needed:
    Public Function OnClosePage(ByRef PageIn, ByRef EventArgIn)
' Provide code to process the action
' Can call WMI directly or call a back-end task
OnClosePage = True 'indicates success
End Function

Related Topics


Creating Web Task ASP for a Wizard Page

Server Appliance Kit

Creating Web Task ASP Pages for a Wizard Page

To create the ASP page for a wizard page, you must complete the following steps.

  1. Include the library file:
    <!-- #include virtual="/admin/inc_framework.asp" -->
  2. Call the library function to create the page and show it:
    Dim retCode
Dim page
'
' Create a tabbed property page. Note that L_PAGE_TITLE and myImage
' are initialized elsewhere
' myImage should be an array to provide the small image for the
' title bar and the large image for the start and finish pages
retCode = SA_CreatePage(L_PAGE_TITLE, myImage, PT_WIZARD, page)

' add as many pages as needed note L_ strings defined elsewhere
retCode = SA_AddWizardPage(page, L_WIZ_INTRO_PAGE_TITLE, idIntro)
retCode = SA_AddWizardPage(page, L_WIZ_PAGE_TITLE, idPage)
retCode = SA_AddWizardPage(page, L_WIZ_FINISH_PAGE_TITLE, idFinish)

' show the page, which will allow the framework to call the
' needed event handlers
retCode = SA_ShowPage(page)
  3. Provide the OnInitPage event function to perform any initialization needed:
    Public Function OnInitPage(ByRef PageIn, ByRef EventArgIn)
' Do initialization here
OnInitPage = True 'indicates success
End Function
  4. Provide the OnServeWizardPage event function to output the actual page:
    Public Function OnServeWizardPage(ByRef PageIn,
                                  ByVal iPageID,
                                  ByVal bIsVisible,
                                  ByRef EventArgIn)
' Provide code to output the content for the requested page
Select Case iPageID
     Case idIntro
          'provide code to ouput this page
'output should be different
          'if the page is visible
     Case idPage
          'provide code to ouput this page
     Case idFinish
          'provide code to ouput this page
Case Else
          'handle error
End Select
OnServeWizardPage = True 'indicates success
End Function
  5. Provide the OnWizardNextPage event function to determine the navigation sequence:
    Public Function OnWizardNextPage(ByRef PageIn,
                                  ByRef EventArgIn,
                                  ByVal iCurrentPageID,
                                  ByVal iPageAction,
                                  ByRef iNextPageID,
                                  ByRef iPageType)
 ' Provide code to determine the next page
Select Case iCurrentPageID
     Case idIntro
          'bassed on the page action determine the next page
'set iNextPageID and iPageType
     Case idPage
          'bassed on the page action determine the next page
     Case idFinish
          'bassed on the page action determine the next page
Case Else
          'handle error
End Select
OnWizardNextPage = True 'indicates success
End Function
  6. Provide the OnSubmitPage event function to perform the requested task:
    Public Function OnSubmitPage(ByRef PageIn, ByRef EventArgIn)
' Provide code to process the action
' Can call WMI directly or call a back-end task
OnSubmitPage = True 'indicates success
End Function
  7. Provide the OnPostBackPage event function to extract the configuration data from the form variables:
    Public Function OnPostBackPage(ByRef PageIn, ByRef EventArgIn)
' Provide code to save the state of the page
OnPostBackPage = True 'indicates success
End Function
  8. Provide the OnClosePage event function to perform any cleanup needed:
    Public Function OnClosePage(ByRef PageIn, ByRef EventArgIn)
' Provide code to process the action
' Can call WMI directly or call a back-end task
OnClosePage = True 'indicates success
End Function

Related Topics


Chime Sample Application

The chime sample application demonstrates many features of the Microsoft Server Appliance Kit. By examining the source code for the Chime application, you can see how you can do the following:

  • Implement primary and secondary navigation pages
  • Implement a property page
  • Implement a tabbed property page
  • Implement series of wizard pages
  • Add a resource item and detailed status information to a status page

To install the sample application

  1. Insert the Microsoft Server Applicance Kit CD into the CD drive.
  2. Run d:\sdk\chime\installchime.cmd, where d is the drive letter of the CD drive.

To view the sample application

  • Open the Web site https://localhost:8098 using your browser.

Notes

  • The WBEM provider in the sample application, chimeprov.cpp, requires the fwcommon.h file to be compiled. This file can be obtained by installing the WMI SDK, which is available at this Microsoft Web site. (http://www.microsoft.com/)
  • The Chime sample application builds debug versions of its dynamic-link libraries (DLLs). The debug versions will not function on a system that does not contain msvcrtd.dll. This is not a problem on development systems.

To uninstall the sample application

  1. Insert the Microsoft Server Applicance Kit CD into the CD drive.
  2. Run d:\sdk\chime\uninstallchime.cmd


Adding a Web Task to a Navigation Page

The navigation page contains the following pieces of information:

  • Information, which describes the section's function and how to use the page.
  • Tasks section, which lists the tasks belonging to the major tab.

A Web task is a property page or wizard that is part of the Web UI. A Web task displays a full-screen window which allows the user to enter configuration data and then to either commit or cancel the changes.

When an item is added to the secondary navigation bar, the item becomes a link to a page.

For more information about adding an item to a secondary navigation bar, see Adding a New Secondary Navigation Item.


Adding Your Logo to the Web UI

You can add your company logo or other identifying graphic to the Web UI of your server appliance by following the steps below. The graphic should be approximately 50 pixels high and in Graphics Interchange Format (GIF). If the graphic is greater than 50 pixels high, the branding/status bar will expand to accommodate the height of the graphic. If the graphic is less than 50 pixels high, the graphic will be displayed against the default background color. If your graphic is significantly more than 200

To add your logo

  1. In the registry key path HKEY_LOCAL_MACHINE, add the Software\Microsoft\ServerAppliance\ElementManager\WebElementDefinitions\<Unique Element ID> registry key.
  2. In the added registry key, enter the values as shown in the following table.

    Web Element Values

    Value | Type | Description | Example
    ElementID | Key | Unique string identifying an element. | OemLogoChime
    CaptionRID | String | Caption resource identifier. It is required, but does not need to be populated. | <empty>
    Container | String | Container name is OemLogo. | OemLogo
    DescriptionRID | String | Description resource identifier. It is required, but does not need to be populated. | <empty>
    ElementGraphic | String | Complete Web path to graphic file for OEM logo. | chime/images/OemLogoChime.gif
    IsEmbedded | DWORD | Process as embedded page. It is always 0x0. | 0x0
    Merit | DWORD | Integer indicating sort order in container (0=no sorting). | 0x1
    Source | String | Name of resource DLL. It is required, but does not need to be populated. | <empty>
    URL | String | Type the URL for your Web site. When the user clicks the logo, the browser will navigate to this Web site. | <empty>

Notes

  • If the server appliance is a Windows Storage Server 2003 device, you can also include your logo on the Web Shares home page. For more information, see “Customizing the Web Shares Home Page” in the OEM Preinstallation Kit.
  • For more information about code examples for adding an OEM logo, see Chime Sample Application.


Raising and Displaying Alerts Overview

Raising Alerts

Alerts are raised using the Server Appliance Manager service. The Server Appliance Manager service then creates a new instance of the Microsoft_SA_Alert class in the WMI. The following diagram shows this process.

Process flow for raising an alert

Related Topics


Adding an Alert to the Web Element Database

You can add custom messages, which can be displayed on the main status page of the Web UI.

To add custom messages to the main status page

  1. Add one Web element for each unique message.
  2. Use unique AlertLog and AlertID values in your Web element definition to define custom messages.

    One convention is to use the resource DLL name for the AlertLog value, and the CaptionRID value of the alert for the AlertID. A better convention is to use a unique string that is meaningful for the AlertLog and a number for the AlertID. For example, the framework uses ShutdownPending for AlertLog and 1 for AlertID for the shutdown pending alert.

    3. Note

    • The AlertLog and AlertID values in the Web element definition must match the values used when raising the alert. To provide the text displayed for the alert, default viewer maps the caption and description resource identifiers to the alert.
  3. Add the Web element definitions for the alert under the HKLM\Software\Microsoft\ServerAppliance\ElementManager\WebElementDefinitions registry key.

The following table illustrates such a Web element.

Value | Type | Description | Example
ElementID | Key | Concatenation of "AlertDefinitions"<AlertLog> and <AlertID> | AlertDefinitionsSampleResource.dll4C000004
CaptionRID | String | Resource identifier for the text of the alert link | 4C000004
Container | String | Alert container | AlertDefinitions
DescriptionRID | String | Resource identifier for the text to display on the alert details page | 4C000008
ElementGraphic | String | Not applicable | <empty>
IsEmbedded | DWORD | Instruction to process element as an embedded page | 0x0
Merit | DWORD | Not applicable | 0x0
Source | String | Name of resource DLL | SampleResource.dll
URL | String | Must be empty to indicate that the default alert view must be used | <empty>

The string identified by CaptionRID should not contain HTML tags because these tags will be sent unaltered in alert e-mail.

Requirements

  • The Element identifier must be the string concatenation of the string AlertDefinitions and the AlertLog and AlertID values.
  • The Container value must be AlertDefinitions.
  • The CaptionRID value must contain the resource identifier of the string that is the text for the link.
  • The DescriptionRID value must contain a more detailed description of the message.
  • The URL value must be empty to indicate that the default message view must be used.

Related Topics


Adding a Shutdown Alert to the Web Element Database

You can add custom messages to be displayed on the Shutdown status page of the Web UI.

To add custom messages to the Shutdown status page

  1. Add one Web element for each unique message.
  2. Use unique AlertLog and AlertID values in your Web element definition to define custom messages.

    One convention is to use the resource DLL name for the AlertLog value, and the CaptionRID value of the alert for the AlertID.

    3. Note

    • The AlertLog and AlertID values in the Web element definition must match the values used when raising the alert. To provide the text displayed for the alert, default viewer maps the caption and description resource identifiers to the alert.
  3. Add the Web element definitions for the alert under the HKLM\Software\Microsoft\ServerAppliance\ElementManager\WebElementDefinitions registry key.

The following table illustrates such a Web element.

Value | Type | Description | Example
ElementID | Key | Concatenation of "ShutdownAlertDefinitions"<AlertLog> and <AlertID> | ShutdownAlertDefinitionsChimeResource.dll4C000004
CaptionRID | String | Resource identifier for the text of the alert link | 4C000004
Container | String | Alert container | ShutdownAlertDefinitions
DescriptionRID | String | Resource identifier for the text to display on the alert details page | 4C000008
ElementGraphic | String | Not applicable | <empty>
IsEmbedded | DWORD | Instruction to process element as an embedded page | 0x0
Merit | DWORD | Not applicable | 0x0
Source | String | Name of resource DLL | ChimeResource.dll
URL | String | Must be empty to indicate that the default message view must be used | <empty>

Requirements

  • The Element identifier must be the string concatenation of the string Shutdown Alert Definitions and the AlertLog and AlertID values.
  • The Container value must be ShutdownAlertDefinitions.
  • The CaptionRID value must contain the resource identifier of the string that is the text for the link.
  • The DescriptionRID value must contain a more detailed description of the message.
  • The URL value must be empty to indicate that the default message view must be used.

Related Topics


Extending an Alert with Hyperlinks

You can add one or more user action links to an alert. These user actions appear in the alert area page or pagelet, which is accessed by clicking an alert link on the Status page. A user action provides a link to a related configuration page, which is usually a task.

Add one Web element for each user action associated with an alert as the following screenshot shows.

Sample status page showing alerts

The following list describes each part of the Web element definition:

  • ElementID. For readability, you must use the alert name concatenated with the user action identifier. If there is more than one user action, use the alert name concatenated with UserActionXX, where XX is the number of the link.
  • Container. All user action elements for a given alert will have the same Container value, which is ElementID of the alert. For more information, see Adding an Alert to the Web Element Database.
  • CaptionRID. This value binds a resource identifier to a string, and the string is then used as the link text.
  • DescriptionRID. This value binds a resource identifier to a string, and the string is then used as the link hover text.
  • URL. This value supplies the location of the user action.
  • Merit. This value is used to determine the order of display.

Add the Web element definitions for the alert under the HKLM\Software\Microsoft\ServerAppliance\ElementManager\WebElementDefinitions ElementManager service key.

The following table shows a sample Web element for such an alert.

Value | Type | Description | Example
ElementID | Key | Unique key name. You must follow the naming convention of <container name><unique part>. | AlertDefinitionsSampleResource.dll4C000004UA
CaptionRID | String | Resource identifier for link text | 4C000010
Container | String | ElementID of alert definition | AlertDefinitionsSampleResource.dll4C000004
DescriptionRID | String | Resource identifier for link hover text. | <4C000014>
ElementGraphic | String | Not used | <empty>
IsEmbedded | DWORD | Not used | 0x0
Merit | DWORD | Display order | 0x1
Source | String | Path to resource DLL | sampleresource.dll
URL | String | Page to display when link is clicked | chime/prop_chime_config.asp

The following screenshot shows the alert detail for the Date and time not set up alert after the link has been clicked.

Alert detail for Date and time not set up


Raising and Displaying Alerts

You can raise and display alerts on both status pages and the local UI.

To raise and display an alert

  1. Add element definitions for the alert under the HKLM\Software\Microsoft\ServerAppliance\ElementManager\WebElementDefinitions registry key.

    You must create one definition per alert for each display location. If you want the same alert to appear on the Web UI main status page, the Shutdown status page, and the local UI, you must create three definitions.

  2. Use the IApplianceServices::RaiseAlert method to raise the alert, as described in the appsrvcs.idl file. This file is located in the \SDK\Chime\Idl folder on the Server Appliance Kit 3.0 CD-ROM.

    The following table lists the arguments in the order in which they are to be passed and describes each one.

    Argument | Description
    AlertType This is one of the SA_ALERT_TYPE values as defined in appsrvcs.idl.
    • SA_ALERT_TYPE_ATTENTION is used to indicate some information is available.
    • SA_ALERT_TYPE_MALFUNCTION is used to indicate a warning.
    • SA_ALERT_TYPE_FAILURE is used to indicate a critical error.
    AlertID | The identifier for the alert. This is used along with the AlertLog value to uniquely identify the alert. There must be a corresponding entry under the ElementManager registry key for the alert to be displayed.
    AlertLog | The text string used to help identify the alert. Past convention used the name of the resource file that contains the resource strings for the alert.
    AlertSource | Obsolete. This is the name of the subkey under HKLM\Software\Microsoft\ServerAppliance\LocalDisplayManager\Resources. This value must be VT_EMPTY.
    TimeToLive | This determines the length of time, in milliseconds (ms), that the alert must exist. If an alert does not time out, this value must be SA_ALERT_DURATION_ETERNAL, as defined in appsrvcs.idl.
    ReplacementStrings | These are strings that can be plugged into the message obtained from the resource DLL. If the message does not take any replacement strings, this value must be set to VT_EMPTY. For more information, see the appsrvcs.idl file.
    RawData | This is for any additional date that might be needed. This value must be set to VT_EMPTY if no additional data is needed. For more information, see the appsrvcs.idl file.
    Cookie | This is the return value identifying which alert is raised.

To clear an alert

  • Use the cookie obtained on RaiseAlert to call the IApplianceServices::ClearAlert method.
    /* This function uses the cookie obtained on RaiseAlert to clear the alert. */
HRESULT lApplianceServices::ClearAlert ([in] LONG lAlertCookie)

    lAlertCookie is the alert cookie returned by the RaiseAlert() function.

  • Alternatively, all alerts with a given Alert ID and Alert Log can be cleared by calling the lApplianceServices::ClearAlertAll method.
    /* This function clears all alerts with a given Alert ID and Alert Log. */
HRESULT lApplianceServices::ClearAlert ( [in] LONG lAlertID, [in] BSTR bstrAlertLog )

    lAlertID is the ID of the alert to clear, and bstrAlertLog is the alert log where the alert resides.

If a call fails, or the alert does not appear, you can use the following procedure to debug the problem.

To debug an alert

  1. If the RaiseAlert call fails, check the HRESULT returned as described in the WMI software development kit (SDK). To view the SDK, see this Microsoft Web site. (http://www.microsoft.com/)
  2. If the call succeeds, but no alert can be seen on the LCD or browser, try using the WBEMTEST tool that ships with the WMI SDK. To find the WBEMTEST tool, see this Microsoft Web site. (http://www.microsoft.com/)

To use the WBEMTEST tool

  1. Start WBEMTEST.
  2. Connect to ROOT\CIMV2.
  3. Select the Enum_Instances button.
  4. Enter Microsoft_SA_Alert for the superclass name.

    If you can see alerts, it means the alerts are being generated but the registry keys are incorrect.

    Note

    • It is important that the application developer creates a Web UI alert definition for every alert that can be raised. This means that every alert that appears on the shutdown page and the local UI needs to also appear on the main status page of the Web UI.

Defining the Replacement Strings

When you raise an alert, you pass in an array of strings for the varReplacementStrings parameter. When the alert is displayed, the strings that were passed in to the alert replace the %n strings in the order specified in the message.

The following code sample shows how replacement strings are used.

// Constants
const long TIME_TO_LIVE=30000      // in milliseconds

// Declare variables
DWORD      dwAlertType = SA_ALERT_TYPE_ATTENTION;
DWORD      dwAlertId = SA_SAMPLEAPP_CHIME_CHIME_ALERT; // from the resource dll header file
_bstr_t      bstrAlertLog(RESOURCE_DLL_NAME);
_bstr_t      bstrAlertSource(L"");
_variant_t   varReplacementStrings;
_variant_t   varRawData;
LONG       lCookie;

HRESULT    hrRet=S_OK;

// Initalize the varReplacementStrings variant.
VariantInit(&varReplacementStrings);

// Create the SAFEARRAY.
SAFEARRAY *psa;
V_ARRAY(&varReplacementStrings) = SafeArrayCreateVector(VT_BSTR, 0, 1);
psa=V_ARRAY(&varReplacementStrings); //initialize the psa pointer

if (psa == NULL)
{
   // error handling here...
}

// Set the type.
V_VT(&varReplacementStrings) = VT_ARRAY | VT_BSTR;

// Lock the array data.
BSTR *pData;
hrRet = SafeArrayAccessData(psa, (void**)&pData);

if (FAILED(hrRet))
{
      // error handling here...
}

// Pass a string into the variant structure
pData[0]=SysAllocString(L"Value1");

// Call RaiseAlert
hrRet = pAppSrvcs->RaiseAlert(dwAlertType,
            dwAlertId,
            bstrAlertLog,
            bstrAlertSource,
            TIME_TO_LIVE,
            &varReplacementStrings,
            &varRawData,
            &lCookie);

In this example, the AlertDefinition caption of Chime %1 would become Chime Value1.

SA_GetLocString works similarly in regards to replacement strings. An additional advantage of replacement strings is that a localizer can change the string to match the word order of a different language.

Raising and Clearing an Alert from an ASP Page

The following sample code demonstrates how to raise an alert from an ASP page. To view the alert, you an alert definition that matches the AlertLog and AlertID used when raising the alert.

Call TestAlerts()

Public Function TestAlerts()
   On Error Resume Next
   Err.Clear

   Const SA_ALERT_CLASS = "Microsoft_SA_Resource"
   Const SA_ALERT_DURATION_ETERNAL = 2147483647

   Const SA_ALERT_TYPE_WARNING = 0
   Const SA_ALERT_TYPE_FAILURE = 1
   Const SA_ALERT_TYPE_INFORMATION = 2

   Const SA_ALERT_NORMAL = 0
   Const SA_ALERT_SINGLETON = 1

   Const AUTOLANGCONFIG_LOG = "AutoLangConfig"
   Const AUTOLANGCONFIG_ALERT_RestartRequired = 1

   Dim oAppServices
   Dim rawData
   Dim nullRepStrings
   Dim idCookie

   '
   ' Create Appliance Services object
   '
   Set oAppServices = CreateObject("Appsrvcs.ApplianceServices")
   If Err.Number <> 0 Then
       ' Object was not created; handle appropriately
       Exit Function
   End If

   '
   ' Initialize it
   '
   oAppServices.Initialize()
   If Err.Number <> 0 Then
       ' Initialization failed; handle appropriately
       Exit Function
   End If

   '
   ' Check to see if the alert is present
   '
   bIsPresent = oAppServices.IsAlertPresent(AUTOLANGCONFIG_ALERT_RestartRequired, AUTOLANGCONFIG_LOG)
   If ( Err.Number <> 0 ) Then
      ' Unexpected error; handle appropriately
   Else
      ' Alert is present; handle appropriately
   End If

   '
   ' Raise Singleton Alert
   '
   idCookie = oAppServices.RaiseAlertEx(SA_ALERT_TYPE_WARNING, _
               AUTOLANGCONFIG_ALERT_RestartRequired, _
               AUTOLANGCONFIG_LOG, _
               SA_ALERT_CLASS, _
               SA_ALERT_DURATION_ETERNAL, _
               nullRepStrings, _
               rawData, _
               SA_ALERT_SINGLETON)
   If ( Err.Number <> 0 ) Then
      ' Unexpected error; handle appropriately
   Else
      If ( idCookie <> 0 ) Then
         ' Alert was successfully raised; handle appropriately
      Else
         ' Alert already existed; handle appropriately
      End If
   End If

   '
   ' Clear the alert
   '
   Call oAppServices.ClearAlertAll(AUTOLANGCONFIG_ALERT_RestartRequired, AUTOLANGCONFIG_LOG)
   If ( Err.Number <> 0 ) Then
      ' Unexpected error; handle appropriately
   Else
      ' Alert was cleared successfully; handle appropriately
   End If

   oAppServices.Shutdown()
   oAppServices = Nothing
End Function


Raising Alerts from Event Log Entries

Server Appliance Kit

Raising and Clearing Alerts from Event Log Entries

If the original equipment manufacturer (OEM) includes a pre-existing application on the server appliance, it may be useful to map the event log entries of that application to server appliance alerts for display on the Web UI or the local display to bring important events to the attention of the server administrator when those events happen. You can do this using Event Filter provided by the Server Appliance Kit. Event Filter is a WMI event provider that receives a notification from WMI whenever a new Windows Server 2003 event is created. Event Filter determines whether the event is of interest and, if so, creates a corresponding Microsoft_SA_Alert WMI object. The administrator can specify whether a Windows Server 2003 event is of interest by setting registry key values in HKLM\Software\Microsoft\ServerAppliance\EventFilter\Events.

The table below describes the registry key and the values that comprise an event definition.

Value | Type | Description | Example
UniqueID | Key | Unique string identifying an event. | Backup
AbsoluteEventId | DWORD | Optional subject to the following conditions:. The registry key must contain values either in AbsoluteEventId, or in both EventID and EventType. If both AbsoluteEventID and EventID are specified, AbsoluteEventID is used. AbsoluteEventID is the 32-bit value which, along with the EventSource, uniquely identifies the event. In the absence of this value, EventID (the 16-bit value available in the Event Log) is used, but the value in the Event Log does not completely identify an event. | 0x1f40
AddEventStrings | DWORD | When this value is set to 1, the strings from the specified event description are appended to the string specified by the ReplacementStrings of the IApplianceServices::RaiseAlert method that is used to raise the alert. | 1
AlertID | DWORD | Required. Identifier of the Microsoft_SA_Alert object to be generated. | 0x1
AlertLog | String | Required. Identifies the log of the alert. | Backup
AlertSource | String | Always Microsoft_SA_Resource. | Microsoft_SA_Resource
AlertType | String | Optional. AlertType can have the following values: Information, Error, and Warning. If AlertType is not specified, the EventType is used as the AlertType. | Information
ClearAlert | DWORD | Optional. Set to 1 to clear the alert specified by AlertID and AlertLog. Otherwise, omit or set to 0 to raise the alert. | 0
EventId | DWORD | Optional, subject to the following conditions: The registry key must contain values either in AbsoluteEventId, or in both EventID and EventType. If both AbsoluteEventID and EventID are specified, then AbsoluteEventID is used. EventID is the 16-bit identifier that appears in the Event Log viewer. If EventID is specified, the correct EventType of the event must also be specified. | 0x1f40
EventSource | String | Required. Name of the process generating the event, which is used to uniquely identify the event. | ntbackup
EventType | String | Optional, subject to the following conditions: The registry key must contain values either in AbsoluteEventId, or in EventID and EventType. EventType specifies the type of the event and can be the following values: Information, Error, and Warning. | Information
TimeToLive | DWORD | Optional. The time, in milliseconds, that the alert will be displayed. The alert will not clear automatically if TimeToLive is not set. | 0x0001e25f

For example, the following registry entries raise an alert when the UPS driver detects that system power has failed. This example uses AbsoluteEventID to identify the event.

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ServerAppliance\EventFilter\Events\UPSPowerFailed]
"EventSource"="UPS"
"AlertID"=dword:00000001
"AlertLog"="UPS"
"AlertType"="Warning"
"AbsoluteEventID"=dword:00000c9e
"AddEventStrings"=dword:00000001
"TimeToLive"=dword:0001e25f

When an event occurs and an alert has been raised, the alert can be cleared when another event happens. To do this, create another registry key for the same alert, that is, HKLM\Software\Microsoft\ServerAppliance\EventFilter\Events\UniqueID. This key specifies the event that should occur to clear the alert, and it has the ClearEvent value set to 1.

For example, the following registry entries raise and clear an alert when a restore operation begins and ends, respectively. This example uses EventID and EventType to identify the events.

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ServerAppliance\EventFilter\Events\Restore]
"AlertID"=dword:00000001
"AlertLog"="Restore"
"AlertSource"="Microsoft_SA_Resource"
"AlertType"="Information"
"EventID"=dword:00001f42
"EventSource"="ntbackup"
"EventType"="Information"
"TimeToLive"=dword:0001e25f
"ClearAlert"=dword:00000000

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ServerAppliance\EventFilter\Events\RestoreClear]
"AlertID"=dword:00000001
"AlertLog"="Restore"
"AlertSource"="Microsoft_SA_Resource"
"AlertType"="Information"
"EventID"=dword:00001f43
"EventSource"="ntbackup"
"EventType"="Information"
"TimeToLive"=dword:0001e25f
"ClearAlert"=dword:00000001

Note that the values in the two registry keys are identical except for the event identifiers and the value of ClearAlert.


Alert Updates

The server appliance alert feature has been enhanced with the following capabilities.

Ability to Raise a Singleton Alert

The Server Appliance Kit has the capability to specify that only one instance of an alert can be present in the system. Any attempt to raise the same alert again will fail. The new method lApplianceServices::RaiseAlertEx can be used for this purpose. The SA_ALERT_FLAG_SINGLETON value is included in the lAlertFlags value.

HRESULT lApplianceServices::RaiseAlertEx (
/*[in]*/  LONG  lAlertType,
/*[in]*/  LONG  lAlertId,
/*[in]*/  BSTR  bstrAlertLog,
/*[in]*/  BSTR  bstrAlertSource,
/*[in]*/  LONG  lTimeToLive,
/*[in]*/  VARIANT*  pReplacementStrings,
/*[in]*/  VARIANT*  pRawData,
/*[in]*/  LONG  lAlertFlags,
/*[out, retval]*/  LONG*  pAlertCookie
);
typedef enum SA_ALERT_FLAGS {
SA_ALERT_FLAG_NONE = 0x0;
SA_ALERT_FLAG_SINGLETON = 0x1;
SA_ALERT_FLAG_PERSISTENT = 0x2
}  SA_ALERT_FLAGS;

A return value of S_FALSE signifies that an alert with this identifier exists.

Ability to Check if an Alert Exists

This capability will allow a component to take appropriate action when an alert exists in the system. Also, a component might decide not to raise a duplicate alert when one already exists. This can also be achieved by trying to raise a Singleton alert.

The following method syntax on the lApplianceServices interface allows a component to check the existence of an alert.

HRESULT lApplianceServices::IsAlertPresent (
/*[in]*/  LONG  lAlertId,
/*[in]*/  BSTR  bstrAlertLog
/*[out, retval]*/  VARIANT_BOOL  *pvbPresent
);

Ability to Raise a Persistent Alert

This extended capability will allow the server appliance to persist alerts across reboots. The lApplianceServices::RaiseAlertEx method can be used for raising a persistent alert by including the SA_ALERT_FLAG_PERSISTENT value to the lAlertFlags argument.

A persistent alert can be cleared through the existing lApplianceServices::ClearAlert call. If the component generating the alert does not save the alert cookie across reboots, then the lApplianceServices::ClearAlertAll method can be used to clear the alert using the alert identifier and alert log. This method will clear all the alerts with the specified alert identifier and alert log from the system.

Only one persistent alert, specified by the alert log and alert type, can exist in the system at a time. If another persistent alert of the same type is raised, the earlier alert is no longer persistent.


System Resources

System resources refer to the resources of the server appliance. A resource is a system service or component for which you wish to display status data, for example, open files and disk space. System resources can be displayed on the main status page or on the Shutdown status page. If the resource has extended status information, you can provide a hyperlink.

Related Topics


Adding a Resource to the Status or Shutdown Page

Add the Web element definitions for system resources under the HKLM\Software\Microsoft\ServerAppliance\ElementManager\WebElementDefinitions registry key.

The following table shows the Web element defined for the chime resource.

Value | Type | Description | Example
ElementID | Key | Unique string identifying the element. You must follow the naming convention of <container name><unique part>. | ResourceChime
CaptionRID | String | Caption resource identifier. Required but does not need to be populated. | <empty>
Container | String | Container name is Resource for the main status page, and ShutdownResource for the Shutdown status page. | Resource
DescriptionRID | String | Description resource identifier. Required but does not need to be populated. | <empty>
ElementGraphic | String | Resource icon. Required but does not need to be populated. | <empty>
IsEmbedded | DWORD | Instruction to process element as an embedded page. It is always 0x0. | 0x0
Merit | DWORD | Integer indicating display order in container. 0=no sorting. | 0x1
Source | String | Name of resource DLL. Required but does not need to be populated. | <empty>
URL | String | Active Server Page to be executed | chime/chime_resource/asp

For more information about code examples of adding a resource, see Chime Sample Application.


Creating Resource ASP

Server Appliance Kit

Creating Resource ASP Pages

The following sample code shows how to create a resource in an ASP page.

<%@ Language=VBScript   %>
<%   Option Explicit    %>
<!-- #include virtual="/admin/inc_framework.asp" -->
<%
   Call ServeMemoryStatus()

Private Function ServeMemoryStatus()
   on error resume next
   Dim objLocator
   Dim objNameSpace
   Dim oProvider
   Dim L_CAPTION_TEXT
   Dim L_HOVER_TEXT
   Dim L_UNITOFMEASURE_TEXT
   Dim MEMORY_RESOURCE_IMAGE

   L_CAPTION_TEXT = "Physical memory available"
   L_UNITOFMEASURE_TEXT = " (Kb)"
   L_HOVER_TEXT = "This shows how much physical memory is currently available on the appliance."
   MEMORY_RESOURCE_IMAGE = ""

   Set objLocator = Server.CreateObject("WbemScripting.SWbemLocator")
   If ( Err.Number <> 0 ) Then
      ' Handle error here
   End If

   Set objNameSpace = objLocator.ConnectServer(".","root\CIMV2")
   If ( Err.Number <> 0 ) Then
      ' Handle error here
   End If

   Set oProvider = objNameSpace.Get("Win32_PerfRawData_PerfOS_Memory")
   Set oProvider = oProvider.Instances_
   If ( Err.Number <> 0 ) Then
      ' Handle error here
   End If

   Dim oSystem
   Dim sURL

   sURL = "sample/resources/sh_resource_memory_details.asp"

   For each oSystem in oProvider
      Dim sMemory
      sMemory = CStr(oSystem.AvailableKBytes) + L_UNITOFMEASURE_TEXT

      Call SA_ServeResourceStatus(MEMORY_RESOURCE_IMAGE, L_CAPTION_TEXT, L_HOVER_TEXT, sURL, SA_DEFAULT,  sMemory)
   Next

End Function
%>


Creating Resource Detail ASP

Server Appliance Kit

Creating Resource Detail ASP Pages

The following code sample shows how to create resource details in an ASP page.

<%@ Language=VBScript   %>
<%   Option Explicit    %>
<%
   '-------------------------------------------------------------------
   ' Memory Resource Details Pagelet
    '------------------------------------------------------------------
%>
<!-- #include virtual="/admin/inc_framework.asp" -->
<%
   Dim page

   Call SA_CreatePage("Memory Status Details", "", PT_PAGELET, page)
   Call SA_ShowPage(page)

   Public Function OnInitPage(ByRef Page, ByRef Reserved)
      OnInitPage = TRUE
   End Function

   Public Function OnServePageletPage(ByRef Page, ByRef Reserved)
      OnServePageletPage = TRUE

      Call ServeCommonElements()
      Call ServeMemoryDetails()

   End Function

Private Function ServeMemoryDetails()
   on error resume next
   Dim objLocator
   Dim objNameSpace
   Dim oProvider

   Dim L_COMMITTED
   Dim L_COMMIT_USED
   Dim L_COMMIT_LIMIT

   L_COMMIT_USED = "Committed Total:"
   L_COMMIT_LIMIT = "Committed Limit:"

   Set objLocator = Server.CreateObject("WbemScripting.SWbemLocator")
   If ( Err.Number <> 0 ) Then
      ' Handle error here
      Exit Function
   End If

   Set objNameSpace = objLocator.ConnectServer(".","root\CIMV2")
   If ( Err.Number <> 0 ) Then
      ' Handle error here
      Exit Function
   End If

   Set oProvider = objNameSpace.Get("Win32_PerfRawData_PerfOS_Memory")
   Set oProvider = oProvider.Instances_
   If ( Err.Number <> 0 ) Then
      ' Handle error here
      Exit Function
   End If

   Dim oSystem

   WriteLine("<table border='0' cellspacing='0' cellpadding='0' >")
   For each oSystem in oProvider

      WriteLine("<tr>")
      WriteLine("<td class='TasksBody' nowrap>"+L_COMMIT_USED+"</td>")
      WriteLine("<td class='TasksBody' nowrap>"+CStr(Round( (oSystem.CommittedBytes / 1024), 1))+"</td>")
      WriteLine("<td class='TasksBody' nowrap>"+" (Kb) </td>")
      WriteLine("</tr>")

      WriteLine("<tr>")
      WriteLine("<td class='TasksBody' nowrap>"+L_COMMIT_LIMIT+"</td>")
      WriteLine("<td class='TasksBody' nowrap>"+CStr(Round( (oSystem.CommitLimit / 1024), 1))+"</td>")
      WriteLine("<td class='TasksBody' nowrap>"+" (Kb) </td>")
      WriteLine("</tr>")
   Next
   WriteLine("</table>")

End Function

   Private Function ServeCommonElements()
%>
<script language='JavaScript'>
function Init()
{
}
</script>
<%
   End Function

   Private Function WriteLine(ByRef sLine)
      Response.Write(sLine + vbCrLf)
   End Function
%>


Help System

The main Help system allows for a localizable, extensive table of contents that support localized Help pages. The features include the ability for the OEM developers to add to the context-sensitive Help, extend the Help table of contents, and create their own content pages.

Related Topics


Content Pages

The content pages are the Help pages created by the OEM developer using HTML or ASP pages. These pages are rendered in the Help pane and are also used in the context-sensitive Help section.

You can create a Help page as you would create any HTML or ASP page. Use the appropriate HTML tags to format your content according to the way you want to present it.

The following code example is a very simple content page written in HTML.

<HTML>
<HEAD>
<TITLE>New Help Page</TITLE>
<SCRIPT SRC="linkcss.js"></SCRIPT>
</HEAD>
<BODY TOPMARGIN="0">
<H1>Insert heading here</H1>
<P>Insert introduction here.</P>
<P><B>Procedure</B></P>
<OL type="1">
   <LI>This is step 1.</LI>
   <LI>This is step 2.</LI>
   <LI>This is step 3.</LI>
</OL>

<P class=indent><B>Note</B> This is an important message.</P>
</BODY>
</HTML>

The sample Help content page can be added to the Help table of contents or context-sensitive Help by following the instructions and example outlined in Adding to the Help Table of Contents or Adding to the Context-Sensitive Help.

For more information about making changes to the context-sensitive Help, see Adding to the Context-Sensitive Help. For more information about making changes to the table of contents, see Adding to the Help Table of Contents.


Main Table of Contents

The main table of contents in the Help system displays the list of topics and subtopics found in the Help system.

Each topic or subtopic present in the table of contents has a Help page associated with it. The Help page contains more information about a specific feature and can also contain various information, such as procedures on how to accomplish certain tasks, sample codes, debugging information, and links to related topics.

For more information about Help pages, see Help Pages. For more information about the Help system, see Help System.


Adding to the Help Table of Contents

The extensible table of contents will allow the application developers to create their own help pages and add these to the main Help table of contents. Application developers need to set the appropriate registry keys and create their own content pages to add to the table of contents.

The table of contents entries are stored in the Web Element Manager database. The top-level items are the Web elements in the container HelpTOC. Each Web element can either be a book or a page. Books can contain other books or pages. The text or title that appears with the added book or page is derived from the CaptionRID value of the Web elements in the container. The framework will determine whether the Web element is either a book or a page. The URL value is the location of the Help page to display relative to the localized Help directory. DescriptionRID is not used but it is required. The ElementGraphic value is also required but not used. URL needs to correspond to whatever the name of the HTML or ASP page file is that the OEM wants to be added to the Help table of contents. For an example of this see Content Pages.

First level Help pages are entries that have Container=HelpTOC. Second level entries have Container=<ElementID of one of the above items with Container=HelpTOC>. Third level entries have Container=<ElementID of second level entry>.

For example, Maintenance has an entry in the registry as the following table shows.

HKEY_LOCAL_MACHINE\Software\Microsoft\ServerAppliance\ElementManager\WebElementDefinitions

Value | Type | Description | Example
ElementID | Key | Unique key name. You must follow the naming convention of <container name><unique part>. | HelpTOCMaintenance
CaptionRID | String | Resource identifier for link text. | 0x40200190
Container | String | HelpTOC to create a first level Help page. <ElementID of one of the above items with Container=HelpTOC> to create a second level Help page. <ElementID of second level entry> to create a third level Help page. | HelpTOC
DescriptionRID | String | Not used, but required. | <empty>
ElementGraphic | String | Not used, but required. | <empty>
IsEmbedded | DWORD | Flag which tells the system to process the element as an embedded page. This should be zero (0). | 0
Merit | DWORD | Display order. | 0x900
Source | String | Path to resource DLL. | Sacoremsg.dll
URL | String | Page to display when the link is clicked. | _maintenance_maintenance.htm

HelpTOCMaintenance is the name of the registry that corresponds to Maintenance. When creating a new registry key, make sure that it is unique.

Note

  • The convention to follow when naming a new registry key is <Container Name><Unique Part>, where <Unique Part> would be related to the English text for the caption. For example, the element identifier for Getting Started would be HelpTOCGettingStarted.

The following is a list of the top-level books where you can add your own Help page or book and the corresponding heading that appears in the online Help table of contents:

  • HelpTOCServerAppliance–Web User Interface
  • HelpTOCNetwork–Network Setup
  • HelpTOCDiskVol–Disks and Volumes
  • HelpTOCUsers–Users and Groups
  • HelpTOCShares–Folders and Shares
  • HelpTOCMaintenance-Maintenance

During development, once the new registry key has been added, the application developer needs to complete a few steps before they can view their new Help page in the Help table of contents. The Web Element Manager service needs to be restarted and this can be done in one of the following two ways:

  • Through the command line, by first stopping the service and then restarting it.
    Net stop elementmgr
Net start elementmgr
  • Or, the application developers can reboot their system.

For more information about content pages, see Content Pages.


Adding to the Context Sensitive Help

Server Appliance Kit

Adding to the Context-Sensitive Help

The extensible table of contents will allow application developers to create their own Help pages and add these to the main Help table of contents. You need to set the appropriate registry keys and create your own content pages to add to the table of contents.

Context-sensitive Help provides more information about some of the features available in the system. It can include links to other Help topics related to that feature or it can contain information that pertains to that particular feature.

The Context-sensitive Help entries are stored in the Web Element Manager database. Each context-sensitive Help entry has a unique registry key name associated with it. You can add your own context-sensitive Help entries to provide your customers the information related to the new feature or component they have developed.

To extend context-sensitive Help so that you can add your own context-sensitive Help page, you need to add a new registry key under HKEY_LOCAL_MACHINE\Software\Microsoft\ServerAppliance\ElementManager\WebElementDefinitions and create an HTML or ASP page file saved in %systemroot%\system32\serverappliance\web\help3\0409, where 0409 corresponds to English.

The following table shows the registry values that are needed to create a new context-sensitive Help entry.

Value | Type | Description | Example
ElementID | Key | Unique key name. You must follow the naming convention of <container name><unique part>. | ContextHelpDateTime
CaptionRID | String | Not used, but required. | <empty>
Container | String | This should be equal to ContextHelp. | ContextHelp
ContextURL | String | URL for the Help page associated with this item. | util/sh_datetime.asp
DescriptionRID | String | Not used, but required. | <empty>
ElementGraphic | String | Not used, but required. | <empty>
IsEmbedded | DWORD | Flag that tells the system to process the element as an embedded page. This should be zero (0). | 0
Merit | DWORD | Display order. This should be set to one (1). | 1
Source | String | Path to resource DLL. | datetimemsg.dll
URL | String | Page to display when the link is clicked. | _datetime_date_and_time.html

ContextHelpDateTime is the name of the registry key. DateTime in ContextHelpDateTime makes the registry key easily distinguishable from the other registry keys associated with context-sensitive Help, for example, ContextHelpXXXX. So, if you want to create a new feature called New Feature and provide context-sensitive Help for it, the registry key can be named ContextHelpNewFeature. ContextHelp<name> must be unique.

Container=ContextHelp says that this registry key is associated with context-sensitive Help.

URL=_datetime_date_and_time.htm specifies the name of the HTML file that is rendered when a user searches for the Date and Time context-sensitive Help . The file contains information about the Date and Time feature. For a New Feature, the HTML or ASP page file that contains more information about New Feature can be named newfeature.htm or newfeature.asp. For more information about creating the content page, see Adding Content Pages.

ContextURL specifies the URL for which this item is the Help page.

During development, once the new registry key has been added, you still have some remaining steps before you can view your new Help page in the Help's table of contents. The Web Element Manager service needs to be restarted. You can do this using one of the following two methods.

  • Through the command line, by first stopping, then restarting the service. The following code sample shows how to do this.
    Net stop elementmgr
Net start elementmgr
  • Or, you can reboot your system.

Related Topics


Adding Logs

The Logs container features insert a secondary navigation bar item entitled Logs under the Maintenance primary navigation bar item on the server appliance Web UI. The Logs tab links to a navigation page which displays a link to each log that is available on the server appliance. Each log's link will typically lead to either an area page – if it is a single file, simple text log – or to an to an Object/Task Selector page if it is a multifile log or is not a simple text file. The Object/Task Selector page will lead to an area page for the selected log file. The area page allows the user to view the log, clear it, download it, or change the logging properties.

Each entry into the Logs page is defined by an element in the TabsMaintenanceLogs container. These entries are made in the registry under the HKLM\Software\Microsoft\ServerAppliance\ElementManager\WebElementDefinitions registry key.

The following table shows the possible values for the Logs page.

Value | Type | Description | Example
ElementID | Key | Unique identifier for this log. Must start with TabsMaintenanceLogs and have <LogName> added. | TabsMaintenanceLogsWebAdministration
Container | String | TabsMaintenanceLogs | TabsMaintenaceLogs
CaptionRID | String | Caption resource identifier for the display name of the log. | 0x40450009
DescriptionRID | String | Resource identifier for the description of the log | 0x4045000A
Source | String | Name of the resource DLL for this log. | salogs.dll
URL | String | Relative path (from Web root) to the area page file or Object/Task Selector page file for this log element. | If using the generic log area or Object/Task Selector pages, these will be Logs/Single_Log_Details.asp?logtitle=<ElementID> -Or- Logs/Multiple_Log_Details.asp?MultiSelect=1 & Title=<ElementID>.
ElementGraphic | String | Icon for this log. |
Merit | DWORD | Integer indicating sort order in the container | Order logs appear in the list (0=no sorting)
IsEmbedded | DWORD | 0 (Do not process as embedded page) |
PropertiesURL | String | Relative path (from Web root) to the property page asp file for this log. Optional. |
DirectoryPath | String | Absolute path to the log file directory. | %systemroot%\system32\LogFiles\W3SVC1
FileName | String | Two cases apply: Single file log–This value is the name of the log file. Multiple file log–A regular expression representing the template for finding files in the DirectoryPath. | * is all files ex*.log is all files that start with the characters ex and end with .log

The display name for the log is found in the resource DLL using the CaptionRID and the description is found in the resource DLL using the DescriptionRID. The link to the properties page for a given log is found in the PropertiesURL field. If PropertiesURL is empty, then the Properties button will not appear on the area page and the Properties task should not appear on the Object/Task Selector page.


Adding a Navigation Page

You can add new primary and secondary navigation pages. See the following topics for implementation details.

Related Topics


Adding a New Primary Navigation Page

You can add a new item to the primary navigation bar – and the page which it invokes – of your server appliance by using the following process.

To add a new primary navigation page

  1. In the path HKEY_LOCAL_MACHINE, add the Software\Microsoft\ServerAppliance\ElementManager\WebElementDefinition\Tabs<Unique Element ID> registry key.
  2. In this new key, enter the values as shown in the following table.
    Value | Type | Description | Example
    Element ID | Key | Unique name for this element. Must start with Tabs. | TabsChime
    BigGraphic | String | Path to the large graphic item to display. This is only needed if this item is also a navigation page. | Chime\images\chimeX192.gif
    CaptionRID | String | Resource identifier for the text to display on the primary navigation bar. | 4C00000C
    Container | String | Container name is always Tabs. | Tabs
    DescriptionRID | String | Resource identifier for the text to display when the mouse hovers over this item on the navigation bar. | 4C000010
    ElementGraphic | String | Resource icon. Required, but does not need to be populated. | Chime\images\chimeX32.gif
    IsEmbedded | DWORD | Instruction to process element as an embedded page. Always 0x0 | 0x0
    LongDescriptionRID | String | Resource identifier for the text to display on the associated navigation page. | <4C000010>
    Merit | DWORD | Integer indicating display order in container. 0=no sorting. | 0x1
    PageType | String | Specifies the required page type. | NORMAL
    Source | String | Name of the resource DLL. | sampleresource.dll
    URL | String | Primary navigation bar items usually use tasks.asp since they are normally navigation pages. | tasks.asp
  3. Add secondary navigation pages for each of the links.
  4. Make sure to use the ElementID specified in Step 1 as the Container name for each of the links.

The Merit value controls the sorting for Web elements. Set the Merit value to the desired position of the new item. For example, a value of 0x1 will make this Web element the first, or furthest to the left, item on the primary navigation bar.

Note

  • The Merit value of 1 and 2 are reserved for Welcome and Status, respectively. You must use a value less than 700 so that Maintenance and Help get the two locations furthest to the right.

Related Topics


Adding a New Secondary Navigation Item

You can add a new item to the secondary navigation bar – and the page which it invokes – of your server appliance by using the following process.

To add a new secondary navigation item

  1. In the path HKEY_LOCAL_MACHINE, add the Software\Microsoft\ServerAppliance\ElementManager\WebElementDefinition\<Container Name><Unique Element ID> registry key.
  2. In this new key, enter the values as shown in the following table.
    Value | Type | Description | Example
    Element ID | Key | Unique name for this element. Must start <container name>. | TabsChimeSettingsProp
    BigGraphic | String | Path to the large graphic item to display if the page referenced by the URL is a navigation page. | <blank>
    CaptionRID | String | Resource identifier for the text to display on the secondary navigation bar. This is also displayed as the link on the primary navigation page that contains this item. | 4C000011
    Container | String | Container name is the ElementID of the primary navigation page for which this is a secondary navigation item. | TabsChime
    DescriptionRID | String | Resource identifier for the hover text to display on the secondary navigation bar. It is also displayed as the description of the link on the associated primary navigation page. | 4C000014
    ElementGraphic | String | Resource icon. Required, but can be blank. Displayed on the primary navigation page that contains this item. | Chime/images/chimeX32.gif
    IsEmbedded | DWORD | Instruction to process element as an embedded page. Always 0x0 | 0x0
    LongDescriptionRID | String | Resource identifier for the hover text to display on the navigation page which contains this item. | <empty>
    Merit | DWORD | Integer indicating display order in container. 0=no sorting. Items are sorted in ascending order according to this value. | 0x1
    PageType String Specifies the required page type.

    FRAMESET for property, multitabbed property, and wizard pages.

    NORMAL for navigation, area, and Object/Task Selector (OTS) pages.

             FRAMESET
    Source | String | Name of the resource DLL. | sampleresource.dll
    URL | String | Path to the ASP page file that will display the desired page. | Chime/prop_chime_config.asp
  3. Create the ASP page file to which the URL item points.

The Merit value controls the sorting for Web elements. Set the Merit value to the desired position of the new item. For example, a value of 0x1 will make this Web element the first, or furthest to the left, item on the primary navigation bar.

Related Topics


Adding a Custom Navigation Page

You can add a navigation page that is not an item on the primary navigation bar to your server appliance by using the following process.

To add a new custom navigation page

  1. In the path HKEY_LOCAL_MACHINE, add the Software\Microsoft\ServerAppliance\ElementManager\WebElementDefinition\<Container Name><Unique Element ID> registry key.
  2. In this new key, enter the values as shown in the following table.
    Value | Type | Description | Example
    Element ID | Key | Unique name for this element. Must start with <container name> | TabsMaintenaceLogs
    BigGraphic | String | Path to the large graphic item to display if the page referenced by the URL is a navigation page. Required. | <blank>
    CaptionRID | String | Resource identifier for the text to display as the title on this navigation page. This is also displayed as the link on the parent navigation page if there is one. | 40450007
    Container | String | Container name is the ElementID of the navigation page which contains the link to this navigation page. | TabsMaintenance
    DescriptionRID | String | Resource identifier that is displayed as the description text on the parent navigation page if there is one. | 40450008
    ElementGraphic | String | Resource icon that is displayed on the parent navigation page if there is one. | images/green_arrow.gif
    IsEmbedded | DWORD | Instruction to process element as an embedded page. Always 0x0 | 0x0
    LongDescriptionRID | String | Resource identifier that is displayed as the description on this navigation page. | 40450008
    Merit | DWORD | Integer indicating display order in container. 0=no sorting. Items are sorted in ascending order according to this value. | 0x8
    PageType | String | Specifies the required page type. | NORMAL
    Source | String | Name of the resource DLL. | salogs.dll
    URL String Custom navigation pages always use tasks.asp and require two parameters. MultiTab is the container for this element. Container is the ElementID of this element. It is called container because it is the container for the items that are displayed on this navigation page. tasks.asp?MultiTab=
    TabsMaintenance&Container=
    TabsMaintenanceLogs

Related Topics


Adding a New Object Task Selector Page

Server Appliance Kit

Adding a New Object/Task Selector Page

Before you add a new Object/Task Selector page, determine the type of Object/Task Selector you want to use and the features you want to enable. You can create a single-selection Object/Task Selector that presents the list of objects as a set of option buttons (also known as radio buttons) so the user can select only one object at a time, or you can create a multiple-selection Object/Task Selector that presents the objects as a set of check boxes, giving the user the option to select more than one item in the list. You can also create Object/Task Selectors so that the user can search and sort the list of objects and navigate through lists that are too long to fit within the Object/Task Selector pane.

Related Topics


Sample ASP for an Object Task Selector Page (1)

Server Appliance Kit

Sample ASP Page for an Object/Task Selector Page (1)

The following code example shows a sample ASP page for a basic Object/Task Selector page.

<%@ Language=VBScript   %>
<%   Option Explicit    %>
<%
   '---------------------------------------------------------------------
   ' OTS Area Page Template
    '--------------------------------------------------------------------
%>
<!--   Framework include file path is two levels up relative to this sample
      which is <WebRoot>/sample/ots
---------------------------------------------------------------------->
<!--   #include virtual="/admin/inc_framework.asp"                -->
<!--    #include virtual="/admin/ots_main.asp"                      -->
<%
   '-------------------------------------------------------------------
   ' Global Constants
   '-------------------------------------------------------------------
   Dim SOURCE_FILE
   SOURCE_FILE = SA_GetScriptFileName()

   '--------------------------------------------------------------------
   ' Global Variables
   '--------------------------------------------------------------------

   '======================================================
   '
   '             E N T R Y   P O I N T
   '
   ' The following few lines implement the mainline entry point for this Web Page.
   ' Basically we create an Area page (PT_AREA) and then ask the Web Framework
   ' to start processing events for this page.
   '
   '======================================================
   Dim L_PAGETITLE
   Dim page

   L_PAGETITLE = "Basic Example"

   '
   ' Create Page
   Call SA_CreatePage( L_PAGETITLE, "images/users_32x32.gif", PT_AREA, page )

   '
   ' Show page
   Call SA_ShowPage( page )

   '======================================================
   '
   '             E V E N T   H A N D L E R S
   '
   ' All of the public functions that follow implement event handler functions that
   ' are called by the Web framework in response to state changes on this Web
   ' page.
   '
   '======================================================

   '-------------------------------------------------------------------
   ' Function:   OnInitPage
   '
   ' Synopsis:   Called to signal first time processing for this page. Use this method
   '         to do first time initialization tasks.
   '
   ' Arguments: [in] oPageIn Page on which this event has been fired.
   '           [in] oEventArg Event argument for this event.
   '
   ' Returns:   Always returns TRUE
   '
   '--------------------------------------------------------------------
   Public Function OnInitPage(ByRef oPageIn, ByRef oEventArg)
      OnInitPage = TRUE
   End Function

   '---------------------------------------------------------------------
   ' Function:   OnServeAreaPage
   '
   ' Synopsis:   Called when the page needs to be served. Use this method to
   '         serve content.
   '
   ' Arguments: [in] oPageIn Page on which this event has been fired.
   '           [in] oEventArg Event argument for this event.
   '
   ' Returns:   Always returns TRUE
   '
   '---------------------------------------------------------------------
   Public Function OnServeAreaPage(ByRef oPageIn, ByRef oEventArg)
      Dim table
      Dim colFlags

      '
      ' Create the table
      table = OTS_CreateTable("", "This sample shows the basics for using the Object Task Selector")

      '
      ' Create Name column
      colFlags = (OTS_COL_KEY)
      Call OTS_AddTableColumn(table, OTS_CreateColumnEx( "Name", "left", colFlags, 15 ))
      '
      ' Create Description column
      colFlags = 0
      Call OTS_AddTableColumn(table, OTS_CreateColumnEx( "Description", "left", colFlags, 40))

      '
      ' Set Tasks section title
      Call OTS_SetTableTasksTitle(table, "Tasks")

      '
      ' Add the tasks associated with User objects
      '

      '
      ' New user Task is always available (OTS_TaskAlways)
      Call OTS_AddTableTask( table, OTS_CreateTaskEx("New", _
                              "Create a new user's profile", _
                              "sample/ots/sample_new.asp",_
                              OTS_PT_PROPERTY,_
                              "OTS_TaskAlways") )

      '
      ' Delete user Task is available if any task is selected (OTS_TaskAny)
      Call OTS_AddTableTask( table, OTS_CreateTaskEx("Delete", _
                              "Delete one or more users", _
                              "sample/ots/sample_delete.asp",_
                              OTS_PT_TABBED_PROPERTY,_
                              "OTS_TaskAny") )

      '
      ' Properties user Task is available if one task is selected (OTS_TaskOne)
      Call OTS_AddTableTask( table, OTS_CreateTaskEx("Properties", _
                              "Change the properties of a user", _
                              "sample/ots/sample_change.asp",_
                              OTS_PT_WIZARD,_
                              "OTS_TaskOne") )

      '
      ' Add Local Users to the table
      Call AddItemsToTable(table)

      '
      ' Enable table multiselection
      Call OTS_SetTableMultiSelection(Table, TRUE)

      '
      ' Send table to the Response stream
      Call OTS_ServeTable(table)

      '
      ' All done...
      OnServeAreaPage = TRUE
   End Function

   Private Function AddItemsToTable(ByRef Table)
      on error resume next
      err.clear

      '
      ' Fetch the list of users and add them to the table
      '
      Dim oContainer
      Dim oUser

      '
      ' ADSI call to get the local computer object
      Set oContainer = GetObject("WinNT://" + GetComputerName() )
      '
      ' ADSI call to get the collection of local users
      oContainer.Filter = Array("User")

      For Each oUser in oContainer
         Call OTS_AddTableRow( Table, Array(oUser.Name, oUser.Description))
      Next

      Set oContainer = Nothing

   End Function

   Private Function GetComputerName()
      on error resume next
      err.clear

      Dim oSysInfo

      Set oSysInfo = CreateObject("WinNTSystemInfo")
      GetComputerName = oSysInfo.ComputerName
      Set oSysInfo = Nothing

   End Function

%>


Sample ASP for an Object Task Selector Page (2)

Server Appliance Kit

Sample ASP Page for an Object/Task Selector Page (2)

The following code example shows a sample ASP page code for an Object/Task Selector page that implements sorting.

<%@ Language=VBScript   %>
<%   Option Explicit    %>
<%
   '----------------------------------------------------------------------
   ' OTS Area Page Template
    '---------------------------------------------------------------------
%>
<!--   Framework include file path is two levels up relative to this sample
      which is <WebRoot>/sample/ots
---------------------------------------------------------------------->
<!--   #include virtual="/admin/inc_framework.asp"                -->
<!--    #include virtual="/admin/ots_main.asp"                      -->
<%
   '-------------------------------------------------------------------
   ' Global Constants
   '-------------------------------------------------------------------
   Dim SOURCE_FILE
   SOURCE_FILE = SA_GetScriptFileName()

   '-------------------------------------------------------------------
   ' Global Variables
   '-------------------------------------------------------------------
   Dim g_iSortCol
   Dim g_sSortSequence

   '======================================================
   '
   '             E N T R Y   P O I N T
   '
   ' The following few lines implement the mainline entry point for this Web Page.
   ' Basically we create an Area page (PT_AREA) and then ask the Web Framework
   ' to start processing events for this page.
   '
   '======================================================
   Dim L_PAGETITLE
   Dim page

   L_PAGETITLE = "Sorting Example"

   '
   ' Create Page
   Call SA_CreatePage( L_PAGETITLE, "images/users_32x32.gif", PT_AREA, page )

   '
   ' Show page
   Call SA_ShowPage( page )

   '======================================================
   '
   '             E V E N T   H A N D L E R S
   '
   ' All of the Public functions that follow implement event handler functions that
   ' are called by the Web Framework in response to state changes on this web
   ' page.
   '
   '======================================================

   '---------------------------------------------------------------------
   ' Function:   OnInitPage
   '
   ' Synopsis:   Called to signal first time processing for this page. Use this method
   '         to do first time initialization tasks.
   '
   ' Arguments: [in] oPageIn Page on which this event has been fired.
   '           [in] oEventArg Event argument for this event.
   '
   ' Returns:   Always returns TRUE
   '
   '---------------------------------------------------------------------
   Public Function OnInitPage(ByRef oPageIn, ByRef oEventArg)
      OnInitPage = TRUE

      '
      ' Set default values
      '
      ' Sort first column in ascending sequence
      g_iSortCol = 0
      g_sSortSequence = "A"

   End Function

   '---------------------------------------------------------------------
   ' Function:   OnServeAreaPage
   '
   ' Synopsis:   Called when the page needs to be served. Use this method to
   '         serve content.
   '
   ' Arguments: [in] oPageIn Page on which this event has been fired.
   '           [in] oEventArg Event argument for this event.
   '
   ' Returns:   Always returns TRUE
   '
   '---------------------------------------------------------------------
   Public Function OnServeAreaPage(ByRef oPageIn, ByRef oEventArg)
      Dim table
      Dim colFlags

      '
      ' Create the table
      table = OTS_CreateTable("", "This sample shows how to use the sorting feature of the Object Task Selector.")

      '
      ' Create Name column
      colFlags = (OTS_COL_KEY OR OTS_COL_SORT)
      Call OTS_AddTableColumn(table, OTS_CreateColumnEx( "Name", "left", colFlags, 15 ))

      '
      ' Create Description column
      colFlags = (OTS_COL_SORT)
      Call OTS_AddTableColumn(table, OTS_CreateColumnEx( "Description", "left", colFlags, 40))

      '
      ' Set Tasks section title
      Call OTS_SetTableTasksTitle(table, "Tasks")

      '
      ' Add the tasks associated with User objects
      '

      '
      ' New user Task is always available (OTS_TaskAlways)
      Call OTS_AddTableTask( table, OTS_CreateTaskEx("New", _
                              "Create a new user's profile", _
                              "sample/ots/sample_new.asp",_
                              OTS_PT_PROPERTY,_
                              "OTS_TaskAlways") )

      '
      ' Delete user Task is available if any task is selected (OTS_TaskAny)
      Call OTS_AddTableTask( table, OTS_CreateTaskEx("Delete", _
                              "Delete one or more users", _
                              "sample/ots/sample_delete.asp",_
                              OTS_PT_TABBED_PROPERTY,_
                              "OTS_TaskAny") )

      '
      ' Properties user Task is available if one task is selected (OTS_TaskOne)
      Call OTS_AddTableTask( table, OTS_CreateTaskEx("Properties", _
                              "Change the properties of a user", _
                              "sample/ots/sample_change.asp",_
                              OTS_PT_WIZARD,_
                              "OTS_TaskOne") )

      '
      ' Add Local Users to the table
      Call AddItemsToTable(table)

      '
      ' Enable table multiselection
      Call OTS_SetTableMultiSelection(Table, TRUE)

      '
      ' Sort the table
      Call OTS_SortTable(table, g_iSortCol, g_sSortSequence, SA_RESERVED)

      '
      ' Send table to the Response stream
      Call OTS_ServeTable(table)

      '
      ' All done...
      OnServeAreaPage = TRUE
   End Function

   '---------------------------------------------------------------------
   ' Function:   OnSortNotify()
   '
   ' Synopsis:   Sorting notification event handler. This event is triggered in one of
   '         the following scenarios:
   '
   '         1) The user presses the search Go button.
   '         2) The user presses either the page next or page previous buttons
   '         3) The user requests a table column sort
   '
   '         The oEventArg indicates the source of this notification event which can
   '         be either a sorting change event (scenario 1) or a post back event
   '         (scenarios 2 or 3)
   '
   '         The sortCol argument indicated which column the user would like to sort
   '         and the sortSeq argument indicates the desired sort sequence which can
   '         be either ascending or descending.
   '
   ' Arguments: [in] oPageIn Page on which this event has been fired.
   '           [in] oEventArg Event argument for this event.
   '         [in] iSortCol Column number of the column that is to be sorted.
   '         [in] sSortSeq Sequence that the column is to be sorted. "A" for ascending,
   '               "D" for descending.
   '
   ' Returns:   Always returns TRUE
   '
   '---------------------------------------------------------------------
   Public Function OnSortNotify(ByRef oPageIn, _
                              ByRef oEventArg, _
                              ByVal iSortCol, _
                              ByVal sSortSeq )
      OnSortNotify = TRUE

      g_iSortCol = iSortCol
      g_sSortSequence = sSortSeq

   End Function

   Private Function AddItemsToTable(ByRef Table)
      on error resume next
      err.clear

      '
      ' Fetch the list of users and add them to the table
      '
      Dim oContainer
      Dim oUser

      '
      ' ADSI call to get the local computer object
      Set oContainer = GetObject("WinNT://" + GetComputerName() )
      '
      ' ADSI call to get the collection of local users
      oContainer.Filter = Array("User")

      For Each oUser in oContainer
         Call OTS_AddTableRow( Table, Array(oUser.Name, oUser.Description))
      Next

      Set oContainer = Nothing

   End Function

   Private Function GetComputerName()
      on error resume next
      err.clear

      Dim oSysInfo

      Set oSysInfo = CreateObject("WinNTSystemInfo")
      GetComputerName = oSysInfo.ComputerName
      Set oSysInfo = Nothing

   End Function
%>


Adding Initialization Tasks

Initialization tasks are tasks that are executed at certain times.

The following tables shows the list of initialization tasks.

Initialization task | Description
Appliance initialization task | An initialization task that is executed each time the server appliance is booted.
Every boot task | Executed each time the server appliance is booted.
First boot task | Executed on the first boot of the server appliance.
Reset configuration task | Executed by pressing the soft power switch multiple times.
Second boot task | Executed on the second boot of the server appliance.

Related Topics


Adding Task Objects to the Appliance Initialization Task

The Appliance Initialization Task is executed each time the server appliance is started. If called by a service – or by another task – the Appliance Initialization Task may occur without a restart on the part of the server appliance. The OEM can add task objects (server appliance tasks) to the end of the list of task executables in the Appliance Initialization Task. All of these task objects are executed each time the system starts. To add a task object so that a given task is executed every time the server appliance is initialized, you must stop and then start the Appliance Manager service, for example, net stop appmgr; net start appmgr, after changing the registry value.

Appliance Initialization Task objects are listed under the HKLM\Software\Microsoft\ServerAppliance\ApplianceManager\ObjectManagers\Microsoft_SA_Task\ApplianceInitializationTask registry key and the TaskExecutables value string. OEM-supplied task objects must appear at the end of the list in this string.

Related Topics


Adding Task Objects to the Every Boot Task

The Every Boot task is executed each time the server appliance is booted. The OEM can add appliance task objects to the list of task executables in the Every Boot Task. All of these task objects are executed every time the computer is booted. To add a task object so that a given task is executed every time the computer boots, you must stop and then start the Appliance Manager service, for example, net stop appmgr; net start appmgr, after changing the registry value.

Every Boot Task objects are listed under the HKLM\Software\Microsoft\ServerAppliance\ApplianceManager\ObjectManagers\Microsoft_SA_Task\EveryBootTask registry key and the TaskExecutables value name.

Related Topics


Adding Task Objects to the First Boot Task

The First Boot task is executed on the first boot of the server appliance. The OEM can add appliance task objects to the list of task executables in the First Boot Task. All of these task objects are executed on first boot. To get this functionality, you must stop and then start the Appliance Manager service, for example, net stop appmgr; net start appmgr, after changing the registry value.

You can find the First Boot Task objects listed under the HKLM\Software\Microsoft\ServerAppliance\ApplianceManager\ObjectManagers\Microsoft_SA_Task\FirstBootTask registry key and TaskExecutables value.

Related Topics


Adding Task Objects to the Reset Configuration Task

The Reset Configuration task is executed by pressing the soft power switch multiple times. This task provides a way to take the server appliance back to a known state in case the server appliance is no longer accessible via the network.

The OEM can add appliance task objects to the list of task executables in the Reset Configuration Task. These tasks will then be executed if the power switch is pressed multiple times.

To add a task object to the Reset Configuration Task

  1. Install the reliability services.
  2. After changing the registry value, stop, and then start, the Appliance Manager service – for example, net stop appmgr; net start appmgr.

You can find the Reset Configuration Task objects listed under the HKLM\Software\Microsoft\ServerAppliance\ApplianceManager\ObjectManagers\Microsoft_SA_Task\ResetConfigurationTask registry key and TaskExecutables value.

To set the number of key presses

  • Change the value of the HKLM\SYSTEM\CurrentControlSet\Services\VMSFTPWR\Parameters\Number of Key Presses registry key.

    This value is a REG_DWORD with a default value of 2. This new value can only be greater than, or equal, to 2.

To set the time interval between key presses

  • Change the value of the HKLM\SYSTEM\CurrentControlSet\Services\VMSFTPWR\Parameters\Key Press Interval registry key.

    This is a REG_DWORD and gives the time interval in milliseconds. The default value is 2,000 milliseconds. The new value must be between 2,000 to 10,000 milliseconds.

Related Topics


Adding Task Objects to the Second Boot Task

The Second Boot Task is executed on the second boot of the server appliance. The OEM can add appliance task objects to the list of task executables in the Second Boot Task. All of these task objects are executed on second boot. To assign a task to occur the second time the server appliance boots, after changing the registry value, you must stop and then start the Appliance Manager service – for example, net stop appmgr; net start appmgr.

Second Boot Task objects are listed under the following registry key and value.

Key:

HKLM\Software\Microsoft\ServerAppliance\ApplianceManager\ObjectManagers\Microsoft_SA_Task\SecondBootTask

Value Name: TaskExecutables

Type: string

Related Topics


Web UI Design Requirements

When you create Web UI pages to work with the Server Appliance Kit, they must meet the following requirements:

  • Localization. All the text in every components and page must come from the Localization Manager. Text should be stored in related DLLs – that is, all the text for each element of a primary navigation page must be stored in one or more DLLs. Furthermore, each DLL must not contain text for more than one primary navigation page.
  • OEM Branding. You can provide an image for the Status bar. The image must be no more than 50 pixels high, and can be between 200 and 400 pixels wide. The image must be on a black background and contain the company and product name. The image should be in the .gif file format.
  • Primary Navigation Item. The caption for a primary navigation item must be one word. The description must be a single sentence describing the page. The long description can provide more information; the general rule for long descriptions is that they are two to four sentences in length.

    Each primary navigation page must also have a unique graphic. The large graphic must be 192x192 pixels in size. The smaller element graphic must be 32x32 pixels in size. The graphic should match the look of the existing items.

  • Secondary Navigation Item. The caption for a secondary navigation item must be no more than two words. The description should be a single sentence describing the page. The long description can provide more information; the general rule for long descriptions is that they are two to four sentences in length.

    Each secondary navigation page should have a unique graphic. The graphic must be 32x32 pixels in size. The graphic should match the look of the existing items.

  • Custom Navigation Pages. Custom navigation pages have the same requirements as primary navigation pages.
  • System Resources. System resources must include status data, as well as an icon and caption. The caption must be no more than two words. The description must be a single sentence describing the resource. The icon must be 16x16 pixels in size. Resources can include a link to an extended status page or pagelet.
  • System Resource Details. System resource detail pages and pagelets must use the appropriate API call and include the icon, caption, and status of the system resource.
  • Alerts. The caption of an alert must be meaningful, such as Date and time not set up. The alert must include a link to another location in the UI, which will allow the user to resolve the problem.
  • Property Pages. Property pages must include a graphic in the header bar. The graphic must be a 16x16 pixel version of the graphic used on the navigation page
  • Multitabbed Property Pages. Multitabbed property pages must include a graphic in the header bar. The graphic must be a 16x16 pixel version of the graphic used on the navigation page. Additionally, the label for each tab is limited to two words.
  • Wizard Pages. Wizard pages must include a graphic in the header bar. The graphic must be a 16x16 pixel version of the graphic used on the navigation page. Additionally, wizard pages must include a graphic for the left panel of both the welcome and finish pages.

    The title of the welcome page must be Welcome to the <wizard name> Wizard. The title of each of the interior pages must indicate the purpose of that page. The title of the finish page must be Completing the <wizard name> Wizard. The finish page must display all the configurable elements addressed by the wizard and how they will be configured.

  • Area Pages. Area pages must include a graphic in the header bar. The graphic must be a 16x16 pixel version of the graphic used on the navigation page.
  • Object/Task Selector Area Pages. Object/Task Selector area pages have the same requirements as other area pages. In addition, they must provide sort, search, and virtual page capabilities. You can use the appropriate Object/Task Selector Routines for these capabilities.


Local User Interface Framework

The local user interface (UI) of a server appliance provides information to the user on the server appliance rather than on the client computer. When a server appliance is running and communicating with client computers, the Web UI available through a client computer is generally the best place to display information for the user. There are, however, the following three cases in which communicating with the user through the local UI is critical:

  • When the server appliance is inaccessible from a client computer, specifically during startup, shutdown, or when there is a problem with the local area network (LAN) connection.
  • When the user must perform a task at the server appliance–such as turning off the power to the server appliance, or inserting a tape into a drive. In these cases, information provided through the local UI eliminates the need for the user to travel between a client computer and the server appliance to gather critical information and complete the task.
  • When the user needs access to real-time system status information. The Web UI can only provide an instant copy of the system status at the time a page refreshes. For information like disk status, network status, or some device-specific task progress, customers need continual, real-time information directly from the server appliance itself. Providing status information as the default display on the local UI addresses these needs.

In short, the local UI provides end users a secondary UI from which to view the system status when real-time information is needed, and to configure the system when client computers displaying the Web UI are not in close proximity.

The local UI consists of an LCD panel and a small keypad, and should provide a concise, appliance-like experience for the user. Consequently, computer jargon and extraneous details are avoided. The local UI display can be a 64x128 pixel LCD. Alerts, as well as OEM branding, can be displayed on the local UI. The Microsoft® Server Appliance Kit 3.0 provides the software framework and some plug-in features for the local UI. The plug-in features provide the following subfeatures:

  • System status information
  • IP address and machine name
  • Alerts
  • Network configuration options
  • Machine name-setting options
  • Restart
  • Shutdown

In addition to the plug-in features provided, as OEM, you can add to the local UI to meet your device-specific needs. For example, makers of Windows Storage Server 2003 server appliances can use the local UI to display available disk space and to show how many users are logged on to the server appliance.

All local UI pages should be written in standard Hypertext Markup Language (HTML). Additionally, all text displayed in the local UI must run through the Server Appliance Kit’s Localization Manager to take full advantage of the multilingual support provided.

The following diagram illustrates how the local UI works.

Local user interface process flow


Boot Status

The following table illustrates the status information that displays while the system is booting.

Information displayed | Definition | Written by
Icon | Duration is approximately 20 seconds while the basic input/output system (BIOS) boots. | BIOS
Windows logo Starting icon should appear at the bottom of the screen. | Duration is ~60 seconds while the operating system starts. The local display driver gets the localized bitmap from the registry. This is an instance of the status page. | Local display driver
Windows logo Text: Running additional tasks. Please wait. Starting icon and other icons should appear at the bottom of the screen. | Local display driver gets the localized bitmap from the registry. This information displays while CHKDSK is running. The length of time is indeterminate. This is an instance of status page. It has no IP address, but a message is displayed under the Windows logo. | Local display driver
Product name logo or OEM logo IP address Ready icon and other icons should appear at the bottom of the screen. | This is the default display when the server appliance is running normally and no alerts are in the queue. This is the normal instance of the status page. | Local Display Manager feature of the local display framework


Status Page LUI

Server Appliance Kit

Status Page

The status page is the home page of the local UI. The status page displays the OEM logo and the status of system resources. This status information may take the form of text or icons. The status page will also provide an entry point for users to navigate to task pages, as appropriate.

The following diagram illustrates the status page.

Local UI status page layout

As an OEM developer, you may choose to take advantage of the existing Microsoft resource status components. Additionally, you can change the logo displayed or create your own text-based or icon-based resource status components and place them on the status page.

Related Topics


Adding a Local UI Task

It is conceivable that users may need to perform an action while physically at the server appliance, rather than managing administration tasks from a client computer. For such a case, the local UI task page provides a mechanism for you to add tasks which can be performed at the server appliance. Similar to task pages accessed through the Web UI, local UI task pages consist of hyperlinks to detail pages where users can complete the specified task. While the items illustrated in the following diagram represent Microsoft Server Appliance Kit 3.0 task components, as the OEM developer, you may create your own task components. If there are more task menu items than can be displayed on a single page, the screen will change, displaying the page with the currently-selected item, along with a page number in the bottom-right corner.

The following diagram illustrates the task page.

Local UI task layout diagram

The first task listed in the task page is the default selection when the task page is initially displayed. Thereafter, the currently-selected task will be remembered when the user leaves the page, and will show as being selected when the user returns.

In the event an alert is triggered, the alert icon will flash every 0.5 seconds and a View Alerts link will appear. In this situation, the alert icon and link will replace the task page number information displayed in the lower-right corner of the task page.

If no user interaction occurs for five minutes on a task page, the page will time out and the status page will display.


LocalUITask

A LocalUITask is an HTML page that is part of the local UI. A LocalUITask displays a screen which allows the user to enter configuration data, and then commit or cancel the changes.

To create a LocalUITask, you must create an HTML program to execute the task. Microsoft provides a Microsoft® ActiveX® data entry field control component to help collect data, a keypad controller component to map the keypad and methods to indicate the currently selected linked item. OEM developers can use these components in their HTML program.

The following table shows the registry values required for creating a LocalUITask.

Value | Type | Description | Example
ElementID | Key | "LocalUITask" followed by a unique name for this element. | LocalUITAskMyTaskName
Container | String | Container for this element. Is always LocalUITask. | LocalUITask
CaptionRID | String | Message caption resource identifier. This is the first line of text of a task displayed on the Task page. | 4C000004
DescriptionRID | String | Not used. | <empty>
ElementGraphic | String | Not used. | <empty>
IsEmbedded | DWORD | Not used. Always 0. | 0x0
Merit | DWORD | Determines the order in which the Web Element Manager returns this element. The lower the number, the closer it will be to the top of the list. | 0x1
Source | String | Name of resource DLL | sampleresource.dll
URL | String | Relative path (from %systemroot%\system32\ServerAppliance\LocalUI) to the task detail page. | localui_shutdown.htm

Optionally, the developer can also add a task to the Appliance Manager.


Task Details

Task details pages allow you to define the actual steps necessary for the user to complete the selected local task. To reach the task details page, select a hyperlink on the task page.

As an OEM developer, you can freely design the task details page using Hypertext Markup Language (HTML). The data entry control component and focus indicator component that have been provided should help the application developer in creating their own task details page using HTML. The task details page will run on Microsoft’s local UI framework, meaning that the timeout value will affect this page as it does others: after five minutes without any user interaction, the page will close and the status page will appear. Additionally, should you need to collect data from the user, you can use the data entry component of the Server Appliance Kit.


Alert Page

The alert page is the primary page for displaying an alert. Like the status page, the alert page displays the system resource status and task icons. The alert page also displays the server appliance IP address and host name between the list of alerts and the icons.

The following diagram illustrates the alert page.

Alert page layout diagram

You can create a new alert that will be displayed when the alert is raised. An alert can fill one or two lines, depending on how the Web element is defined. You can also turn the alert into a hyperlink that connects to the alert detail page.

When more than one alert needs to be displayed, multiple pages can be used.

The keypad is used for navigation. The UP and DOWN arrow keys select the task icon and alert hyperlink. After a hyperlink on the page has been selected, pressing the ENTER key jumps to the linked alert detail page. The LEFT and RIGHT arrow keys change pages if there are multiple alert pages. The CANCEL key is disabled while the alert page is active.


Alert Details

The alert detail page is specific to a given alert, and is accessed from the primary alert page through a hyperlink. The alerts details page is used to provide the user with additional information about the alert.

When a new alert is generated or an existing alert is cleared, the local UI will automatically close the alert detail page and revert to the primary alert page. If there are no extant alerts, the local UI will revert to the status page. Additionally, the alert detail page will time out if no user interaction occurs for five minutes. In this case, the alert detail page will revert to the primary alert or status page, depending on whether there are other alerts.

While an alert details page is active, the CANCEL key will close the alert detail page and revert to the alert page. The ENTER key and all arrow keys are disabled while an alert details page is active.

For more information about the local UI, see Local User Interface Framework.


Adding a Local UI Alert to the Web Element Database

You can add custom messages to be displayed on the local UI status page, following these guidelines:

  • Add the Web element definitions for the alert under the HKLM\Software\Microsoft\ServerAppliance\ElementManager\WebElementDefinitions registry key.
  • Add one Web element for each unique message.
  • Use unique AlertLog and AlertID values in your Web element definition to define custom messages.

    • One convention is to use the resource DLL name for the AlertLog value, and the CaptionRID value of the alert for the AlertID.

    Note

    • The AlertLog and AlertID values in the Web element definition must match the values used when raising the alert; to provide the text displayed for the alert, default viewer maps the caption and description resource identifiers to the alert.

The following table illustrates such a Web element.

Value | Type | Description | Example
ElementID | Key | Concatenation of "LocalUIAlertDefinitions"<AlertLog> and <AlertID> | LocalUIAlertDefinitionsChimeResource.dll4C000004
CaptionRID | String | Message caption resource identifier. This is the first line of text of an alert in the alert page. It is recommended to have less than 20 characters in this string due to screen size. | 4C000004
Container | String | Container for this element. | Should always be: LocalUIAlertDefinitions
DescriptionRID | String | Message description resource identifier. This is the second line of text of an alert in an alert page. It is recommended to have less than 20 characters in this string due to screen size. If this value is not defined (no value for this entry), there should be only one line of text for this alert in the alert page. | 4C000008
ElementGraphic | String | Not applicable | <empty>
IsEmbedded | DWORD | Instruction to process element as an embedded page | 0x0
LongDescriptionRID String
  • If the LongDescriptionRID value is not defined (no value for this entry), no hyperlink will be associated with this alert.
  • If there is a LongDescriptionRID value, there will be a hyperlink (to alert detail page) associated with this alert. The text indexed by LongDescriptionRID will be displayed in the alert detail page. It is recommended to have less than 80 characters in this string due to screen size.
 <empty>
LocalUIMsgCode | DWORD | Specifies the LED to be switched on when the alert is raised. | 0x00002000
Merit | DWORD | Not applicable | 0x0
Source | String | Name of resource DLL | ChimeResource.dll
URL | String | Must be empty to indicate that the default message view must be used | <empty>

Requirements

  • The Element identifier must be the string concatenation of the string LocalUIAlertDefinitions and the AlertLog and AlertID values.
  • The Container value must be LocalUIAlertDefinitions.
  • The CaptionRID value must contain the resource identifier of the string that is the text for the link.
  • The DescriptionRID value must contain a more detailed description of the message.
  • The URL value must be empty to indicate that the default message view must be used.

Related Topics


System Resources and Status

System resources refer to the hardware and software components of the server appliance that provide crucial functionality to the overall system, and for which the user will need to know the real-time status on a regular basis. Examples of system resources include the hard disk and network card, as well as some device-specific tasks, such as system backup.

The status of system resources is always displayed on the status page, either in text or icon form. The local UI framework provides machine, hard disk, network, and IP address status information.

The following illustration shows the Microsoft suggested architecture to control the display of the status icons, given the need to display real-time status information.

Suggested architecture for displaying status icons

As illustrated here, the monitor DLL calls the status DLL when the monitor DLL has status information to report. When the status DLL receives the report from the monitor DLL, the status DLL checks for a change in the system resource status by comparing the incoming status data to the status data that is currently displayed. If there is no change in the status data, the report is ignored. However, if there is a status change, the status DLL uses the resource identifier and status identifier to send the corresponding status text or icon to the HTML rendering engine. The bitmap that is generated can then be sent to the video manager of the local display to render the LCD.

The status DLL ensures that no more than one frame of bitmap is sent to the local display video manager per 0.5 second interval. In the event that the video manager does receive more than one status change per resource from the monitor DLL within a 0.5 second interval, the video manager maintains the more recent status data.

To avoid overuse of processor time in the LCD, when the video manager processes the status report from a resource after the 0.5 second interval has expired, the video manager compares the new status data to the status data that is currently displayed. If there is no change in status, the video manager ignores the status report.


Adding a Local UI Resource

The status page displays icons or text representing the state of various server appliance resources. The local UI framework provides disk and network activity resources. A new resource icon can be added.

Implementing the resource monitoring component

For each resource that is being monitored, a WMI provider must be implemented. Microsoft_SA_ResourceEvent class has been defined for providing resource state information.

This class has the following three properties:

String UniqueName;
Name of the appliance resource being monitored.
Unit32 DisplayInformationID;
This is the state identifier for the resource.
Unit32 CurrentState;
Current state. This field is optional.

Adding the resource to the local UI framework

A new resource DLL must be created for icon resources. The DLL contains graphic elements representing each state, including 16x16 icons corresponding to each state provided by the WMI provider. It contains text corresponding to each state for text resources. A new Web element must be added for each resource. The following table shows the available graphic elements.

Value | Type | Description | Example
ElementID | Key | Unique name for this element; container name + unique name | LocalUIResourceDiskEvent
Container | String | Name of the container for this element | LocalUIResource
Source | String | Name of resource DLL | Solocaluimsg.dll
CaptionRID | String | Caption resource identifier; default icon or text for resource | 201
DescriptionRID | String | Description resource identifier | Not used
URL | String | Relative path to file from Local UI root directory | Not used
ElementGraphic | String | Resource icon | Not used
Merit | DWORD | Integer indicating sort order in container, (0 = no sorting) | 3
IsEmbedded | DWORD | Always 0 | Not used
IsTextResource | DWORD | 0 for icon resources, 1 for text | 0
ResourceName | String | Unique name of the resource | DiskEvent
State1 | String | Resource identifier for icon or text corresponding to state 1 | 202
State2 | String | Resource identifier for icon or text corresponding to state 2 | 203
StateN | String | Resource identifier for icon or text corresponding to state N | 204

The container name must be LocalUIResource for each resource element. CaptionRID is the resource identifier of the text or icon corresponding to the default state of the resource. For other states, 1, 2, and so on, State1 and State2 keys will be used to determine the text or icon. State information is provided by the WMI object in the DISPLAYINFORMATIONID property.

The following code sample shows how the Microsoft-provided disk activity resource monitor reports states to the Microsoft local UI status management through WMI events. It has two basic states: busy and idle. The disk activity resource monitor creates a thread which determines disk state every second and calls the method below to notify the Microsoft local UI status management with a WMI event.

/////////////////////////////////////////////////////////////////////////
//  CSADiskEvent::NotifyDiskEvent
//  Description:
//      Called by InstanceThread to begin delivery of our events.
//
//  Arguments:
//     [in] lDisplayInformationIDIn       Resource ID for the disk event.
//          lCurrentStateIn               Reserved.
//
/////////////////////////////////////////////////////////////////////////
VOID
CSADiskEvent::NotifyDiskEvent(
     LONG     lDisplayInformationIDIn,
     LONG     lCurrentStateIn
        )
{
    //
    // Generate a new event object.
    //
    IWbemClassObject *pEvt = 0;

         //
         // m_pEventClassDef is a IWbemClassObject pointer obtained
         // during provider initialization through a GetObject call
         // for "Microsoft_SA_ResourceEvent" class
         //

    //
    // Generate a new event object.
    //
    HRESULT hRes = m_pEventClassDef->SpawnInstance( 0, &pEvt );
    if ( hRes != 0 )
      {
        SATraceString(
                      "CSADiskEvent::NotifyDiskEvent SpawnInstance failed"
                      );
        return;
       }

    //
    // SA_DISK_EVENT is "DiskEvent"
    // This property is the same as the ResourceName attribute of the localui resource
    // definition.
    //
    CVARIANT cvUniqueName( SA_DISK_EVENT );
    pEvt->Put(
                  CBSTR( SA_RESOURCEEVENT_UNIQUENAME ),
                  0,
                  cvUniqueName,
                  0
              );

    //
    // This is the state id, ie 0,1,2
    //
    CVARIANT cvDisplayInformationID( lDisplayInformationIDIn );
    pEvt->Put(
                  CBSTR( SA_RESOURCEEVENT_DISPLAYINFORMATION ),
                  0,
                  cvDisplayInformationID,
                  0
              );

//
    // Deliver the event to CIMOM.
    //
    hRes = m_pSink->Indicate(1, &pEvt);

    if ( FAILED( hRes ) )
       {
        SATraceString(
                      "CSADiskEvent::NotifyDiskEvent Indicate failed"
                     );
       }

    pEvt->Release();
}


Replacing the Local UI Logo

A new element must be added to the registry to replace the local UI logo with your own. The following table shows the elements that are available to add.

Value | Type | Description | Example
ElementID | Key | Unique name for this element | OEMLocalUILogoExample
Container | String | Name of the container for this element. This should always be OEMLocalUILogo. | OEMLocalUILogo
Source | String | Name of resource DLL | Not used
CaptionRID | String | Caption resource identifier | Not used
DescriptionRID | String | Description resource identifier | Not used
URL | String | Relative path to file from the local UI root directory | Not used
ElementGraphic | String | Relative path to file from the local UI root directory | ImageDir\Oem_Logo.gif
Merit | Dword | Integer indicating sort order in container. Integer should be less than 300 to replace the default logo. This should define the local UI directory, which is %systemroot%\system32\ServerAppliance\LocalUI. | 298
IsEmbedded | Dword | Always 0 | Not used

Only the Container, ElementGraphic, and Merit fields are used.

Container
This must be OEMLocalUILogo.
ElementGraphic
The path to the file containing the logo.
Merit
The logo in the element with the smallest merit value in the container will be displayed.


LED Display Support

To achieve the best user experience, Microsoft recommends using a 128x64 LCD panel to display the local UI. However, for hardware that only has an LED display, limited support is available. To control the LEDs, you can use a DWORD message code that allows minimal communication with the end user. It is important to note that this communication is limited to displaying information related to alerts.

The message codes are defined in the definition of each alert. With a 32-bit DWORD, the message code can control up to 32 LEDs. When the alert is raised, the message code is passed to the low-level driver; if the driver supports LEDs, it will convert the message code to the corresponding LED on/off pattern.

The following default message codes have been predefined. These message codes may be overridden, but it is recommended that additional codes be defined in the four most significant bits of the message code DWORD.

// Default message codes
#define READY           0x1    // OS is running normally
#define SHUTTING_DOWN   0x2    // OS is shutting down
#define NET_ERR         0x4    // LAN error
#define HW_ERR          0x8    // general hardware error
#define CHECK_DISK      0x10   // autochk.exe is running
#define BACKUP_DISK     0x20   // disk backup in progress
#define NEW_TAPE        0x40   // new tape media required
#define NEW_DISK        0x80   // new disk media required
#define STARTING        0x100  // OS is booting
#define WAN_CONNECTED   0x200  // connected to ISP
#define WAN_ERR         0x400  // WAN error–for example, no dial tone
#define DISK_ERR        0x800  // disk error–for example, dirty bit set
#define ADD_START_TASKS 0x1000 // additional startup tasks running–for example, autochk, sw update
#define CRITICAL_ERR    0x2000 // general error


Components Provided

To help you take full advantage of the local UI, Microsoft has provided the following components.

Data Entry Field Control

The local UI framework provides a data entry ActiveX control that can be used in an HTML page to obtain user input. The following explains how to use this ActiveX control with an example.

The following code sample shows how this ActiveX control can be inserted into any HTML with the <OBJECT> tag page.

<HTML>
…
<BODY>
          <OBJECT STYLE="position:absolute;
                    TOP:0; LEFT=0;
                    WIDTH=128; HEIGHT=64;"
                    ID="DataEntryControl"
                    CLASSID="CLSID:538D1B58-8D5A-47C5-9867-4B6230A94EAC">
          </OBJECT>
</BODY>
</HTML>

The above example positions the control on the top, left part of the HTML page.

The following table shows the properties that this ActiveX control supports.

Property | Description
TextValue | Displayed in the middle of the controller. It can be set and retrieved with a client-side script.
MaxSize | Integer value specifying the maximum length of the text data that can be entered using the ActiveX control. By default, it is 20.
TextCharSet | A string containing the set of characters that can appear in the text data. By default, it is ABCD…XYZ0123456789 , letters, numbers, and a space character.

The following table shows the two events that this ActiveX control fires which can be handled by a client-side script to take the proper action.

Event | Description
DataEntered | Fired when the user presses the ENTER key. This event can be used to get the NAME property and perform a useful task with it, such as setting the host name.
OperationCanceled | Fired when the user presses the ESC key. This event can be used to cancel the operation and go to a previous page.

The following HTML code sample demonstrates the use of this ActiveX control.

<HTML>
<HEAD>
<SCRIPT LANGUAGE="VBScript">
<!--
     Option Explicit

     Sub window_onload()

          Dim objKeypad
          'Create the keypad controller component and set the meaning of the keys

          Set objKeypad = CreateObject("Ldm.SAKeypadController")

          'Key 0, up arrow
          'Key 1, down arrow
          'Key 2, left arrow
          'Key 3, right arrow
          'Key 4, escape key
          'Key 5, enter key
          objKeypad.Setkey 0,38,FALSE
          objKeypad.Setkey 1,40,FALSE
          objKeypad.Setkey 2,37,FALSE
          objKeypad.Setkey 3,39,FALSE
          objKeypad.Setkey 4,27,FALSE
          objKeypad.Setkey 5,13,FALSE

          Set objKeypad = Nothing

          'Set the max size to 10
          DataEntryControl.MaxSize = 10

          'Set the character set
          DataEntryControl.MaxSize = "ABCFOXY0123"

          'Set a default value to the control
          DataEntryControl.TextValue = "FOO"

          'Set the focus to the control
          DataEntryControl.focus

     End Sub

     Sub DataEntryControl_DataEntered()

          Dim strValue
          'Data entered, get the name property
          strValue = DataEntryControl.TextValue

          'Perform a task with this value
          …
     End Sub

     Sub DataEntryControl_OperationCanceled()

'Operation cancelled, take the proper action such as going to previous page
          …

     End Sub

-->
</SCRIPT>
</HEAD>
<BODY>
<OBJECT STYLE="position:absolute;
     TOP:0; LEFT=0;
     WIDTH=128; HEIGHT=64;"
     ID="DataEntryControl"
     CLASSID="CLSID:538D1B58-8D5A-47C5-9867-4B6230A94EAC">
</OBJECT>
</BODY>
</HTML>

Focus Indicator

A task page can be a list of multiple options from which a user selects to proceed with more specific operations. For example, the network configuration task provides two options: static and auto IP. In such cases, the current selection must be clearly marked. This section provides a solution for such pages with an example.

Consider a page with two options, custom task 1 and custom task 2. These options are links to other pages. Whenever a link is selected, Internet Explorer draws a dotted rectangle around the link. It does not clearly identify the selected link and it also does not display attractively on the LCD. Therefore, the selected link will be inverted. Whenever a link receives the focus, its background will be set to black and its text color will be set to white.

The OnFocus event of the <A> object is called whenever a link receives the focus. As seen below, the FocusOnItem method is implemented to handle the event. This method provides the inverting effect. The following code sample shows how to implement the focus indicator.

<HTML>
<HEAD>

<TITLE>Sample Page</TITLE>

<SCRIPT LANGUAGE="VBScript">
<!--

     Sub FocusOnItem(iItemIndex)

          'First item has been selected
          If iItemIndex = 1 Then
               'Invert the first item
               Task1.style.backgroundColor = "#000000"
               Task1.style.color = "#FFFFFF"

               'Revert the second item to normal
               Task2.style.backgroundColor = "#FFFFFF"
               Task2.style.color = "#000000"

          ElseIf iItemIndex = 2 Then

               'Invert the second item
               Task2.style.backgroundColor = "#000000"
               Task2.style.color = "#FFFFFF"

               'Revert the first item to normal
               Task1.style.backgroundColor = "#FFFFFF"
               Task1.style.color = "#000000"

          End If
     End Sub
-->
</SCRIPT>

</HEAD>

<BODY RIGHTMARGIN=0 LEFTMARGIN=0>

     <A STYLE="position:absolute; top:0; left:10; font-size:10; font-family=arial;"
          id="Task1" OnFocus="FocusOnItem(1)" HREF="http://www.msn.com">
     Custom Task1
     </A>

     <A STYLE="position:absolute; top:10; left:10; font-size:10; font-family=arial;"
          id="Task2" OnFocus="FocusOnItem(2)" HREF="http://www.msnbc.com">
     Custom Task2
     </A>

</BODY>

</HTML>

Keypad Controller Component

There are typically six keys on the LCD hardware. The meaning of each key press is interpreted differently in different pages of the local UI. To support the maximum flexibility, these keys can be defined with a client-side script on each page.

The following diagram shows an example layout of the keys on the hardware with their key codes.

Local UI keypad layout diagram

The following table shows the default meanings that correspond to key presses on the keyboard.

Key | Description
0 | TAB key on the keyboard. SHIFT key is also down.
1 | TAB key on the keyboard. SHIFT key is up.
2 | LEFT arrow key on the keyboard. SHIFT key is up.
3 | RIGHT arrow key on the keyboard. SHIFT key is up.
4 | Simulates choosing the Back button on Internet Explorer.
5 | ENTER key on the keyboard. SHIFT key is up.

Each time a new page is loaded, these default key values are loaded. The keypad controller component can be used to change the meaning of every key in any page.

The ProgID for this component is Ldm.SAKeypadController. It exposes the following method code sample to set the meaning of each key.

HRESULT SetKey (LONG lKeyID, LONG lMessage, BOOL fShiftKeyDown)

The first argument for this method is the key code of the key that will be set (0-5). The second argument corresponds to the window key code of any of the keyboard keys. The following table lists some of the useful key codes.

Key code | Description
0 | Special code. Disables the key.
-1 | Special code. Simulates choosing the Back button on Internet Explorer.
13 | Corresponds to the ENTER key on the keyboard.
9 | Corresponds to the TAB key on the keyboard.
27 | Corresponds to the ESC key on the keyboard.
37 | LEFT arrow key on the keyboard.
38 | UP arrow key on the keyboard.
39 | RIGHT arrow key on the keyboard.
40 | DOWN arrow key on the keyboard.

Note

  • You can obtain more key codes for keys on the keyboard from the Windows SDK.

The third argument is a Boolean return value that specifies the state of the shift key. The return value is True if the SHIFT key is down and False if the SHIFT key is up.

The following code sample demonstrates how you can use the method listed earlier in this topic to set key meanings for each key of the LCD. The OnLoad event of the window in an HTML page is the proper place set key meanings.

<SCRIPT LANGUAGE="VBScript">
<!--
     Option Explicit

     Sub Window_OnLoad

          Dim objKeypad
          Set objKeypad = CreateObject("Ldm.SAKeypadController")

          objKeypad.Setkey 0,9,TRUE
          objKeypad.Setkey 1,9,FALSE
          objKeypad.Setkey 2,37,FALSE
          objKeypad.Setkey 3,39,FALSE
          objKeypad.Setkey 4,0,FALSE
          objKeypad.Setkey 5,13,FALSE

          Set objKeypad = Nothing

     End Sub
-->
</SCRIPT>

The following table shows the keys that are set by the code sample above.

Key | Description
0 | TAB key on the keyboard. SHIFT key is also down.
1 | TAB key on the keyboard. SHIFT key is up.
2 | LEFT arrow key on the keyboard. SHIFT key is up.
3 | RIGHT arrow key on the keyboard. SHIFT key is up.
4 | Disables the key.
5 | ENTER key on the keyboard. SHIFT key is up.


Localization

All text that is displayed on the local display must run through the localization manager so that the local display can be fully multilingual. For more information, see Localization Framework.


API Reference

The Web user interface (UI) framework is used to create customizable Web content for a server appliance running Microsoft® Windows Server 2003. The following topics provide detailed information regarding the various elements of the Web UI framework.

Web Framework Routines and Events

Object/Task Selector Routines

Client-Side Routines

Error-trapping Routines

Debugging Routines

Utility Routines


Web Framework Routines and Events

The following pages describe the application programming interface (API) routines used to create Web content and handle Web framework events.

Routine/event | Description
OnClosePage | Signals the end of processing.
OnInitPage | Signals first-time processing.
OnPostBackPage | Indicates that the user has navigated to within the ASP page.
OnServeAreaPage | Occurs whenever the Web framework needs to send content. Applicable only to area pages.
OnServePageletPage | Occurs whenever the Web framework needs to send content. Applicable only to area pagelets.
OnServePropertyPage | Occurs whenever the Web framework needs to send content. Applicable only to property pages.
OnServeTabbedPropertyPage | Occurs whenever the Web framework needs to send content. Applicable only to tabbed property pages.
OnSubmitPage | Indicates that the user has submitted the page for processing.
OnWizardNextPage | Occurs whenever the Web framework needs to determine which wizard page is the next page to be shown.
OnServeWizardPage | Occurs whenever the Web framework needs to send content.
SA_AddTabPage | Adds a tab to a multitabbed property page.
SA_AddWizardPage | Adds a wizard page to a wizard.
SA_CreatePage | Creates a Web page of the specified page type.
SA_ExecuteTask | Executes a server appliance task back-end object.
SA_GetScriptFileName | Returns the current script file (ASP) name, obtained from the Request.ServerVariables collection.
SA_IsAsyncTaskBusy | Returns a Boolean value indicating whether the asynchronous task is busy.
SA_IsChangeEvent | Checks to see if the event type is an SA_EVENT_CHANGE. A change event indicates that the state of the control has changed.
SA_IsPostBackEvent | Checks to see if the event type is an SA_EVENT_POSTBACK. A post-back event provides notification of the current state, as contrasted with the change event, which indicates a state change since the last post-back event.
SA_ServeFailurePage | Serves an error page and should be used when an irrecoverable error is encountered.
SA_ServeOpenPageButton | Creates an image button that allows the user to open the specified page type.
SA_ServeOnClickButton | Creates a button that, when clicked, will invoke a JavaScript function.
SA_ServeResourceStatus | Serves resource status information. This routine is intended to be used by resource pagelets to display status information.
SA_ServeRestartingPage | Serves the restarting page.
SA_SetActiveTabPage | Sets the active tab in a tabbed property page. This routine is used if you want to set a tab other than the first tab as the active tab.
SA_SetErrMsg | Sets the error message to display.
SA_SetGenericMsg | Sets a general-purpose message to display.
SA_SetPageRefreshInterval | Sets the page auto-refresh interval for either a pagelet or an area page.
SA_ShowPage | Shows the specified page.
SAI_GetPageKey | Obtains a key associated with the current user for this session. This key is used to verify that a hyperlink or form input is from a Web UI framework ASP page.

Related Topics


OnInitPage

This event signals first-time processing and applies to all page types. Use it to initialize a page for the first time. For example, you might use it to create and initialize session variables.

OnInitPage(
ByRef PageIn,
ByRef EventArgIn
)

Parameters

PageIn
Reference to the page object.
EventArgIn
Reserved for future use. Reference to the event argument, which contains additional information regarding the event.

Return Values

This event always returns TRUE.

Remarks

The following code sample illustrates how to use this event handler.

Public Function OnInitPage(ByRef PageIn, ByRef EventArgIn)
    L_ADDRESS_DESC = SA_GetLocString("sample.dll", "4000040", "")
    OnInitPage = SetVariablesFromSystem()
End Function

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


OnClosePage

This page event signals the end of processing. Use this method to perform cleanup tasks for the page. For example, you might use it to free session variables.

OnClosePage(
ByRef PageIn,
ByRef EventArgIn
)

Parameters

PageIn
Reference to the page object.
EventArgIn
Reserved for future use. Reference to the event argument, which contains additional information regarding the event.

Return Values

This event always returns TRUE.

Remarks

The event is applicable only to property pages, tabbed property pages, and wizard pages.

The following code sample illustrates how to use this event handler.

Public Function OnClosePage(ByRef PageIn, ByRef EventArgIn)
    OnClosePage = TRUE
End Function

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


OnPostBackPage

This page event indicates that the user has navigated to another page. Use this event to save the state of the page between post-back and OnServePage events.

OnPostBackPage(
ByRef PageIn,
ByRef EventArgIn
)

Parameters

PageIn
Reference to the page object.
EventArgIn
Reserved for future use. Reference to the event argument, which contains additional information regarding the event.

Return Values

This event always returns TRUE.

Remarks

Timing occurs when a page post-back event has occurred. Post-back events occur as the user navigates through a multiple tab page such as a tabbed property page or a wizard page.

This event is applicable only to property pages, tabbed property pages, and wizard pages. The following code sample illustrates how to use this event handler.

Public Function OnPostBackPage(ByRef PageIn, ByRef EventArgIn)
    OnPostBackPage = TRUE
End Function

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


OnServeAreaPage

This page event occurs whenever the Web framework needs to send content for an area page.

OnServeAreaPage(
ByRef PageIn,
ByRef EventArgIn
)

Parameters

PageIn
Reference to the page object that needs to be initialized.
EventArgIn
Reserved for future use. Reference to the event argument, which contains additional information regarding the event.

Return Values

This event always returns TRUE.

Remarks

This event is called in response to the following event scenarios:

OnInitPage
Success code (TRUE) was returned in response to the page initialization event. In this context, the OnServeAreaPage method is being called for the first time.
OnSubmitPage
Error code (FALSE) was returned in response to the OnSubmitPage event. In this context, this method is being called after an error occurred.

Use this method to write HTML content to the response stream, either in line or using Response.Write.

This event is applicable only to area pages.

The following code sample illustrates how to use this event handler.

Public Function OnServeAreaPage(ByRef PageIn, ByRef EventArgIn)
    OnServeAreaPage = TRUE
End Function

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


OnServePageletPage

This page event occurs whenever the Web framework needs to send content for an area pagelet.

OnServePageletPage(
ByRef PageIn,
ByRef EventArgIn
)

Parameters

PageIn
Reference to the page object that needs to be initialized.
EventArgIn
Reserved for future use. Reference to the event argument, which contains additional information regarding the event.

Return Values

This event always returns TRUE.

Remarks

This event is called in response to the following event scenarios:

OnInitPage
Success code (TRUE) was returned in response to the page initialization event. In this context, the OnServePageletPage method is being called for the first time.
OnSubmitPage
Error code (FALSE) was returned in response to the OnSubmitPage event. In this context, this method is being called after an error occurred.

Use this method to write HTML content to the response stream, either in line or using Response.Write.

This event is applicable only to area pagelets.

The following code sample illustrates how to use this event handler.

Public Function OnServePageletPage(ByRef PageIn, ByRef EventArgIn)
    OnServePageletPage = TRUE
End Function

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


OnServePropertyPage

This page event occurs whenever the Web framework needs to send content.

OnServePropertyPage(
ByRef PageIn,
ByRef EventArgIn
)

Parameters

PageIn
Reference to the page object that needs to be initialized.
EventArgIn
Reserved for future use. Reference to the event argument, which contains additional information regarding the event.

Return Values

This event always returns TRUE.

Remarks

OnInitPage
Success code (TRUE) was returned in response to the page initialization event. In this context, the OnServePropertyPage method is being called for the first time.
OnSubmitPage
Error code (FALSE) was returned in response to the OnSubmitPage event. In this context, this method is being called after an error occurred.

Use this method to write HTML content to the response stream, either in line or using Response.Write.

This event is applicable only to property pages.

The following code sample illustrates how to use this event handler.

Public Function OnServePropertyPage(ByRef PageIn, ByRef EventArgIn)
    Response.Write("<TABLE><TR nowrap>")
    Response.Write("<TD>"+L_ADDRESS_DESC+"</TD>")
    Response.Write("<TD>")
    Response.Write("<INPUT type=text")
    Response.Write(" name=frmAddress")
    Response.Write(" value="+F_Address + ">")
    Response.Write("</TD>")
    Response.Write("</TR></TABLE>")
    OnServePropertyPage = TRUE
End Function

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


OnServeTabbedPropertyPage

This page event occurs whenever the Web Framework needs to send content.

OnServeTabbedPropertyPage(
ByRef PageIn,
ByVal iTab,
ByVal bIsVisible,
ByRef EventArgIn
)

Parameters

PageIn
Reference to the page object that needs to be initialized.
iTab
Number of the tab that needs to be rendered.
bIsVisible
Boolean indicating if the tab needs to be rendered as visible (TRUE) or hidden (FALSE).
EventArgIn
Reserved for future use. Reference to the event argument, which contains additional information regarding the event.

Return Values

This event always returns TRUE.

Remarks

This event is called in response to the following event scenarios.

OnInitPage
Success code (TRUE) was returned in response to the page initialization event. In this context, the OnServeAreaPage method is being called for the first time.
OnSubmitPage
Error code (FALSE) was returned in response to the OnSubmitPage event. In this context, this method is being called after an error occurred.

This method is called once for each tab. Tabs that are not visible should emit hidden form fields containing current state information to enable state persistence during post-back events. As the user tabs between pages, the post-back event, OnPostBackPage, is called. The state of hidden pages can be retrieved on these operations if the hidden tab page emits hidden form fields.

Use this method to write HTML content to the response stream, either in line or using Response.Write.

This event is applicable only to tabbed property pages.

Timing occurs every time page content needs to be served.

The following code sample illustrates how to use this event handler.

Public Function OnServeTabbedPropertyPage(ByRef PageIn, ByVal iTab,_
                                          ByVal bIsVisible, ByRef EventArgIn)
    If (bIsVisible) Then
        Response.Write("<TABLE><TR nowrap>")
        Response.Write("<TD>"+L_ADDRESS_DESC+"</TD>")
        Response.Write("<TD>")
        Response.Write("<INPUT type=text")
        Response.Write(" name=frmAddress")
        Response.Write(" value="+F_Address + ">")
        Response.Write("</TD>")
        Response.Write("</TR></TABLE>")
    Else
        Response.Write("<INPUT type=hidden")
        Response.Write(" name=frmAddress")
        Response.Write(" value="+F_Address + ">")
    End If
    OnServeTabbedPropertyPage = TRUE
End Function

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


OnServeWizardPage

This event occurs whenever the Web Framework needs to send content.

OnServeWizardPage(
ByRef PageIn,
ByVal iPageID,
ByVal bIsVisible,
ByRef EventArg
)

Parameters

PageIn
Reference to the page object.
iPageID
ID of the page that needs to be rendered.
bIsVisible
Boolean value indicating whether the tab page needs to be rendered as visible (TRUE) or hidden (FALSE).
EventArgIn
Reserved for future use. Reference to the event argument, which contains additional information regarding the event.

Return Values

This event always returns TRUE.

Remarks

This event is called in response to the following event scenarios.

OnInitPage
Success code (TRUE) was returned in response to the page initialization event. In this context, the OnServePropertyPage method is being called for the first time.
OnSubmitPage
Error code (FALSE) was returned in response to the OnSubmitPage event. In this context, this method is being called after an error occurred.

This method is called once for each page in the wizard. Pages that are not visible should emit hidden form fields containing current state to enable state persistence during post-back events. Use this method to write HTML content to the response stream, either in line or using Response.Write.

This event is applicable only to wizard pages.

Timing occurs every time page content needs to be served.

The following code sample illustrates how to use this event handler.

Public Function OnServeWizardPage(ByRef PageIn, ByVal iPageID, ByVal bIsVisible, ByRef EventArg)

Select Case iPageID
   Case idIntro
      Call ServeIntro(PageIn, bIsVisible)

   Case idPage1
      Call ServePage1(PageIn, bIsVisible)

   Case idFinish
      Call ServeFinish(PageIn, bIsVisible)

   Case Else
      ' Handle error here
End Select

OnServeWizardPage = TRUE
End Function

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


OnSubmitPage

This page event indicates that the user has submitted the page for processing. Use this event to perform the appropriate page-specific action. For example, the Add User Account page would add the user account to the system during processing of this event.

OnSubmitPage(
ByRef PageIn,
ByRef EventArgIn
)

Parameters

PageIn
Reference to the page object.
EventArgIn
Reserved for future use. Reference to the event argument, which contains additional information regarding the event.

Return Values

TRUE
The event was successful.
FALSE
The event failed. Depending on what type of page this is, one of the following events will occur:

OnServePropertyPage, OnServeTabbedPropertyPage, OnServeWizardPage, or OnWizardNextPage.

Remarks

Timing occurs when the page has been submitted for processing.

OnSubmitPage is applicable only to property pages, tabbed property pages, and wizard pages. The following code sample illustrates how to use this event handler.

Public Function OnSubmitPage(ByRef PageIn, ByRef EventArgIn)
    OnSubmitPage = TRUE
End Function

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


OnWizardNextPage

This event occurs whenever the Web framework needs to determine which wizard page is the next page to be shown.

OnWizardNextPage(
ByRef PageIn,
ByRef EventArg,
ByVal iCurrentPageID,
ByVal iPageAction,
ByRef iNextPageID,
ByRef iPageType
)

Parameters

PageIn
Reference to the page object.
EventArg
Reserved for future use. Reference to the event argument, which contains additional information regarding the event.
iCurrentPageID
Page identifier of the page that is currently visible.
iPageAction
Action that the user selected on the current page. The following actions show the possible actions.
Variable | Description
PA_NEXT | The Next button was clicked.
PA_BACK | The Back button was clicked.
PA_FINISH | The Finish button was clicked.
iNextPageID
Next page that the wizard should show. This is an output argument that must be set by the called function.
iPageType
Next wizard page type. This is an output argument that must be set by the called function. The following table shows the wizard page types available.
Variable | Description
WIZPAGE_INTRO | The Intro wizard page.
WIZPAGE_STANDARD | The Standard wizard page.
WIZPAGE_FINISH | The Finish wizard page.

Return Values

This method always returns a TRUE value.

Remarks

Use this method to determine which page should be shown next. Because wizard page logic depends on input selections made by the user, this function will need to examine previous selections made by the user to determine the next logical page that should be shown.

Timing occurs when the Web framework needs to determine which wizard page is the next page to be shown.

The following code sample illustrates how to use this event handler.

Public Function OnWizardNextPage(ByRef PageIn, ByRef EventArg, ByVal iCurrentPageID,_
                                 ByVal iPageAction, ByRef iNextPageID, ByRef iPageType)

Select Case iCurrentPageID
   Case idIntro
   Call OnIntroNavigate(iPageAction, iNextPageID, iPageType)

   Case idPage1
   Call OnPage1Navigate(iPageAction, iNextPageID, iPageType)

   Case idSelectTarget
   Call OnSelectTargetNavigate(iPageAction, iNextPageID, iPageType)

   Case idFinish
   Call OnFinishNavigate(iPageAction, iNextPageID, iPageType)

   Case Else
   ' Handle error here
   Call OnIntroNavigate(iPageAction, iNextPageID, iPageType)
End Select

OnWizardNextPage = true
End Function

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_AddTabPage

This function adds a tab to a tabbed property page. Tabs appear in the order they are added.

SA_AddTabPage(
ByRef PageIn,
ByVal sTabDesc,
ByRef iTabNumber
)

Parameters

PageIn
Reference to the page object.
sTabDesc
Localized string for the tab title.
iTabNumber
Reference to the variable that receives the output tab ID for the newly added tab.

Return Values

SA_NO_ERROR
The page was created.
SA_ERROR_INVALIDPAGE
The PageIn parameter is invalid.

Remarks

The following code sample illustrates how to use this function.

Dim retCode
Dim page
Dim iTabGeneral

retCode = SA_AddTabPage(page, "General", iTabGeneral)
If (retCode <> SA_NO_ERROR) Then
    ' Handle error
End If

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_AddWizardPage

This method adds a wizard page to a wizard. The Web framework fires the OnWizardNextPage event to determine appearance order for wizard pages.

SA_AddWizardPage(
ByRef PageIn,
ByVal sPageTitle,
ByRef iPageOut
)

Parameters

PageIn
Reference to the page object.
sPageTitle
Title for the wizard page.
iPageOut
Reference to the variable that receives the page identifier for this wizard page.

Return Values

This method has the following return values.

SA_NO_ERROR
The page was created.
SA_ERROR_INVALIDPAGE
The PageIn parameter is invalid.

Remarks

The following code sample illustrates how to use this function.

Dim page
Dim idIntro, idPage1, idFinish
Dim aImages(2)
aImages(0) = "images/disksX16.gif"
aImages(1) = "images/disks.gif"

Call SA_CreatePage("Wizard Page Template", aImages, PT_WIZARD, page)
Call SA_AddWizardPage(page, "Welcome to the Internet Setup Wizard", idIntro)
Call SA_AddWizardPage(page, "Internet connection options", idPage1)
Call SA_AddWizardPage(page, "Finishing Internet Setup", idFinish)

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This routine is part of the complete Microsoft Server Appliance Kit. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this routine.

Related Topics


SA_CreatePage

This function creates a Web page of the specified page type.

SA_CreatePage(
ByVal sTitleIn,
ByVal sPageImage,
ByVal enPageType,
ByRef PageOut
)

Parameters

sTitleIn
This is a localized string containing the title of the page.
sPageImage
Image URL. This parameter is optional. To omit this parameter, use an empty string (see example). Wizard pages can specify one or more image URLs in this parameter by passing an array of image URLs.
enPageType
This is the PageType enumeration.
PageOut
This is a reference to a variable that receives the output page object. This output is required as input on other server appliance Web framework routines.

Return Values

SA_NO_ERROR
The page was created.
SA_ERROR_INVALIDPAGE
The EnPageType parameter is invalid.

Remarks

The following table shows the possible page types.

PageType | Description
PT_AREA | Creates an area page.
PT_PAGELET | Creates a pagelet page.
PT_PROPERTY | Creates a property page.
PT_TABBED | Creates a multitabbed property page.
PT_WIZARD | Creates a Wizard-style property page.

The following code sample illustrates how to use this function.

Dim retCode
Dim page

'
' Create a property page. Note that L_PAGE_TITLE is initialized
' elsewhere.
retCode = SA_CreatePage(L_PAGE_TITLE,"", PT_PROPERTY, page)
If (retCode <> SA_NO_ERROR) Then
    ' Handle error
End If

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_ExecuteTask

This function executes a server appliance task back-end object. Normally, back-end tasks are executed synchronously. The bExecuteAsync parameter allows you to override this behavior.

SA_ExecuteTask(
ByVal TaskName,
ByVal bExecuteAsync,
ByRef oTaskContext
)

Parameters

TaskName
Required. Name of the task to execute.
bExecuteAsync
Flag indicating whether the task should be executing asynchronously. Normally, tasks are executed synchronously. Setting this parameter to TRUE will change the default behavior, thus executing the task asynchronously.
oTaskContext
Object that contains parameters for the task.

Return Values

Value | Description
SA_NO_ERROR | The call succeeded. No errors occurred.
SA_ERROR_CREATE_OBJECT_FAILED | Unable to create one of the required back-end objects. This indicates that either the components were not installed correctly or that the appliance manager service is not running.
SA_ERROR_INITIALIZE_OBJECT_FAILED | The task object encountered an unrecoverable error during its internal initialization. This is probably not recoverable and likely indicates a problem with either the expected inputs or the current state of the server appliance task.
The HRESULT return value received from the task. | An error occurred, but was not one of the two anticipated errors. This applies to all other cases not mentioned above.

Remarks

If the oTaskContext object has not been created and initialized, this function will create a default oTaskContext object and will initialize it by creating task parameters using all input form fields from the current request object. This makes it easy to pass the oTaskContext object in HTML format to the server appliance task.

If an error is encountered, there is no reasonable recovery that a scripting client can make.

The following code samples illustrate how to use this function.

'--------------------------------------------------------
'Example 1 - Create TaskContext and set input parameters:
'--------------------------------------------------------
Dim oTaskContext
Dim rc

Set oTaskContext = CreateObject("Taskctx.TaskContext")
If Err.Number <> 0 Then
     ' Handle the error
     Exit Function
End If

Call oTaskContext.SetParameter("Method Name", strMethodName)
Call oTaskContext.SetParameter("LanguageID", strLANGID)

Call oTaskContext.SetParameter("AutoConfig", "y")

rc = SA_ExecuteTask("ChangeLanguage", FALSE, oTaskContext)
If ( rc <> SA_NO_ERROR ) Then
     ' Handle the error
End If

'------------------------------------------------------------------------
'Example 2 - Use the current input form (request object) as input to the task
'------------------------------------------------------------------------
Dim rc
Dim oTaskContext

Set oTaskContext = nothing
rc = SA_ExecuteTask("MyApplianceTask", FALSE, oTaskContext)
If ( rc <> SA_NO_ERROR ) Then
     ' Handle the error
End If

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_GetScriptFileName

Returns the current script file (ASP) name, obtained from the Request.ServerVariables collection.

SA_GetScriptFileName()

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  |  |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_IsAsyncTaskBusy

This function returns a Boolean value indicating whether the asynchronous task is busy.

SA_IsAsyncTaskBusy(
ByVal TaskName
)

Parameters

TaskName
Name of the task to be checked.

Return Values

TRUE
The task is already running.
FALSE
The task is not running.

Remarks

The SA_IsAsyncTaskBusy function checks to see if the specified task is already executing. It is advisable to make sure a task is not already running before starting it.

The following code sample illustrates how to use this function.

If SA_IsAsyncTaskBusy(mstrAsyncTaskName) Then
' Task is busy
Else
' Task is not busy
End If

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_IsChangeEvent

This function checks to see if the event type is an SA_EVENT_CHANGE. A change event indicates that the state of the control has changed. This differs from a post-back event, which simply provides notification of the current state.

SA_IsChangeEvent(
ByRef oEvent
)

Parameters

oEvent
Reference to the event object.

Return Values

This function has the following return values.

TRUE
The specified event is a change event.
FALSE
The specified event is not a change event.

Remarks

The following code example illustrates how to use this function.

Public Function OnSortNotify(ByRef PageIn, _
                             ByRef EventArg, _
                             ByVal sortCol, _
                             ByVal sortSeq)
OnSortNotify = TRUE
'
' User clicked column sort
'
If SA_IsChangeEvent(EventArg) Then
   g_iSortCol = sortCol
   g_sSortSequence = sortSeq
   g_bSortRequested = TRUE
'
' User clicked the Search, Go, next, or previous button
'
ElseIf SA_IsPostBackEvent(EventArg) Then
   g_iSortCol = sortCol
   g_sSortSequence = sortSeq
   g_bSortRequested = TRUE
'
' Unknown event source
Else
   ' Handle error here
End IF

End Function

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


SA_IsPostBackEvent

This function checks to see if the event type is an SA_EVENT_POSTBACK. A post-back event provides notification of the current state, as contrasted with the change event, which indicates a state change since that last post-back event.

SA_IsPostBackEvent(
ByRef oEvent
)

Parameters

oEvent
Reference to the event object.

Return Values

This function has the following return values.

TRUE
The specified event is a post-back event.
FALSE
The specified event is not a post-back event.

Remarks

The following code sample illustrates how to use this function.

Public Function OnSortNotify(ByRef PageIn, _
                             ByRef EventArg, _
                             ByVal sortCol, _
                             ByVal sortSeq)
OnSortNotify = TRUE
'
' User clicked column sort
'
If SA_IsChangeEvent(EventArg) Then
   g_iSortCol = sortCol
   g_sSortSequence = sortSeq
   g_bSortRequested = TRUE
'
' User clicked the Search, Go, next, or previous button
'
ElseIf SA_IsPostBackEvent(EventArg) Then
   g_iSortCol = sortCol
   g_sSortSequence = sortSeq
   g_bSortRequested = TRUE
'
' Unknown event source
Else
   ' Handle error here
End IF

End Function

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


SA_ServeFailurePage

This function serves an error page and should be used when an unrecoverable error is encountered.

SA_ServeFailurePage(
ByVal Message
)

Parameters

Message
Error message to be displayed.

Return Values

None.

Remarks

The SA_ServeFailurePage function will display the error message in a message style page.

The following code example uses the SA_ServeFailurePage function to display a page that indicates there has been a failure.

Call SA_ServeFailurePage("Unexpected error in Chime Settings Wizard")

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_ServeOnClickButton

This function creates a button that, when clicked, will invoke a JavaScript function.

SA_ServeOnClickButton(
ByVal Caption,
ByVal Image,
ByVal OnClickFn,
ByVal iWidth,
ByVal iImageWidth,
ByVal Attributes
)

Parameters

Caption
Caption for the button.
Image
Image for the button.
OnClickFn
JavaScript function that is invoked when the button is clicked. This must be a syntactically correct JavaScript function call–see the example below.
iWidth
Optional width of the button. The width should be specified in pixels. If no width is specified, the button will use enough space to show the caption and text.
iImageWidth
Optional width of the button image. If no width is specified, the actual width of the image will be used.
sButtonAttr
Optional additional HTML tag attributes as may be appropriate for a button, such as DISABLED.

Return Values

None.

Remarks

The following code sample illustrates how to use this function.

Call SA_ServeOnClickButton("Add", "images/users32.gif",_
                           "AddUserFunction()",_
                           100, 50, "DISABLED" )

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_ServeOpenPageButton

This function creates an image button that allows you to open the specified page type.

SA_ServeOpenPageButton(
ByVal enPageType,
ByVal sURL,
ByVal sReturnURL,
ByVal sPageTitle,
ByVal sButtonCaption,
ByVal sButtonImage,
ByVal iButtonWidth,
ByVal iButtonImageWidth,
ByVal sButtonAttr
)

Parameters

enPageType
Specifies the type of page to be opened.
Page type | Description
PT_AREA | Opens an area page
PT_PROPERTY | Opens a property page
PT_TABBED | Opens a tabbed property page
PT_WIZARD | Opens a wizard page
sURL
Uniform Resource Locator (URL) of page to open.
sReturnURL
Return URL.
sPageTitle
Title for the page to be opened. Only applicable to PT_PROPERTY and PT_TABBED.
sButtonCaption
Button caption.
sButtonImage
Button image.
iButtonWidth
Optional width of a button. The width should be specified in pixels. If zero width is specified, the button will use enough space to show the caption and text.
iButtonImageWidth
Optional width of a button image. If zero width is specified, the actual width of the image will be used.
sButtonAttr
Optional additional HTML tag attributes for a button, such as DISABLED.

Return Values

None.

Remarks

The following code sample illustrates how to use this function.

Call SA_ServeOpenPageButton( PT_PROPERTY,_
                          "sample/template_prop3.asp",_
                          Request.QueryString("ReturnURL"),_
                          "Confirm format of disk",_
                          "Format",_
                          "images/alert_gif",_
                          100, 50, "")

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_ServeResourceStatus

This function is used by resource pagelets to display status information. Resource pagelets are displayed on the appliance status page.

SA_ServeResourceStatus(
ByVal sImage,
ByVal sCaption,
ByVal sHoverText,
ByVal sURL,
ByVal sURLTarget,
ByVal sStatusInfo
)

Parameters

sImage
Image to be displayed for the resource. Can be blank.
sCaption
Caption of the resource.
sHoverText
Hover text for the resource. Can be blank.
sURL
Resource details information page, which is a clickable link. Can be blank.
sURLTarget
Optional target for the clickable link. Specify an empty string ("") to use the default target frame, which is the lower-center IFRAME on the appliance status page. If you want to have the resource details open a new page, you can specify a target with this parameter. For more information, see the TARGET attribute of the HTML <A> tag.
sStatusInfo
Status information text indicating a brief summary of the status of this resource.

Return Values

None.

Remarks

The following code sample illustrates how to use this function.

Call SA_ServeResourceStatus("images/printer.gif",_
                          "Active",_
                            "printer/printer_details.asp",_
                            "",_
                            "Printing document <xxxxxx>")

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_ServeRestartingPage

This function serves a page that indicates that the server appliance is currently unavailable, restarting, or shutting down. This function does not restart the server appliance.

SA_ServeRestartingPage(
ByVal strOption,
ByVal sInitialWait,
ByVal sRetryWait,
ByVal strRsrcDLL,
ByVal sTitleRID,
ByVal sMessageRID
)

Parameters

strOption
Specifies one of the optional standard restart options, as shown in the following table. If one of these standard options is specified, strRsrcDLL, sTitleRID, and sMessageRID do not need to be specified and SA_DEFAULT can be specified.
Option | Description
Shutdown | The server appliance will perform a shutdown.
Restart | The server appliance will perform a restart.
sInitialWait
Time (in milliseconds) that this page will wait before checking to determine whether the appliance has completed a restart.
sRetryWait
Optional. Time (in milliseconds) that, following the initial delay, this page will wait before attempting to reconnect to the server appliance while a restart is in progress. If this is not specified, the default value indicated by the registry key HKLM\SOFTWARE\Microsoft\ServerAppliance\WebFramework\RestartRetryDelay is used.
strRsrcDLL
Optional. String resource dynamic-link library (DLL) that contains string message text for the sTitleRID and sMessageRID parameters.
sTitleRID
Optional title resource identifier for the title that should be used for this page if the restarting option is not one of the standard options.
sMessageRID
Optional message resource identifier for the message that should be used for this page if the restarting option is not one of the standard options.

Return Values

None.

Remarks

The following code sample illustrates how to use this function.

'
'Show the restarting page, wait the default amount of time before
'checking for the server appliance to come back up
'and then check at the default interval.
'
Call SA_ServeRestartingPage("Restarting", "SA_DEFAULT", "SA_DEFAULT", _
                            SA_DEFAULT, SA_DEFAULT, SA_DEFAULT)

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_SetActiveTabPage

This function sets the active tab in a tabbed property page. Use this function if you want to set a tab other than the first tab as the active tab. This might be useful if you wanted to display an error message pertaining to input on a particular tab.

SA_SetActiveTabPage(
ByRef PageIn,
ByVal iTabNumber
)

Parameters

PageIn
[in] Reference to the page object.
iTabNumber
[out] ID number of the tab to make active. This is the same ID that is returned by the SA_AddTabPage function.

Return Values

gc_ERR_SUCCESS
If the active tab was changed.
SA_ERROR_INVALIDPAGE
The PageIn parameter is invalid.

Remarks

The following code sample illustrates how to use this function.

Public Function OnSubmitPage(ByRef oPageIn, ByRef oEventArg)
OnSubmitPage = TRUE
If ( Ucase(Request.Form("fldBackupDisk")) = "C:" ) Then
   Call SA_SetErrMsg("Can't backup the boot drive.")
   Call SA_SetActiveTabPage(oPageIn, g_iTabBackupDisk)
   OnSubmitPage = FALSE
End If
'
' Schedule backup

End Function

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_SetErrMsg

This function sets the current error message to be displayed in a designated area of the page.

SA_SetErrMsg(
ByVal Message
)

Parameters

Message
Error message to be displayed.

Return Values

None.

Remarks

The SA_SetErrMsg function sets the error message to be displayed on the current page of a wizard or property page.

The following code example uses the SA_SetErrMsg function to set the error message.

SA_SetErrMsg L_INVALIDDATETIME_ERRORMESSAGE

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_SetGenericMsg

This function sets the current general-purpose message that is displayed in a designated area of the page.

SA_SetGenericMsg(
ByVal Message,
ByVal MsgType
)

Parameters

Message
General message to be displayed.
MsgType
Type of message to be displayed. This determines the icon displayed next to the message. MsgType can be set to any of the following values:
  • MSG_TYPE_INFORMATION
  • MSG_TYPE_WARNING
  • MSG_TYPE_ERROR

Return Values

None.

Remarks

The SA_SetGenericMsg function displays a message on the current page of a wizard or property page.

The following code example uses the SA_SetGenericMsg function to set the message.

If Request.QueryString("error")=0 then
          SA_SetGenericMsg L_NEW_CLIENT_GROUPS_DISABLED, MSG_TYPE_INFORMATION
     ElseIf Request.QueryString("error")=1 then
          SA_SetGenericMsg L_NEW_CLIENT_GROUPS_DISABLED, MSG_TYPE_WARNING
     ElseIf Request.QueryString("error")=2 then
          SA_SetGenericMsg L_NEW_CLIENT_GROUPS_DISABLED, MSG_TYPE_ERROR
End If

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 | None | inc_framework.asp | None

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM). Some devices might not support this function.


SA_SetPageRefreshInterval

This function sets the page auto-refresh interval for either a pagelet or an area page. It is used to cause the page to automatically refresh at the specified interval.

SA_SetPageRefreshInterval(
ByRef PageIn,
ByVal iInterval
)

Parameters

PageIn
Reference to the page object.
iInterval
Time in seconds.

Return Values

SA_NO_ERROR
The call succeeded. No errors occurred.
SA_ERROR_INVALIDPAGE
The PageIn parameter is invalid.

Remarks

The following code sample illustrates how to use this function.

'
' Set the page auto refersh to 30 seconds
'
Call SA_SetPageRefreshInterval(page, 30)

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_ShowPage

This function shows the specified page. Calling this function will cause the Web framework to initiate the sequence that will create and render the Web page.

SA_ShowPage(
ByRef PageIn
)

Parameters

PageIn
Reference to the page object.

Return Values

SA_NO_ERROR
The page was created.
SA_ERROR_INVALIDARG
The PageIn parameter is invalid.
SA_ERROR_INVALIDPAGE
The PageIn parameter is invalid.

Remarks

The following code sample illustrates how to use this function.

Dim retCode
Dim page

retCode = SA_ShowPage(page)
If (retCode <> SA_NO_ERROR) Then
    ' Handle error
End If

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


SAI_GetPageKey

This function obtains a key associated with the current user for this session and stores that key in the Session object. If the key does not exist, the function creates a new key. This key is used to verify that a hyperlink or input from a form is from a Web UI framework ASP page.

SAI_GetPageKey()

Parameters

None.

Return Values

The key associated with the current user for this session.

Remarks

The following code example illustrates how to use this function to obtain a key and transfer it to a form.

<FORM>

   <INPUT TYPE="hidden" NAME="<%=SAI_FLD_PAGEKEY%>" VALUE="<%=SAI_GetPageKey()%>">

</FORM>

In the following example, the SAI_GetPageKey function is used in an anchor tag to validate that the requesting page is part of the administration site and is included in the current user session.

<A HREF="/admin/samplepage.asp?<%=SAI_FLD_PAGEKEY%>=<%=SAI_GetPageKey()%>&otherarg=1">click here</A>

Finally, this example shows how to pass the value of SAI_FLD_PAGEKEY to the SA_MungeURL function.

<SCRIPT LANGUAGE="Javascript">
    function GoSomewhere()

    {

        var strURL = g_strDestinationURL;

        strURL = SA_MungeURL(strURL, SAI_FLD_PAGEKEY, g_strSAIPageKey);
        // These last two arguments are client-side variables declared by inc_pagekey.asp.

        top.location.href = strURL;

    }

</SCRIPT>

It is not necessary to call SAI_GetPageKey when constructing a URL to pass to a Web UI framework function, such as setting the URL for an Object/Task Selector task or calling SA_ServeOnClickButton. SAI_GetPageKey is required only when linking directly from one add-in page to another within the Web UI framework. Do not call SAI_GetPageKey when linking to a page outside the Administration web site (for example, to a page on the World Wide Web) because the page will not be able to use the page key, and the key will be sent on the network in plain text, creating a security risk.

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 | None | inc_pagekey.asp | None

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM). Some devices might not support this function.


Object/Task Selector Routines

Server-Side ASP Functions

Routine | Description
OnPagingNotify | Used in determining which page of table data should be served in the OnServeAreaPage event.
OnSearchNotify | Occurs whenever the user has changed the search criteria and pressed the GO button.
OnSortNotify | Used to save the sort criteria information, which will be used when serving the page.
OTS_AddTableColumn | Adds a column to the table.
OTS_AddTableRow | Adds a row to the table.
OTS_AddTableTask | Adds a task to the table.
OTS_CreateColumn | Creates a column for the table.
OTS_CreateColumnEx | Creates a column for the table, specifying the maximum width of text.
OTS_CreateTable | Creates the Object/Task Selector (OTS) table.
OTS_CreateTask | Creates a task for the table.
OTS_CreateTaskEx | Creates a dynamically enabled task for the table.
OTS_EnablePaging | Enables the paging function for the Object/Task Selector.
OTS_EnableAutoInit | Disables the default behavior of single-selection Object/Task Selector tables.
OTS_GetTablePKeyName | Gets the name of the primary key query string parameter.
OTS_GetTableSelection | Gets the key value for a selected object in an OTS page.
OTS_GetTableSelectionCount | Gets the number of selected objects on an OTS page.
OTS_ServeTable | Renders the table in the response stream.
OTS_SetPagingRange | Sets the paging control values.
OTS_SetTableMultiselection | Enables the multiselection mode.
OTS_SetTablePKeyName | Sets the name of the primary key query string parameter.
OTS_SetTableRow | Sets a specific row in the table. See also OTS_SetTableRowCount.
OTS_SetTableRowCount | Sets the number of rows in the table (optional).
OTS_SetTableSortCriteria | Sets the criteria used to sort a presorted table.
OTS_SetTableTasksTitle | Sets the tasks section title.
OTS_SetTaskEnabled | Enables a task. This is a Web framework client-side helper function that is used in conjunction with custom task activation functions.
OTS_SortTable | Sorts the table.

See Also

Web Framework Routines and Events, Client-Side Routines, Debugging Routines, Utility Routines


OnPagingNotify

This event occurs when the user clicks a page navigation button in the Object/Task Selector (OTS). This event occurs before the OnServeAreaPage event.

OnPagingNotify(
ByRef PageIn,
ByRef EventArgIn,
ByVal sPageAction
ByVal iPageMin,
ByVal iPageMax,
ByVal iPageCurrent
)

Parameters

PageIn
Reference to the page object.
EventArgIn
Reference to the event argument, which contains additional information regarding the event.
sPageAction
Page navigation action, which will be a string value of either NEXT or PREV.
iPageMin
Minimum page number.
iPageMax
Maximum page number.
iPageCurrent
Current page number.

Return Values

This event always returns a TRUE value.

Timing

When a user clicks a page navigation button in the OTS. For OTS tables that contain a large number of rows, it is often more efficient to break the table into a series of pages, each containing a subset of the table. This event signals a user request view another page of table data.

Remarks

Use this event to save the page change action of NEXT or PREV so it can be used in determining which page of table data should be served in the OnServeAreaPage event.

The following code sample illustrates how to use this event handler.

Public Function OnPagingNotify(ByRef PageIn, _
                               ByRef EventArg, _
                               ByVal sPageAction, _
                               ByVal iPageMin, _
                               ByVal iPageMax, _
                               ByVal iPageCurrent)
OnPagingNotify = TRUE
g_bPagingInitialized = TRUE
'
' User clicked either page Next or page Previous
'
If SA_IsChangeEvent(EventArg) Then
g_bPageChangeRequested = TRUE
g_sPageAction = CStr(sPageAction)
g_iPageMin = iPageMin
g_iPageMax = iPageMax
g_iPageCurrent = iPageCurrent
'
' User clicked a column sort or the Go button
ElseIf SA_IsPostBackEvent(EventArg) Then
g_bPageChangeRequested = FALSE
g_sPageAction = CStr(sPageAction)
g_iPageMin = iPageMin
g_iPageMax = iPageMax
g_iPageCurrent = iPageCurrent
'
' Unknown event source
Else
' Handle error here
End IF
End Function

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


OnSearchNotify

This event occurs when the user has changed the search criteria and has clicked the search Go button, when the user requests a table column sort, or when the user presses the page Next or page Previous button.

It is fired before the OnServeAreaPage event.

OnSearchNotify(
ByRef PageIn,
ByRef EventArgIn,
ByVal sItem,
ByVal sValue
)

Parameters

PageIn
Reference to the page object.
EventArgIn
Reference to the event argument, which contains additional information regarding the event.
sItem
Item that should be searched. In the case of the Object/Task Selector table, this is the column number, starting from zero (0), of the column that has been selected.
sValue
Value that should be searched for.

Return Values

This event always returns TRUE.

Remarks

This event is fired either as a result of a change to the search criteria or in response to a post-back event, which has been caused by either a paging change or a sort request.

Use this event to save the search criteria information, which will be used when serving the page.

This event is applicable to area pages that contain an Object/Task Selector. The following code sample illustrates how to use this event handler.

Public Function OnSearchNotify(ByRef PageIn, ByRef EventArg, _
                               ByVal sItem, ByVal sValue)
OnSearchNotify = TRUE
g_iSearchCol = Int(sItem)
g_sSearchColValue = CStr(sValue)

If (TRUE = SA_IsChangeEvent(EventArg)) Then
          g_bSearchChanged = TRUE
     Else
          g_bSearchChanged = FALSE
     End if

End Function

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


OnSortNotify

This event occurs when the user clicks a sort-enabled Object/Task Selector (OTS) column heading. Use this event to save the sort criteria information, which will be used when serving the page.

OnSortNotify(
ByRef oPageIn,
ByRef oEventArg,
ByVal iSortCol,
ByVal sSortSeq
)

Parameters

oPageIn
Reference to the page object.
oEventArg
Reference to the event argument, which contains additional information regarding the event.
iSortCol
Zero-based index number of the column that was clicked.
sSortSeq
Sort sequence: A for ascending D for descending.

Return Values

This event always returns a TRUE value.

Remarks

The timing occurs when a user has requested a column sort by clicking one of the OTS column headings.

The following code sample illustrates how to use this event handler.

Public Function OnSortNotify(ByRef oPageIn, _
                             ByRef oEventArg, _
                             ByVal iSortCol, _
                             ByVal sSortSeq)
OnSortNotify = TRUE

'
' User clicked column sort
'
If SA_IsChangeEvent(oEventArg) Then
   g_iSortCol = iSortCol
   g_sSortSequence = sSortSeq
   g_bSortRequested = TRUE
'
' User clicked search Go button or clicked page next/prev button
'
ElseIf SA_IsPostBackEvent(oEventArg) Then
   g_iSortCol = iSortCol
   g_sSortSequence = sSortSeq
   g_bSortRequested = TRUE
'
' Unknown event source
Else
' Handle error here
End IF

End Function

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


OTS_AddTableColumn

This function adds a column to the table. The column must have been created using the OTS_CreateColumn or OTS_CreateColumnEx function.

OTS_AddTableColumn(
ByRef Table,
ByRef Column
)

Parameters

Table
Object/Task Selector table to which you are adding a column.
Column
Column to be added.

Return Values

Value | Description
OTS_ERR_SUCCESS | The column was successfully added to the table.
OTS_ERR_INVALID_TABLE | This is an invalid table.
OTS_ERR_INVALID_COLUMN | This is an invalid column.

Remarks

The following code sample illustrates how to use this function.

Dim ots_table
Dim ots_column
Dim retcode
'
' Create table
'
ots_table = OTS_CreateTable(SA_RESERVED,
   "These are users of the server appliance")
'
' Create column
'
ots_column = OTS_CreateColumn("Login", "left", OTS_COL_FLAG_KEY)
'
' Add column to table
'
retcode = OTS_AddTableColumn(ots_table, ots_column)
If (retcode <> OTS_ERR_SUCCESS) Then
    '
    'OTS_AddTableColumn failed...
    '
End If

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


OTS_AddTableRow

This function adds a row of data to the table. The row must be an array type and all rows must be the same size or contain the same number of elements.

OTS_AddTableRow(
ByRef Table,
ByRef Array
)

Parameters

Table
Object/Task Selector table to which you are adding a row.
Array
Array of data for the new row.

Return Values

Value | Description
OTS_ERR_SUCCESS | The row was successfully added to the table.
OTS_ERR_INVALID_TABLE | This is an invalid table.
OTS_ERR_ROW_NOT_ARRAYTYPE | The Array parameter is not a valid array.

Remarks

The following code sample illustrates how to use this function.

Function SampleAddUsers(ByRef ots_table, ByVal DomainName)
    Dim Container
    Dim User
    Dim retcode
    Dim userCount

    Set Container = GetObject("WinNT://"+DomainName)
    Container.Filter = Array("User")

    userCount = 0
    For Each User in Container
        retcode = OTS_AddTableRow(ots_table, Array(User.Name, User.FullName))
        If (retcode = OTS_ERR_SUCCESS) Then
            userCount = userCount + 1
        End If
    Next

    SampleAddUsers = userCount
End Function

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


OTS_AddTableTask

This function adds a task to the table. The task must have been created using the OTS_CreateTask or OTS_CreateTaskEx function.

OTS_AddTableTask(
ByRef Table,
ByRef Task
)

Parameters

Table
Object/Task Selector table to which you are adding a task.
Task
Task to be added.

Return Values

Value | Description
OTS_ERR_SUCCESS | The task was successfully added to the table.
OTS_ERR_INVALID_TABLE | This is an invalid table.
OTS_ERR_INVALID_TASK | This is an invalid task.

Remarks

The following code sample illustrates how to use this function.

Dim ots_table
Dim ots_task
Dim retcode
'
' Create table
'
ots_table = OTS_CreateTable(SA_RESERVED, "These are users of the server appliance")
'
' Create task
'
ots_task = OTS_CreateTask("Set Password", _
                          "Change the password for a user",_
                          "users/user_setpassword.htm")
'
' Add task to table
'
retcode = OTS_AddTableTask(ots_table, ots_task)
If (retcode <> OTS_ERR_SUCCESS) Then
    '
    'AddTableTask failed...
    '
End If

The maximum length of a URL is 2000 characters. Normally, this is not a problem when using the Web UI framework. This limit can be reached, however, if Object/Task Selectors are nested too deeply, that is, if there are several tasks in sequence that link to an area page containing another Object/Task Selector instead of operating on an item selected in the Object/Task Selector table. This is because the URL of each page opened by an Object/Task Selector task contains the URL of the task that opened it.

Before calling this function to add a task to a multiselection Object/Task Selector, you must ensure that the task tabs will be properly displayed when the user clicks the tab. To do this, use the following routine calls before calling OTS_AddTableTask:

Call SA_MungeURL(strURL, "Tab1", GetTab1())
Call SA_MungeURL(strURL, "Tab2", GetTab2())

The strURL argument is the URL of the task page displayed when the user clicks the task tab.

Do not use these routine calls when adding a task to a single-selection Object/Task Selector.

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


OTS_CreateColumn

This function creates a column for the table. Each table can contain one or more columns of data. Use this function to create a column and then pass the column returned by this function to the OTS_AddTableColumn function to add the new column to the table.

OTS_CreateColumn(
ByVal colHeading,
ByVal colAlign,
ByVal colFlags
)

Parameters

colHeading
Column heading.
colAlign
Alignment attribute: left, center, or right.
colFlags
The following table shows the available attribute flags.
Flag | Description
OTS_COL_HIDDEN | The column is hidden and not displayed.
OTS_COL_KEY | The column contains a key that uniquely identifies this row.
OTS_COL_SORT | The column should be used as a sort key if the table is sorted.
OTS_COL_SEARCH | The column should be used as a search column if searching is enabled.

Return Values

The return value is a reference to a valid column object that can then be used in the OTS_AddTableColumn function.

Remarks

The following code sample illustrates how to use this function.

Dim ots_table
Dim ots_column
Dim retcode
'
' Create Table
'
ots_table = OTS_CreateTable("Appliance Users", "These are users of the server appliance")
'
' Create Column
'
ots_column = OTS_CreateColumn("Login", "left", OTS_COL_FLAG_KEY)
'
' Add column to table
'
retcode = OTS_AddTableColumn(ots_table, ots_column)
If (retcode <> OTS_ERR_SUCCESS) Then
    '
    'OTS_AddTableColumn failed...
    '
End If

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


OTS_CreateColumnEx

This function creates a column for the table and allows you to specify the maximum number of text characters for the column. Text cells in the column that exceed the specified maximum are truncated. The full cell text can be viewed by hovering over the cell.

Each table can contain one or more columns of data. Use this function to create a column and then pass the column returned by this function to the OTS_AddTableColumn function to add the new column to the table.

OTS_CreateColumnEx(
ByVal colHeading,
ByVal colAlign,
ByVal colFlags,
ByVal iColWidth
)

Parameters

colHeading
Heading for the column.
colAlign
Column alignment attribute: left, center, or right.
colFlags
The following table shows the available column attribute flags.
Flag | Description
OTS_COL_HIDDEN | The column is hidden and not displayed.
OTS_COL_KEY | The column contains a key that uniquely identifies this row.
OTS_COL_SORT | The column should be used as a sort key if the table is sorted.
OTS_COL_SEARCH | The column should be used as a search column if searching is enabled.
iColWidth
Maximum number of text characters for this column. Use zero (0) for no limit.

Return Values

The return value is a reference to a valid column object that can then be passed in the OTS_AddTableColumn function.

Remarks

The following code sample illustrates how to use this function.

Dim ots_table
Dim ots_column
Dim retcode
'
' Create table
'
ots_table = OTS_CreateTable("Appliance Users", "These are users of the server appliance")
'
' Create column, maximum text width is 20 characters
'
ots_column = OTS_CreateColumnEx("Login", "left", OTS_COL_KEY, 20)
'
' Add column to table
'
retcode = OTS_AddTableColumn(ots_table, ots_column)
If (retcode <> OTS_ERR_SUCCESS) Then
    '
    'OTS_AddTableColumn failed...
    '
End If

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


OTS_CreateTable

This function creates a new Object/Task Selector table.

OTS_CreateTable(
ByVal Reserved,
ByVal Description
)

Parameters

Reserved
Reserved for future use.
Description
Description text for the Object/Task Selector table.

Return Values

The return value is a reference to the Object/Task Selector table object.

Remarks

This function should only be called once per page. Having multiple Object/Task Selector tables on a page is not supported.

After creating the Object/Task Selector table, you must also call the OTS_AddTableColumn, OTS_AddTableTask, and OTS_ServeTable functions to ensure that the table is properly rendered.

The following code sample illustrates the OTS_CreateTable function.

'
' Create Appliance Users table
'
table = OTS_CreateTable("","These are users of the server appliance")

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


OTS_CreateTask

This function creates a new task. The task object that is returned can then be added to the Object/Task Selector table using the OTS_AddTableTask function.

OTS_CreateTask(
ByVal Label,
ByVal Description,
ByVal Link,
ByVal PageType
)

Parameters

Label
Label for the task.
Description
Description of the task.
Link
Hyperlink to be used when the task is selected.
PageType
The following table shows the types of pages that can be opened.
Variable | Description
OTS_PT_PROPERTY | Opens a standard property page.
OTS_PT_TABBED_PROPERTY | Opens a multitabbed property page.
OTS_PT_WIZARD | Opens a wizard page.
OTS_PT_AREA_PAGE | Opens an area page.
OTS_PT_NEW_WINDOW | Opens a page in a new browser window.
OTS_PT_RAW | Opens a page in raw mode. The URL is not updated with navigation context, it is simply opened in a new browser window.

Return Values

The return value is a reference to a valid task that can be passed to the OTS_AddTableTask function.

Remarks

The following code sample illustrates how to use this function.

Dim ots_table
Dim ots_task
Dim retcode
'
' Create table
'
ots_table = OTS_CreateTable(SA_RESERVED,
                            "These are users of the server appliance")
'
' Create task
'
ots_task = OTS_CreateTask("Set Password", _
                          "Change the password for a user",_
                          "users/user_setpassword.htm",_
                          OTS_PT_PROPERTY)
'
' Add task to table
'
retcode = OTS_AddTableTask(ots_table, ots_task)
If ( retcode <> OTS_ERR_SUCCESS) Then
    '
    'AddTableTask failed...
    '
End If

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


OTS_CreateTaskEx

This function creates a new task that can be dynamically enabled. The task object that is returned can then be added to the Object/Task Selector table using the OTS_AddTableTask function.

OTS_CreateTaskEx(
ByVal Label,
ByVal Description,
ByVal Link,
ByVal PageType,
ByVal TaskFn
)

Parameters

Label
Label for the task.
Description
Description of the task.
Link
Hyperlink to be used when the task is selected.
PageType
The following table shows the types of pages that can be opened.
Variable | Description
OTS_PT_PROPERTY | Opens a standard property page.
OTS_PT_TABBED_PROPERTY | Opens a tabbed property page.
OTS_PT_WIZARD | Opens a wizard page.
OTS_PT_AREA | Opens a page.
OTS_PT_NEW_WINDOW | Opens a page in new browser window.
OTS_PT_RAW | Opens a page in raw mode. The URL is not updated with navigation context, it is simply opened in a new browser window.
TaskFn
Task activation function. This parameter is the name of the JavaScript function that is invoked to activate the task. This function is called by the Web framework when an item has been changed. The function prototype for this function is Function TaskFN(sMessage, iTaskNo, iItemNo).

The following table shows the task activation functions in the Web UI framework.

Function | Description
OTS_TaskAny | Activates the task if one or more items are selected.
OTS_TaskOne | Activates the task if only one item is selected.
OTS_TaskAlways | Always activates the task. Use only for tasks that do not require or use an object, such as New.

Return Values

Reference to a valid task that can be passed to the OTS_AddTableTask function.

Remarks

The following code sample illustrates how to use this function. For a complete example, see the Object/Task Selector sample file Sample_ots_dynamic_tasks.asp

Dim task1
Dim task2
Dim task3
'
' Task that is always activated
'
task1 = OTS_CreateTaskEx("New...", _
              "Add a new user",_
              "users/user_new.asp",_
              OTS_PT_PROPERTY,_
              "OTS_TaskAlways")
'
' Task that is activated if at least one item is selected
'
task2 = OTS_CreateTaskEx("Delete", _
              "Delete a user",_
              "users/user_delete.asp",_
              OTS_PT_PROPERTY,_
              "OTS_TaskAny")
'
' Task that is activated if one and only one item is selected
'
task = OTS_CreateTaskEx("Set Password", _
              "Change the password for a user",_
              "users/user_setpassword.asp",_
              OTS_PT_PROPERTY,_
              "OTS_TaskOne")

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


OTS_EnableAutoInit

This function can be used to disable the default behavior of single-selection Object/Task Selector tables. For single-selection Object/Task Selector tables, the default behavior when returning from a task page is for the Object/Task Selector table to automatically reselect the item that was previously selected. If the user selects an object, or row, and then clicks a task to manipulate that object's properties, that object will be reselected when the task is completed and the Object/Task Selector table is redisplayed.

Normally the default behavior of the Object/Task Selector is sufficient for handling this task. In the event that the default behavior is not sufficient, the OTS_EnableAutoInit function can be used to disable the default behavior. Calling this function with the bEnable parameter set to FALSE will disable the default behavior.

OTS_EnableAutoInit(
ByRef Table,
ByVal bEnable
)

Parameters

Table
Object/Task Selector table being modified.
bEnable
The default is TRUE. Set to FALSE to disable the default behavior.

Return Values

OTS_ERR_SUCCESS
The column was successfully added to the table.
OTS_ERR_INVALID_TABLE
This is an invalid table.

Remarks

If Auto Init is disabled using this function, client-side JavaScript code will need to be written to perform initialization of the Object/Task Selector table. You must call the OTS_Init(<selection>) function to properly complete initialization of the Object/Task Selector table.

The following code sample illustrates how to use this function.

Dim rc

rc = OTS_EnableAutoInit(Table, FALSE)

If ( rc <> SA_NO_ERROR ) Then
    '
    ' Unexpected error, must have been an invalid Table parameter
    '
End If

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


OTS_EnablePaging

Enables the paging option for the Object/Task Selector. For tables that are very large, the paging option provides a virtual paging mechanism. Each page can contain a subset of the complete table. The paging option provides UI navigation buttons and event callback routines to the Web page to help manage paging through a large table.

OTS_EnablePaging(
ByRef Table,
ByVal bEnable
)

Parameters

Table
The table
bEnable
Set to TRUE to enable the paging option, FALSE to disable the option. The default is FALSE.

Return Values

OTS_ERR_SUCCESS
Option was successfully executed.
OTS_ERR_INVALID_TABLE
Invalid table

Remarks

The following code sample illustrates how to use this function.

Dim rc
rc = OTS_EnablePaging(Table, TRUE)
If ( rc <> SA_NO_ERROR ) Then
     '
     ' Unexpected error, must have been an invalid table parameter
     '
End If

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


OTS_GetTablePKeyName

This function gets the name of the primary key query string parameter.

OTS_GetTablePKeyName(
ByRef Table,
ByRef pKeyName
)

Parameters

Table
Object/Task Selector table.
pKeyName
Output variable to receive the name of the primary key query string parameter name.

Return Values

OTS_ERR_INVALID_TABLE
The table is invalid
OTS_ERR_SUCCESS.
The table is valid.

Remarks

The default value for the primary key query string parameter is PKey.

The following code sample illustrates how to use this function.

rc = OTS_GetTablePKeyName(Table, strPKeyName)

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


OTS_GetTableSelection

This function retrieves the object key for an object selected in the Object/Task Selector (OTS). OTS tasks should use this function to retrieve the value of an object key.

OTS_GetTableSelection(
ByVal sParamName,
ByVal iIndex,
ByRef sValue
)

Parameters

sParamName
Parameter name for the object key, which is blank for the default value of PKEY.
iIndex
Index number of the selected item, starting at 1.
sValue
Output parameter that receives the value of the selected object key.

Return Values

TRUE
The specified object was found.
FALSE
The specified object was not found.

Remarks

The following code fragment illustrates how to use this function. For a complete example showing proper usage see the following Object/Task Selector samples: Sample_change.asp, Sample_delete.asp, or Sample_listing.asp.

   Dim x
  Dim itemCount
  Dim itemValue

  itemCount = OTS_GetTableSelectionCount("")

  For x = 1 to itemCount
    If (OTS_GetTableSelection("", x, itemKey)) Then
    '
    'Process the selected item
    '
    End If
  Next

If the table has multiselect mode enabled, this function can return incorrect results if any task in the table was created by calling the OTS_CreateTaskEx function with the TaskFn argument set to OTS_TaskAlways.

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


OTS_GetTableSelectionCount

This function gets a count of the objects that were selected on the OTS page. OTS tasks should use this function to determine how many objects were selected when the user clicked a task.

OTS_GetTableSelectionCount(
ByVal sParamName
)

Parameters

sParamName
Parameter name for object key, with a default of PKEY.

Return Values

Returns the number of table selections.

Remarks

The following code fragment illustrates how to use this function. For a complete example showing proper usage see the following Object/Task Selector samples: Sample_change.asp, Sample_delete.asp, or Sample_listing.asp.

  Dim x
  Dim itemCount
  Dim itemValue
  itemCount = OTS_GetTableSelectionCount("")
  For x = 1 to itemCount
    If (OTS_GetTableSelection("", x, itemKey)) Then
    '
    'Process the selected item
    '
    End If
  Next

If the table has multiselect mode enabled, this function can return incorrect results if any task in the table was created by calling the OTS_CreateTaskEx function with the TaskFn argument set to OTS_TaskAlways.

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


OTS_ServeTable

This function sends the table to the output response stream, creating the HTML output that will be used to render the table.

OTS_ServeTable(
ByRef Table
)

Parameters

Table
Object/Task Selector table to be rendered.

Return Values

OTS_ERR_SUCCESS
The table was rendered successfully.
OTS_ERR_INVALID_TABLE
This is an invalid table.

Remarks

The following code sample illustrates how to use this function.

Public Function OnServeAreaPage(ByRef PageIn, ByRef EventArg)

Dim table
'
' Create the table
table = OTS_CreateTable(SA_RESERVED, "OTS Template")

'
' Create the column and add it to the table
Call OTS_AddTableColumn(table, OTS_CreateColumnEx( "Col1", "left", OTS_COL_KEY, 15 ))

'
' Create the column and add it to the table
Call OTS_AddTableColumn(table, OTS_CreateColumnEx( "Col2", "left", 0, 40))

'
' Set Tasks section title
Call OTS_SetTableTasksTitle(table, "Tasks")

'
' Add the tasks associated with user objects
Call OTS_AddTableTask( table, OTS_CreateTaskEx("Task 1", _
        "Example Task 1", _
        "sample/template_property.asp",_
        OTS_PT_PROPERTY,_
        "OTS_TaskAlways") )

Call OTS_AddTableTask( table, OTS_CreateTaskEx("Task 2", _
        "Example Task 2", _
        "sample/template_tabbed.asp",_
        OTS_PT_TABBED_PROPERTY,_
        "OTS_TaskAny") )
'
' Add data to table
Dim x
For x = 1 to 20
    Call OTS_AddTableRow( table, Array( "Row " + CStr(x), "Description of row "+ CStr(x) ))
Next

'
' Enable multiselection mode
Call OTS_SetTableMultiSelection(Table, TRUE)

'
' Send table to the response stream
'
Call OTS_ServeTable(table)

OnServeAreaPage = TRUE
End Function

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


OTS_SetPagingRange

This function sets the paging range values for the virtual paging control. This control is similar in concept to a scroll bar or a spinner control. It is programmed with a minimum, maximum, and current value and the control provides a UI to allow the user to page through the data series rendered by the table.

For tables that are very large, the paging option provides a virtual paging mechanism. Each page can contain a subset of the complete table. The paging option provides UI navigation buttons and callback routines to the Web page to help manage paging through a large table.

OTS_SetPagingRange(
ByRef Table,
ByVal iMin,
ByVal iMax,
ByVal iCurrent
)

Parameters

Table
Object/Task Selector table for which the paging range is being set.
iMin
Minimum page number.
iMax
Maximum page number.
iCurrent
Current page number.

Return Values

OTS_ERR_SUCCESS
The option was successfully implemented.
OTS_ERR_INVALID_TABLE
This is an invalid table.

Remarks

This function only tells the framework how many pages to make for the control. It does not filter the data in the table to only display data for each page.

Consider the following scenario:

The developer wants to create a table that shows 100 user accounts. The application developer creates the table, creates the columns, and adds 100 rows of user accounts. The developer then tells the framework to enable paging and to create 10 pages.

The framework is not going to automatically show 10 users per page. Instead, each page will show all 100 users.

The correct way to use this function is to create the table and the columns, determine the page you are on, determine which records are valid for this page and add those rows, and then tell the framework to use paging and that you have 10 pages.

For an example showing proper usage, see sample file sample_ots4.asp.

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


OTS_SetTableMultiselection

This function enables the multiselection mode for the table.

OTS_SetTableMultiselection(
ByRef Table,
ByVal bEnable
)

Parameters

Table
Reference to the table.
bEnable
TRUE to enable, FALSE to disable.

Return Values

OTS_ERR_SUCCESS
The multiselection mode was enabled.
OTS_ERR_INVALID_TABLE
This is an invalid table.

Remarks

Normally the table will use a single-selection UI model. Use this function to enable the multiselection mode.

The following code sample illustrates how to use this function.

'
' Enable multi-selection mode
'
Call OTS_SetTableMultiselection(Table, TRUE)

Before calling OTS_AddTableTask to add a task to a multiselection Object/Task Selector, you must ensure that the task tabs will be properly displayed when the user clicks the tab. To do this, use the following routine calls before calling OTS_AddTableTask:

Call SA_MungeURL(strURL, "Tab1", GetTab1())
Call SA_MungeURL(strURL, "Tab2", GetTab2())

The strURL argument is the URL of the task page displayed when the user clicks the task tab.

Do not use these routine calls when adding a task to a single-selection Object/Task Selector.

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


OTS_SetTablePKeyName

This function sets the name of the primary key query string parameter.

OTS_SetTablePKeyName(
ByRef Table,
ByVal pKeyName
)

Parameters

Table
Object/Task Selector table.
pKeyName
Input variable specifying the name of the primary key query string parameter name.

Return Values

OTS_ERR_INVALID_TABLE
The table is invalid.
OTS_ERR_SUCCESS
The table is valid.

Remarks

The parameter name should be a short, unique string with no special characters or embedded blanks. The default value for the primary key query string parameter is PKey.

The following code sample illustrates how to use this function.

rc = OTS_SetTablePKeyName(Table, strPKeyName)

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


OTS_SetTableRow

This function sets the value of a specific row in the table. The row must be an array type and all rows must be the same size and contain the same number of elements.

If the specified row does not exist, the table rows are automatically grown to add room for the new row and previous rows are preserved.

OTS_SetTableRow(
ByRef Table,
ByVal RowNumber,
ByRef Array
)

Parameters

Table
Object/Task Selector table for which you are setting a row value.
RowNumber
Row number to be set.
Array
Array of data for the row.

Return Values

OTS_ERR_SUCCESS
The row was successfully set.
OTS_ERR_ROW_NOT_ARRAYTYPE
The row is not an array type.
OTS_ERR_INVALID_TABLE
The table is invalid.

Remarks

When completing the table, the first row number must be 0 and all rows must be completed for the table to render properly.

The following code sample illustrates how to use this function.

Function SampleAddManyUsers(ByRef ots_table, ByVal expectedUpperLimit)
    Dim Container
    Dim User
    Dim retcode
    Dim userCount
    '
    ' Set expected upperbound number of rows
    '
    retcode = OTS_SetTableRowCount(ots_table, expectedUpperLimit)
    Set Container = GetObject("WinNT://"+DomainName)
    Container.Filter = Array("User")
    userCount = 0
    '
    ' Add users to table
    '
    For Each User in Container
        retcode = OTS_SetTableRow(ots_table, userCount, Array(User.Name, User.FullName))
        If (retcode = OTS_ERR_SUCCESS) Then
            userCount = userCount + 1
        End If
    Next
    '
    ' Shrink the table if necessary, do not leave empty rows
    '
    If (userCount < expectedUpperLimit) Then
        retcode = OTS_SetTableRowCount(ots_table, userCount)
    End If
    SampleAddManyUsers = userCount
End Function

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


OTS_SetTableRowCount

This function sets the number of rows expected for the table and can be used to initialize the expected number of rows for a table. This function will substantially improve performance for large tables.

This function can be used to grow or shrink the number of rows in the table. If the number of rows is increased, existing rows are preserved. If the number of rows is decreased, excess rows are removed.

OTS_SetTableRowCount(
ByRef Table,
ByVal RowCount
)

Parameters

Table
Object/Task Selector table for which you are setting the number of rows expected.
RowCount
Number of rows the table will require.

Return Values

Value | Description
OTS_ERR_INVALID_TABLE | This is an invalid table.
OTS_ERR_SUCCESS | The table rows were successfully changed.

Remarks

This function is optional and should be used in conjunction with the OTS_SetTableRow function, rather than the OTS_AddTableRow function.

The following code sample illustrates how to use this function.

Function SampleAddManyUsers(ByRef ots_table, ByVal expectedUpperLimit)
    Dim Container
    Dim User
    Dim retcode
    Dim userCount
    '
    ' Set expected upperbound number of rows
    '
    retcode = OTS_SetTableRowCount(ots_table, expectedUpperLimit)

    Set Container = GetObject("WinNT://"+DomainName)
    Container.Filter = Array("User")

    userCount = 0
    '
    ' Add users to table
    '
    For Each User in Container
        retcode = OTS_SetTableRow(ots_table, userCount, Array(User.Name, User.FullName))
        If (retcode = OTS_ERR_SUCCESS) Then
            userCount = userCount + 1
        End If
    Next

    '
    ' Shrink the table if necessary, do not leave empty rows
    '
    If (userCount < expectedUpperLimit) Then
        retcode = OTS_SetTableRowCount(ots_table, userCount)
    End If

    SampleAddManyUsers = userCount
End Function

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


OTS_SetTableSortCriteria

This function synchronizes the user interface (UI) when sorting is performed externally, without calling OTS_SortTable. The Object/Task Selector UI column headings contain a visual clue as to which column the table is sorted by and the sort sequence. If the table is sorted using the OTS_SortTable function, you do not need to use this function because the UI will be properly synchronized.

OTS_SetTableSortCriteria(
ByRef Table,
ByVal sortCol,
ByVal sortSeq
)

Parameters

Table
Object/Task Selector table.
sortCol
Index number of the column by which the table is currently sorted.
sortSeq
Sequence by which the table is sorted: A for ascending and D for descending.

Return Values

OTS_ERR_SUCCESS
The sort criteria is set correctly.
OTS_ERR_INVALID_TABLE
This is an invalid table.

Remarks

The following code sample illustrates how to use this function.

Call OTS_SetTableSortCriteria(Table, g_iSortCol, g_iSortSequence)

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


OTS_SetTableTasksTitle

This function sets the tasks section title.

OTS_SetTableTasksTitle(
ByRef Table,
ByVal sTasksTitle
)

Parameters

Table
Reference to the table.
sTasksTitle
Title to be used for the tasks section.

Return Values

OTS_ERR_SUCCESS
The tasks section title was created.
OTS_ERR_INVALID_TABLE
This is an invalid table.

Remarks

The following code sample illustrates how to use this function.

Call OTS_SetTableTasksTitle(Table, "Tasks")

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


OTS_SetTaskEnabled

This function can be used to either enable or disable an Object/Task Selector task. This is a JavaScript function (client-side) that is intended to be used in conjunction with custom task activation functions. For more information, see OTS_CreateTaskEx.

OTS_SetTaskEnabled(
ByVal iTaskNo,
ByVal bEnabled
)

Parameters

iTaskNo
Index number, zero-based, of the task to which this message refers.
bEnabled
Boolean flag. TRUE to enable task, FALSE to disable task.

Return Values

None.

Remarks

The following code sample illustrates how this function might be used in a custom task activation function. For a complete example, see the Object/Task Selector example code Sample_ots_dynamic_tasks.asp.

var iTaskOne_ItemCount = 0;
function OTS_TaskOne(sMessage, iTaskNo, iItemNo)
{
  var rc = true;

  if (sMessage == OTS_MESSAGE_BEGIN)
  {
    iTaskOne_ItemCount = 0;
  }
  else if (sMessage == OTS_MESSAGE_ITEM)
  {
  iTaskOne_ItemCount += 1;
  }
  else if (sMessage == OTS_MESSAGE_END)
  {
    if (iTaskOne_ItemCount != 1)
    {
      OTS_SetTaskEnabled(iTaskNo, false);
    }
    else
    {
      OTS_SetTaskEnabled(iTaskNo, true);
    }
  }

  return rc;
}

Requirements

Runs on | Versions | Defined in | Include | Link to
Client, JavaScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


OTS_SortTable

This function sorts the contents of the table using the specified column parameter, sortCol, and in the specified sequence, sortSeq. This function performs a string sort of the table. If a non-string sort is required, the data should be sorted externally before it is added to the table.

OTS_SortTable(
ByRef Table,
ByVal sortCol,
ByVal sortSeq,
ByRef Reserved
)

Parameters

Table
Object/Task Selector table being sorted.
sortCol
Index number of the column by which the table is currently sorted.
sortSeq
Sequence by which the table is sorted: A for ascending and D for descending.
Reserved
Reserved for future use; use constant SA_RESERVED.

Return Values

OTS_ERR_SUCCESS
The table was output successfully.
OTS_ERR_INVALID_TABLE
This is an invalid table.

Remarks

The following code sample illustrates how to use this function.

Call OTS_SortTable(Table, g_iSortCol, g_sSortSequence, SA_RESERVED)

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | ots_main.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


Error-trapping Routines

Function | Description
SA_ClearError | Clears the last error.
SA_GetLastError | Gets the last error.
SA_SetLastError | Sets the last error.


SA_ClearError

This function is called by framework functions to clear the last error code. User-written library functions should use this function to clear any outstanding errors.

SA_ClearError()

Parameters

None.

Return Values

gc_ERROR_SUCCESS
The function completed successfully.

Remarks

This function sets the last error to SA_NO_ERROR.

The following code sample illustrates how to use this function.

SA_ClearError()

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


SA_GetLastError

This function gets the error code from the last framework API call.

SA_GetLastError()

Parameters

None.

Return Values

The value set by the last error code.

Remarks

An error is indicated by any error code <> SA_NO_ERROR.

The following code sample illustrates how to use this function.

    DIM rc

    Call OTS_CreateTable(L_TABLE_CAPTION, L_TABLE_DESC)
    rc = SA_GetLastError()
    If (rc <> gc_ERROR_SUCCESS) Then
    ' Error
    Else
    ' Success
    End If

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


SA_SetLastError

This function sets the error code being returned by a function. Framework functions call this function to set the status of the call.

SA_SetLastError(
ByVal ErrorCode,
ByVal RoutineName
)

Parameters

ErrorCode
Error code to be set.
RoutineName
Name of the routine setting the error code. The routine name is recorded in the tracing error log if tracing is enabled.

Return Values

The value specified in ErrorCode.

Remarks

Web applications can use SA_GetLastError to retrieve the error code for a framework API routine. An error is indicated by any error code <> SA_NO_ERROR.

The following code sample illustrates how to use this function.

Call SA_SetLastError(OTS_ERROR_INVALIDTABLE, "OTS_GetTableRows")

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


Debugging Routines

Function | Description
SA_IsDebugEnabled | Determines whether debugging is enabled.
SA_TraceErrorOut | Writes debugging information to the HTML stream or a log file. The information is prefixed with the string "ISSUE:".
SA_TraceOut | Writes debugging information to the HTML stream or a log file.


SA_IsDebugEnabled

This function verifies whether debugging is currently enabled.

SA_IsDebugEnabled()

Parameters

None.

Return Values

The return value is the value stored in the registry entry
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ServerAppliance\WebFramework\Debug
and can be one of these values:

1
Debugging is enabled.
0
Debugging is not enabled.

Remarks

The following code sample illustrates how to use this function.

If ( SA_IsDebugEnabled() ) Then
    ' Debugging is enabled
  Else
    ' Debugging NOT enabled
  End If

For more information about using this function to debug your Web UI add-in, see Debugging.

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_TraceErrorOut

This function emits error tracing output using the current debug setting.

SA_TraceErrorOut(
ByVal sModule,
ByVal sMessage
)

Parameters

sModule
Name of the module emitting trace output.
sMessage
Message to be output.

Return Values

gc_ERROR_SUCCESS
The function completed successfully.

Remarks

The difference between this function and the SA_TraceOut function is that the error message will begin with the string ISSUE.

The following code sample illustrates how to use this function.

Call SA_TraceErrorOut("ots_addtablerow", "Invalid table object")

For more information about using this function to debug your Web UI add-in, see Debugging.

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


SA_TraceOut

This function emits tracing output using the current debug setting.

SA_TraceOut(
ByVal sModule,
ByVal sMessage
)

Parameters

sModule
Name of the module emitting trace output.
sMessage
Message to be output.

Return Values

gc_ERROR_SUCCESS
The function completed successfully.

Remarks

The following code sample illustrates how to use this function.

Call SA_TraceOut("ots_addtablerow", "Invalid table object")

For more information about using this function to debug your Web UI add-in, see Debugging.

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


Client-Side Routines

The following functions must be implemented in all client-side Web pages.

Function | Description
Init | Called by the Web framework in the onLoad event when the Web page loads.
SetData | Called by the Web framework after the ValidatePage function returns TRUE.
ValidatePage | Called by the Web framework as part of the submit processing.

Additionally, several optional client-side functions are provided for your convenience.

Function | Description
SA_DisableBack | Disables the Back button.
SA_DisableCancel | Disables the Cancel button.
SA_DisableFinish | Disables the Finish button.
SA_DisableNext | Disables the Next button.
SA_DisableOK | Disables the OK button.
SA_DisplayErr | Displays the error message on the screen.
SA_EnableBack | Enables the Back button.
SA_EnableCancel | Enables the Cancel button.
SA_EnableFinish | Enables the Finish button.
SA_EnableNext | Enables the Next button.
SA_EnableOK | Enables the OK button.
TaskFn | Prototype for the dynamic task enabling a callback function.


Init

This function, which must be implemented by the Web developer, is called by the Web framework in the onLoad event when the Web page loads.

Function Init()

Parameters

None.

Return Values

None.

Remarks

The timing occurs when the Web page first loads into the client Web browser.

The following code sample illustrates how to use this function.

function Init()
{
    // Perform initialization tasks in the web page
}

Requirements

Runs on | Versions | Defined in | Include | Link to
Client, JavaScript | Microsoft Server Appliance Kit 3.0 |  |  |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_DisableBack

This function disables the Back button.

SA_DisableBack()

Parameters

None.

Return Values

None.

Remarks

The SA_DisableBack function disables the Back button, preventing the user from using it.

Requirements

Runs on | Versions | Defined in | Include | Link to
Client, JavaScript | Microsoft Server Appliance Kit 3.0 |  |  |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_DisableCancel

This function disables the Cancel button.

SA_DisableCancel()

Parameters

None.

Return Values

None.

Remarks

The SA_DisableCancel function disables the Cancel button, preventing the user from using it.

Requirements

Runs on | Versions | Defined in | Include | Link to
Client, JavaScript | Microsoft Server Appliance Kit 3.0 |  |  |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_DisableFinish

This function disables the Finish button.

SA_DisableFinish()

Parameters

None.

Return Values

None.

Remarks

The SA_DisableFinish function disables the Finish button, preventing the user from using it.

Requirements

Runs on | Versions | Defined in | Include | Link to
Client, JavaScript | Microsoft Server Appliance Kit 3.0 |  |  |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_DisableNext

This function disables the Next button.

SA_DisableNext()

Parameters

None.

Return Values

None.

Remarks

The SA_DisableNext function disables the Next button, preventing the user from using it.

Requirements

Runs on | Versions | Defined in | Include | Link to
Client, JavaScript | Microsoft Server Appliance Kit 3.0 |  |  |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_DisableOK

This function disables the OK button.

SA_DisableOK()

Parameters

None.

Return Values

None.

Remarks

The SA_DisableOK function disables the OK button, preventing the user from using it.

Requirements

Runs on | Versions | Defined in | Include | Link to
Client, JavaScript | Microsoft Server Appliance Kit 3.0 |  |  |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_DisplayErr

This function displays the error message on the screen.

SA_DisplayErr(
ErrorMessage
)

Parameters

ErrorMessage
Text to be displayed.

Return Values

None.

Remarks

The SA_DisplayErr function displays an error message on the client browser, informing the user that there is a problem.

Requirements

Runs on | Versions | Defined in | Include | Link to
Client, JavaScript | Microsoft Server Appliance Kit 3.0 |  |  |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_EnableBack

This function enables the Back button.

SA_EnableBack()

Parameters

None.

Return Values

None.

Remarks

The SA_EnableBack function enables the Back button, allowing the user to use it.

Requirements

Runs on | Versions | Defined in | Include | Link to
Client, JavaScript | Microsoft Server Appliance Kit 3.0 |  |  |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_EnableCancel

This function enables the Cancel button.

SA_EnableCancel()

Parameters

None.

Return Values

None.

Remarks

The SA_EnableCancel function enables the Cancel button, allowing the user to use it.

Requirements

Runs on | Versions | Defined in | Include | Link to
Client, JavaScript | Microsoft Server Appliance Kit 3.0 |  |  |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_EnableFinish

This function enables the Finish button.

SA_EnableFinish()

Parameters

None.

Return Values

None.

Remarks

The SA_EnableFinish function enables the Finish button, allowing the user to use it.

Requirements

Runs on | Versions | Defined in | Include | Link to
Client, JavaScript | Microsoft Server Appliance Kit 3.0 |  |  |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_EnableNext

This function enables the Next button.

SA_EnableNext()

Parameters

None.

Return Values

None.

Remarks

The SA_EnableNext function enables the Next button, allowing the user to use it.

Requirements

Runs on | Versions | Defined in | Include | Link to
Client, JavaScript | Microsoft Server Appliance Kit 3.0 |  |  |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_EnableOK

This function enables the OK button.

SA_EnableOK()

Parameters

None.

Return Values

None.

Remarks

The SA_EnableOK function enables the OK button, allowing the user to use it.

Requirements

Runs on | Versions | Defined in | Include | Link to
Client, JavaScript | Microsoft Server Appliance Kit 3.0 |  |  |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SetData

This function, which must be implemented by the Web developer, is called by the Web framework after ValidatePage returns TRUE.

Function SetData()

Parameters

None.

Return Values

None.

Remarks

Use this function to perform any final updates that might be required before the submit action is performed. For example, this might include updating hidden form fields.

Timing occurs before the page is submitted, after ValidatePage returns true while the page is running in the client Web browser.

The following code sample illustrates how to use this function.

function SetData()
{
    //Perform cleanup before the Submit occurs.
}

Requirements

Runs on | Versions | Defined in | Include | Link to
Client, JavaScript | Microsoft Server Appliance Kit 3.0 |  |  |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


TaskFn

This is the JavaScript function prototype for the function that must be passed to the OTS_CreateTaskEx function.

TaskFn(
sMessage,
iTaskNo,
iItemNo
)

Parameters

sMessage
The following table shows the available messages.
Message | Description
OTS_MESSAGE_BEGIN | Indicates the beginning of an activation event. This message should be used to reset any state control variables used to determine the activation state.
OTS_MESSAGE_ITEM | Indicates that an item has been selected. The index number of the item is contained in the iItemNo parameter for this message.
OTS_MESSAGE_END | Indicates the end of the activation event. The function should finalize the task state before returning from this message.
iTaskNo
Index number (zero-based) of the task to which this message refers.
iItemNo
Index number (zero-based) of the item that has been selected and is only applicable to item message in sMessage parameter.

Return Values

When processing the OTS_MESSAGE_ITEM variable, returning FALSE will cause the Web UI framework to stop enumerating the selected items.

When processing the OTS_MESSAGE_ITEM variable, returning TRUE will cause the Web framework to continue enumerating the selected items.

Returns TRUE for OTS_MESSAGE_BEGIN and OTS_MESSAGE_END.

Remarks

The following code sample illustrates how to use this function. For a complete example, see Sample_ots_dynamic_tasks.asp

var iTaskOne_ItemCount = 0;
function ExampleTaskActivationFn(sMessage, iTaskNo, iItemNo)
{
  var rc = true;

  if (sMessage == OTS_MESSAGE_BEGIN)
  {
    iTaskOne_ItemCount = 0;
  }
  else if (sMessage == OTS_MESSAGE_ITEM)
  {
  iTaskOne_ItemCount += 1;
  }
  else if (sMessage == OTS_MESSAGE_END)
  {
    if (iTaskOne_ItemCount != 1)
    {
      OTS_SetTaskEnabled(iTaskNo, false);
    }
    else
    {
      OTS_SetTaskEnabled(iTaskNo, true);
    }
  }

  return rc;
}

Requirements

Runs on | Versions | Defined in | Include | Link to
Client, JavaScript | Microsoft Server Appliance Kit 3.0 |  |  |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.

Related Topics


ValidatePage

This function, which must be implemented by the Web developer, is called by the Web framework as part of the submit processing. When the user clicks OK, the Web framework calls this function.

Function ValidatePage()

Parameters

None.

Return Values

None.

Remarks

Use this function to validate user input. If input errors are detected, returning FALSE from this function will cause the Web framework to not submit the page.

Timing occurs before the page is submitted for processing while the page is running in the client Web browser.

The following code sample illustrates how to use this function.

function ValidatePage()
{
    return true;
}

Requirements

Runs on | Versions | Defined in | Include | Link to
Client, JavaScript | Microsoft Server Appliance Kit 3.0 |  |  |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


Utility Routines

Routine | Description
SA_EscapeQuotes | Returns the string with apostrophes replaced with an escaped version (\'). This function is used to correctly format text for use in Microsoft® JScript® code.
SA_GetCharSet | Returns the character set encoding to be used for the current language setting.
SA_GetElements | Returns the collection of elements for the specified container.
SA_GetLocString | Returns the specified string from the resource DLL in the current language directory.
SA_IsIE | Returns a Boolean value indicating whether the browser is Microsoft® Internet Explorer.
SA_MungeURL | Allows for manipulation of URLs to add, update, or delete the specified parameter.


SA_EscapeQuotes

This function returns a string with apostrophes replaced with an escaped version (\'). This function is used to correctly format text for use in JScript code.

SA_EscapeQuotes(
ByVal InputString
)

Parameters

InputString
Name of the string to be formatted.

Return Values

The formatted string.

Remarks

The following code example illustrates how to use this function.

<A
title="<%= L_CHIMESTATUS_LABEL %>"
onMouseOver="window.status='<%=Server.HTMLEncode(SA_EscapeQuotes(L_CHIMESTATUS_LABEL)) %>';return true;"
href="sample/chime_status.asp?ReturnURL=/admin/home.asp"><%= L_MAINSTATUS_CHIME %></A>

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_GetCharSet

This function returns the character set encoding to be used for the current language setting.

SA_GetCharSet()

Parameters

None.

Return Values

The character set encoding.

Remarks

The following example uses this function to set the HTML character set encoding.

<meta http-equiv="Content-Type" content="text/html; charset=<%=SA_GetCharSet()%>">

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_GetElements

This function returns the collection of elements for the specified container.

SA_GetElements(
ByVal Container
)

Parameters

Container
Name of the collection to be retrieved.

Return Values

The specified collection of elements.

Remarks

The following sample code shows how to use this function.

Dim objAlertCol     ' the collection of alerts
Dim objElement    ' each element in the collection

Set objAlertCol = SA_GetElements("SA_Alerts")

For Each objElement in objAlertCol
'do something
Next

Set objAlertCol = Nothing

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_GetLocString

This function returns the specified string from the resource DLL in the current language directory.

SA_GetLocString(
ByVal sourceFile,
ByVal resourceID,
ByRef replacementStrings
)

Parameters

sourceFile
Name of the resource DLL that contains the strings.
resourceID
Resource identifier of the desired string.
replacementStrings
Array of strings to use as replacement strings.

Return Values

The localized string.

Remarks

By putting all UI text in resource DLLs, it is possible to create a multilingual server appliance with minimal effort.

The following Microsoft® Visual Basic®, Scripting Edition (VBScript) code example uses the SA_GetLocString function to get text from a resource DLL. This sample uses the strReplacementStrings parameter to insert text into the message string.

A complete example using this function can be found in the localization sample file, Localized.asp.

Dim strSourceFile
Dim strResourceID
Dim strReplacementStrings(1)    'Declare an array of 2

'These strSourceFile and strResourceID values correspond to the string "Unexpected error %1 %2"
strSourceFile = "sampleloc.dll"
strResourceID = "C05000CD"
strReplacementStrings(0) = "Value1"
strReplacementStrings(1) = "Value2"
'The resulting text will be displayed as "Unexpected error Value1 Value2"
Response.write(SA_GetLocString(strSourceFile, strResourceID, strReplacementStrings))

Note that depending on how the string is used, it might be necessary to use SA_EscapeQuotes and Server.HTMLEncode.

Use Server.HTMLEncode if the string will be enclosed in double quotes.

Response.Write("<td title=""" + Server.HTMLEncode(SA_GetLocString(strSourceFile, strResourceID, strReplacementStrings))+ """ >")

If the string will be used in JavaScript, use SA_EscapeQuotes and enclose the string in single quotes.

SA_DisplayErr('<%=SA_EscapeQuotes(SA_GetLocString(strSourceFile, strResourceID, strReplacementStrings))%>')

If the string is used in JavaScript that is passed to an HTML parameter, you will need to use both SA_EscapeQuotes and Server.HTMLEncoder.

Response.Write("<td onmouseover=""window.status='" + Server.HTMLEncode(SA_EscapeQuotes(SA_GetLocString(strSourceFile, strResourceID, strReplacementStrings)))+ "'"" >")

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_IsIE

This function returns a Boolean value indicating whether the browser is Internet Explorer.

SA_IsIE()

Parameters

None.

Return Values

TRUE
The browser is Internet Explorer.
FALSE
The browser is not Internet Explorer.

Remarks

The following example uses this function to check the type of browser.

If SA_IsIE() Then
   'do something
Else
   'do something else
End If

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


SA_MungeURL

This function manipulates the specified URL to add, update, or delete the specified parameter.

SA_MungeURL(
ByRef sURL,
ByVal sParamName,
ByVal sParamValue
)
sURL
URL to be manipulated.
sParamName
Name of the parameter that is to be added, changed, or removed.
sParamValue
Value of the parameter that is to be added, changed, or removed.

Remarks

This function will apply the URLEncode function to the sParamValue parameter. Do not enter Server.URLEncode(sParamValue)before passing to this function.

To delete a parameter value from the URL, specify the parameter name and a blank value as in Call SA_MungeURL(sURL, "FavoriteFood", "").

To add or update a parameter to the URL, specify the parameter name and a valid nonblank value as in Call SA_MungeURL(sURL, "FavoriteFood", "ApplePie").

The following code sample illustrates how to use this function.

Dim sURLExample
'
sURLExample = "Tasks.asp"
'
' Add a parameter to the URL.
Call SA_MungeURL(sURLExample, "Param1", "Green")

Requirements

Runs on | Versions | Defined in | Include | Link to
Server (ASP), VBScript | Microsoft Server Appliance Kit 3.0 |  | inc_framework.asp |

Note

  • This function is part of the complete Server Appliance Kit as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM), and some devices might not support this function.


Localization Framework

The localization framework makes it possible for your server appliance application to be localized into multiple languages, giving users the option to change the language in which the server appliance user interface (UI) and online Help are displayed. In addition to English, the Server Appliance Kit provides localized Web UI elements, Help, and a local UI in the following languages:

  • Chinese (simplified)
  • Chinese (traditional)
  • French
  • German
  • Japanese
  • Korean
  • Spanish

To provide localized UI elements, you must create one or more resource dynamic-link libraries (DLLs) for each language you want to provide for your Web UI and local UI. These resource DLLs contain the UI text strings for a particular language. Your Web UI and local UI elements then call the SA_GetLocString function to obtain the correct localized string (that is, the string in the language that is selected by the user) before adding it to the UI output. When the server appliance is built, these resource DLLs are placed in language-specific directories so they can be found and used by the Localization framework.

If you provide on-line Help for your Web UI, you also place the HTML pages for that Help into a language-specific directory.

Related Topics


Adding Localized Text Resources

The server appliance framework supports building multilingual server appliances. To utilize this capability, all dynamic text must first be implemented using an .mc file or an .rc file. The text must then be compiled into a DLL and stored on the server appliance using the four character hexadecimal LangID language code. For example, the following code sample shows how English resources would be stored.

%systemroot%\system32\serverappliance\mui3\0409\sampleresource.dll

In the example above, 0409 is the appropriate four character hexadecimal LangID language code. For more information about locating a list of these codes, see the Microsoft Web site.(http://msdn.microsoft.com/)

These message file names, including the path relative to the language code directory, are then entered into the Windows registry to be used by the localization manager. The localization manager displays text on the Web user interface (UI) and the local display, which is the small screen built into the server appliance, in the correct language.

Note that it is important to never concatenate strings when creating a UI that will be used in multiple languages. The word order is different in various languages and it will be impossible to translate properly. The server appliance framework supports replacement strings to allow building strings that have dynamic content. For example, the resource string Do you wish to delete the user %1? allows you to change the user name at runtime and allows a localizer to adjust the location of the user name in the string to match the conventions of the language.

Related Topics


Creating a Resource DLL

Creating a resource DLL requires that you complete the following eight steps:

  1. Write a message (.mc) file containing the specific messages.
    • Depending on the application, it makes sense to assign facility names to the message file, as illustrated in the following code snippet. System (0x0FF) and application (0xFFF) facilities are supplied by default.
      FacilityNames=(
    System=0x0FF
    Application=0xFFF
    MyApp_tab=0xA00 :SA_MYAPP_FACILITY_TAB
    )
    • Assign message identifiers to the messages, as illustrated in the following code snippet. This will ensure that message identifiers remain constant even if the message file is later modified. To enable adding messages at a later date, Microsoft recommends that you skip numbers as you assign message identifiers. Assign a symbolic name to each message; the name can then be used within your calling program to extract messages from the dynamic-link library (DLL). Note that at the end of each message entry, a period and a carriage return are required on a separate line.
      MessageID    = 4
Severity     = Informational
Facility     = MyApp_Tab
SymbolicName = SA_MY_TAB_CAPTION
Language     = English
My Tab
.
  2. Use the message compiler to compile the message file.
    mc -U -h . -r .      sampleresource.mc

    The following table shows the files that the compilation will generate.

    File | Description
    MSG00001.bin | Binary message (.msg) file that will be included in the resource DLL.
    sampleresource.h | Header (.h) file that includes the generated messages and corresponding identifiers. This header file must be included by a calling program that will extract message identifiers that use symbolic names.
    sampleresource.rc | Resource file used to generate the DLL.
  3. Create an .rc file that includes the resource file generated by the message compiler. The following code example shows how to create the .rc file.
    /////////////////////////////////////////////////////////////////////////////
//
// Message TABLE="100%" Info
//
/////////////////////////////////////////////////////////////////////////////
#include "SampleResource.rc"

#define VER_FILETYPE                    VFT_DLL
#define VER_FILESUBTYPE                 VFT2_UNKNOWN
#define VER_FILEDESCRIPTION_STR         "Microsoft Server Appliance SDK Sample"
#define VER_INTERNALNAME_STR            "SAMPLERESOURCE.DLL"
#define VER_ORIGINALFILENAME_STR        "SAMPLERESOURCE.DLL"
  4. Write the source file, called SampleresourceMain.cpp, containing DLLMain as the following code sample illustrates.
    #include "windows.h"

extern "C" BOOL WINAPI
DllMain(
    HINSTANCE   hInstance,
    DWORD       dwReason,
    LPVOID      lpReserved
    )
{
        return (TRUE);
}   //  end of DllMain method
  5. Create a definition (.def) file for the DLL. The following code sample shows how to create the .def file.
    ; MyAppResource.def : Declares the module parameters.
LIBRARY      "SampleResource.dll"
VERSION 1.0
EXPORTS
DllMain         @1 PRIVATE
  6. Compile the sampleresourcetbl.rc file using the resource compiler. Please note that the l symbol in the .rc file represents the code page. The resulting .res file is going to be packaged into the resource DLL. The following code sample shows how to compile the sampleresourcetbl.rc file.
    rc –l 409 -r -fo sampleresourcetbl.res sampleresourcetbl.rc

    For more information about flag definitions, see the Microsoft Web site.(http://msdn.microsoft.com/)

  7. Compile the source file containing the DLLmain and link the source file with the sampleresourcetbl.res and samplersource.def files to create the sampleresource.dll. The following code sample shows how to compile the source file.
    (Compiler options:
Cl /c /Zel /Zp8 /Gy  /W3 /Gz  /QIfdiv- /QIf /QI0f /GB /Gi- /Gm- /GX-  /GR- /GF -Z7 /D UNICODE /D _UNICODE /Od -I<include path for include files windows.h, and CRT>
SampleresourceMain.cpp
)
  8. Type the link command. The following code sample shows how to type the link command.
    link /DLL /MACHINE:Ix86 /DEF:MyAppResource.def Sample MyAppresource.obj MyAppresourcetbl.res msvcrtd.lib

After you have created a resource DLL, you will need to find the resource identifiers for each message. You can look in the header (.h) file to match each symbolic name to its corresponding identifier. These identifiers are necessary to instruct the framework functions which localized text you want.

For more information on message compiler, see the Microsoft Web site.(http://msdn.microsoft.com/)


Build-Time Procedure

The following steps must be taken at the time an image is built:

  1. You must install the resource files for all supported languages that include text strings for the Web UI and local display in the correct directories.
  2. You must provide the Web element definitions for these localized alert strings. For more information on creating Web element definitions, see Registry Values.
  3. You must provide information about alert messages showing up in the LCD in the appropriate service registry key. For more information about alert messages, see Raising and Displaying Alerts.


Glossary

A

access control list (ACL)
A list associated with an object that contains information about users or groups who have permissions to use or modify the object.
ACL
See access control list.
ACPI
See Advanced Configuration and Power Interface.
Advanced Configuration and Power Interface (ACPI)
A specification that defines a new interface to the system board. This interface enables the operating system to implement operating system-directed power management and system configuration.
action message
A message displayed when an alert is raised.
Active Directory
The directory service included with Windows 2000 Server that stores information about objects on a network and makes this information available to users and network administrators.
Active Server Pages (ASP)
An open application environment in which HTML pages, scripts, and ActiveX components are combined to create Web-based applications.
agent
A computer running Simple Network Management Protocol (SNMP) agent software. See also Simple Network Management Protocol.
alert ID
The code used to identify and raise an alert. The combination of AlertID and AlertLog are unique for each alert.
AlertLog
The code used to uniquely identify the area of the alert, such as disk and Internet. The combination of AlertID and AlertLog are unique for each alert.
alerts
Actions to be taken when specific events occur, such as a specific error, errors of certain severities, or a database reaching a defined limit of free space available. The alert can be defined to take such actions as sending an e-mail, paging an operator, or running a job to address the problem.
API
See application programming interface.
appliance initialization task
The appliance initialization task is executed on every boot. Add the appliance task object to the list of task executables in the appliance initialization task under the following registry key and value: HKLM\Software\Microsoft\ServerAppliance\ApplianceManager\ObjectManagers\Microsoft_SA_Task\ApplianceInitializationTask
application programming interface (API)
A standard set of documented and supported routines that expose operating system programming interfaces and services to applications.
application wizard
A wizard that automatically creates a set of starter files for a new component.
ASP
See Active Server Pages.
ASSP
See Application Specific Standard Product.
asynchronous operation
1. A process in a multitasking system whose execution can proceed independently or in the background. Other processes may be started before the asynchronous process has finished. 2. A data transmission method that allows characters to be sent at irregular intervals over a line by preceding each character with a start bit and following it with a stop bit. Compare synchronous operation.
atomic operations
Indicates that either all actions occur or none of them will.

B

boot
The process a computer performs to load its operating system.
boot loader
An application that is automatically run when a computer is switched on (booted). After first performing a few basic hardware tests, the boot loader loads and passes control to a larger loader application, which then typically loads the operating system.
bootable
Contains the system files necessary for booting a device and running it.
bootstrap loader
See boot loader.
branding
OEM identification.
buffered I/O
Stored data that is buffered in anticipation of another sequential read request.
build dependency
The functional relationship between two components that controls the order in which components are built into an embedded run-time image. A build dependency does not cause the automatic inclusion of a component in an embedded run-time image.
build process
The process of using the information in a configuration to construct an embedded run-time image. The output of the build process is defined by script contained in individual component object definitions, which are sometimes inherited from a prototype.

C

category group
Used to collect components into functionally related categories as an organizational convenience. Category groups are used to organize components in the Windows XP Embedded user interface. See also group.
COM
See Component Object Model.
COM class
The definition of an object in code. In the Component Object Model, class refers to the general object definition, whereas in C++, the class of an object is a data type.
COM object
A programming structure that includes both data and functionality. A COM object is defined and allocated as a single unit.
component
The smallest individually selectable piece of functionality that can be included or excluded from an embedded run-time image, comprised of files, registry entries, and dependency information. It is the most basic element in a configuration.
Component Designer
A development tool that enables you to create a custom component to add to the Windows XP Embedded component database.
component instance
A specific instance of a component that is included within a configuration. A component instance is configured entirely by dynamic HTML. Each component instance consists of multiple components in an ordered chain of prototypes.
Component Object Model (COM)
An open architecture for cross-platform development of client/server applications. COM is based on object-oriented technology as agreed upon by Digital Equipment Corporation and Microsoft Corporation. COM defines the interface, similar to an abstract base class, IUnknown, from which all COM-compatible classes are derived.
component prototype
A component from which others are directly or indirectly derived. Windows XP Embedded uses an ordered chain of prototypes in component instances.
configuration
A set of data that contains all the information necessary to build a Windows-based embedded run-time image, including which components to include. A configuration is contained in a file that has the .slx file extension.
configuration file
A file that contains a configuration. See source code configuration file, configuration, and image configuration file.
configuration page
Can be an HTML page on the Web user interface where the feature or component is set up.
configure
The process of the user setting properties of a tool or device so that it operates correctly and according to user specifications.
conflict
An incompatibility between components or capabilities, or when the same system resource has been allocated to multiple devices. Conflicts are defined in a component definition.
control
A standardized child window on the screen that can be manipulated by the user to perform an action or display information. The most common controls are buttons that allow the user to select options and scroll bars that allow the user to move through a document or position text in a window.
control code
One or more nonprinting characters used by a computer program to control the actions of a device.

D

data type
A class of registry entry, which includes REG_BINARY, REG_DWORD, REG_EXPAND_SZ, REG_MULTI_SZ, and REG_NONE. See also DWORD.
Database Manager
The tool that enables you to manage the component database and the repositories.
DDK
See driver development kit.
de-bounce algorithm
A set of instructions that makes an assumption about how fast a user can press and release a switch and then ensures that only one press is registered in the time specified.
delayed procedure call (DPC)
A routine that checks specific parameters.
dependency
A directed relationship between two objects, typically components or objects. For example, if resource A depends on resource B, then B is a dependency of A.
dependency group
A type of dependency that allows a component to express a dependency on all components that belong to the group. See also group.
direct memory access (DMA)
Memory access that does not involve the microprocessor and is frequently used for data transfer directly between memory and an "intelligent" peripheral device, such as a disk drive.
DLL
See dynamic-link library.
DMA
See direct memory access.
DPC
See delayed procedure call.
driver development kit (DDK)
A set of tools and libraries that enable programmers to write Windows-based software used to run hardware devices, such as printers.
DWORD
A data type composed of hexadecimal data with a maximum allotted space of 4 bytes.
dynamic-link library (DLL)
A set of autonomous functions that any application can use. DLLs are a set of object code modules with each module containing a set of functions.

E

embedded
Broadly, software code or commands built into a device, as opposed to software that is added. In a narrower sense, code that is typically stored in ROM and dedicated to either controlling a device or providing a specific functionality.
embedded run-time image
The final output of the Windows XP Embedded authoring tools, which is the combination of operating system binaries, drivers, applications, services, and configuration data (typically in the system registry).
event viewer
A tool that displays a log that reports critical and noncritical events.
extension key
An entry in the registry, corresponding to the extension of a given file, that specifies which file filter will handle conversions for that file type.

F

focus
1. A temporary property of a user interface object, such as a window, view, dialog box, or button, that permits the object to receive keyboard input from the user. 2. One of the two points that determine the shape of an ellipse. The sum of the distances between any point on the ellipse and each of the foci is constant.
form
An ActiveX control container that you customize to create a user interface for your application. A form contains a collection of controls, such as speech controls, power list boxes, audio controls, and tabber controls. A form displays information on a screen.

G

gateway
The address of a local IP router residing on the same network as the server appliance and that is used to forward traffic to destinations beyond the local network.
global variable
A variable whose value can be accessed and modified by any statement in an application and not merely within a single routine in which it is defined.
globally unique identifier (GUID)
A unique 128-bit value used to identify objects. See also universally unique identifier.
group
A collection of components that are grouped to express dependencies between components, to express user interface categories, or to bulk upgrade instances or component deletions. Groups include dependency, package, and category. See also category group, dependency group, and package group.

H

hardware abstraction layer (HAL)
Consists of hardware and device driver mechanisms that insulate applications from device-specific implementation details. If a capability requested by an application is not implemented by the current hardware, the capability will be emulated by the software.

For Windows CE, see also OAL.

headless
A system that does not have a keyboard, mouse, or video monitor during normal operation, also known as remote administration.
hive
A section of the registry that is stored in a file on a computer's hard disk. Hives are located on a specified volume or in the user profiles.
host system
The computer system that hosts the Windows XP Embedded development environment and authoring tools. This is the system on which the embedded run-time image is constructed.

I

IDE
See integrated development environment and Integrated Device Electronics.
IIS
See Internet Information Services and Internet Information Servers.
image
See embedded run-time image.
image configuration file
A file that Makeimg.exe uses to create an operating system image. Image configuration files include .bib, .dat, .reg, .db, and .str files. See also configuration file.
image file
A file that is generated by Romimage.exe that makes up the bits of the operating system image. An image file can be one of the following three formats: Windows CE binary image data format (.bin), Motorola 32-bit binary data format (.sre), or absolute binary data format (.abx).
implementation
In Platform Builder, an implementation contains the functionality necessary to implement the features contained in a type. There can be more than one implementation for a given type. You use the Platform Builder Catalog and Component view to view implementations and to add them to a platform.
instantiate
The process of creating a specific instance of a component within a configuration.
integrated development environment (IDE)
In Microsoft Visual Studio, an integrated set of Windows-based tools for building, testing, and refining an application. The IDE includes a variety of editors, project build facilities, compilers, an incremental linker (for C++), a class viewer, and an integrated debugger. The IDE enables you to create, test, and refine your applications and Web sites all in one place.
Integrated Device Electronics (IDE)
A type of disk-drive interface in which the controller electronics reside on the drive itself, eliminating the need for a separate adapter card.
Internet Information Servers (IIS)
Software services that support Web site creation, configuration, and management, along with other Internet functions. Internet Information Servers include the Network News Transfer Protocol (NNTP), File Transfer Protocol (FTP), and Simple Mail Transfer Protocol (SMTP).
Internet Information Services (IIS)
Microsoft’s brand of Web server software, using HTTP to deliver World Wide Web documents. IIS incorporates various functions for security, allows for CGI applications, and provides for FTP servers. In versions 4.0 and earlier, IIS was named Internet Information Server.
interrupt priority
One of three thread priority groups. Interrupt priority is reserved for operating system threads. See also idle priority and main priority.
interrupt service routine (ISR)
A small subroutine that resides in the OEM adaptation layer (OAL). The ISR executes in kernel mode and has direct access to the hardware registers. Its sole job is to determine what interrupt identifier to return to the interrupt support handler. Essentially, ISRs map physical interrupts onto logical interrupts.
interrupt service thread (IST)
A thread created by a device driver to wait on an event.
interrupt support handler
A routine that registers a driver so that it can handle a particular interrupt and deregister it later. It also enables communication between the interrupt service routine, the interrupt service thread, and subroutines within the OEM adaptation layer (OAL) in Windows CE and the hardware abstraction layer (HAL) in Windows XP Embedded.
ISR
See interrupt service routine.

J

There are no glossary terms that begin with this letter.

K

key
1. A field or expression used to identify a record; often used as the index field for a database table. 2. The complete registry subkey path of a registry value.

L

LANGID
See language identifier.
language identifier (LANGID)
A standard international numeric abbreviation for a country or geographical region. An LANGID is a 16-bit value that consists of a primary language identifier and a secondary language identifier. A LANGID is constructed using the MAKELANGID macro. See also locale identifier.
locale identifier (LCID)
A 32-bit value that consists of a language identifier and a sort identifier. In code, an LCID identifies the primary language and any secondary language of a specific locale. An LCID is constructed using the MAKELCID macro. See also language identifier.
localization
The process of adapting an application for a specific international market, which includes translating the user interface, resizing dialog boxes, customizing features if necessary, and testing results to ensure that the application still functions properly.

M

message handler
A Component Object Model (COM) object that implements the ITranslate interface in an in-process COM object.
message sink
A callback function that receives messages for a form or a control. Forms or controls that need to be notified of messages implement a message sink.

N

There are no glossary terms that begin with this letter.

O

object definition
Data that defines a discrete packets of functionality, called components, that can be included in the final run-time image. The functionality is expressed as a set of resources (files, registry entries, and dependency information), properties, and optional script.
object definition file
A file that contains object definitions, including components. The component object definition file has the .sld file extension. In Windows NT Embedded 4.0, the file has the .kdf extension.
object type
A name for a particular group of objects that are contained in a folder.
operating system image
The executable file that contains the operating system. See also run-time image.

P

package
A set of one or more components that are treated as a unit when they are either imported or exported to or from the Windows XP Embedded component database. See also group and package group.
package group
Used to collect components together for administrative purposes, allowing a set of components to be managed as a single unit. Examples include upgrading all component instances to a new service pack or deleting all components in the group. See also group.
packet
A unit of information transmitted as a whole from one device to another. A packet includes data and a header containing an identification number, source and destination addresses, and error-control data.
page file
A file on the hard disk that holds parts of applications and data files that do not fit in memory. Data is moved from the page file to memory as needed and moved back to the page file to make room for new data. The paging file and physical memory, or RAM, comprise virtual memory. Also called a swap file.
partition
A portion of a disk that functions as though it were physically separate.
persistent image
A copy at a given instant of the information stored on a selected volume or volumes. The persistent image can later be restored to the server appliance to replace lost data.
physical repository
A location from which files are copied when building a run-time image.
platform
Defines the type of target embedded run-time image being constructed. A platform defines a target operating system, CPU, and locale and is bound to one component database. When a configuration is created, the user selects a specific platform. For example, one platform might be Windows (x86)–US English.
Point-to-Point Tunneling Protocol (PPTP)
A networking technology that supports multiprotocol virtual private networks (VPNs), enabling remote users to access corporate networks securely across the Internet. Using PPTP users can remotely run applications that are dependent on particular network protocols. See also packet.
PPTP
See Point-to-Point Tunneling Protocol.
process
A running application that consists of a private virtual address space, code, data, and other operating system resources, such as files, pipes, and synchronization objects that are visible to the process. A process also contains one or more threads that run in the context of the process.
property
With respect to the Windows XP Embedded component database, a property consists of component or object properties, including lists of resources and dependencies, group membership, version, and so on.
With respect to the database API, a property refers to a data item that consists of a property identifier, data type, and value.
prototype
See component prototype.

Q

There are no glossary terms that begin with this letter.

R

Remote Access Service (RAS) server
Any Windows-based server configured to run the Remote Access Service. See also Remote Access Service.
repository
A storage area used as the source for all embedded run-time image files required during the build process. There may be multiple repositories for a single installation. Repositories may exist as folders (directories) or .cab files.
repository file source
The location of repository files before import has taken place.
repository files
The actual files stored in a repository.
repository object
The database object in the component definition that logically defines a repository.
repository search path
The path that specifies one or more repository servers or share locations where physical repositories are located.
resource
An object that is used within an application but that is defined outside of the application.
run-time image (embedded)
The final output of the Windows XP Embedded authoring tools, which is the combination of operating system binaries, drivers, applications, services, and configuration data (typically in the system registry).

S

script
A set of instructions to an application or utility program. A script typically uses the rules and syntax of the application or utility. A script can also be called a macro. Common scripting languages are JavaScript and VBScript.
SDK
See software development kit.
server appliance
Fixed-function servers that are easier to install than general-purpose servers and eliminate post-purchase upgrade problems.
signature
The operating system identification. For example, "$Windows NT$".
Simple Network Management Protocol (SNMP)
The network management protocol for TCP/IP.
SNMP
See Simple Network Management Protocol.
software development kit
A set of library, header, and Help files that you use to write applications for a specific platform.
source code configuration file
A file that Build.exe uses to generate source code. A source code configuration file can be a dirs file, a sources file, or a makefile file.
symbol
A name that represents a register, an absolute value, or a memory address (relative or absolute).
synchronous operation
1. Two or more processes that depend on the occurrences of specific events such as common timing signals. 2. A data transmission method in which there is constant time between successive bits, characters, or events. The timing is achieved by the sharing of a single clock. Each end of the transmission synchronizes itself with the use of clocks and information sent along with the transmitted data. Characters are spaced by time and not by start and stop bits. 3. A function call that blocks execution of a process until it returns. See also asynchronous operation.

T

Target Analyzer
The analysis tool you use with Target Designer to ensure that your run-time image supports the hardware on your embedded device. This tool has two parts: a probe that identifies the hardware information on your target device and an engine that constructs a configuration based on the information identified by the probe.
Target Designer
The primary authoring tool that allows you to create, customize, and build a bootable run-time image.
target directory
The path for installing a target system.
target drive
The drive and path to which the target system loads.
target path
See target directory.
target system
The computer system on which the embedded run-time image executes.
Telephony API (TAPI)
A set of functions in the Win32 API set that lets a computer communicate directly with telephone systems.
thread local storage (TLS)
A Win32 mechanism that allows multiple threads of a process to store data that is unique for each thread. For example, a spreadsheet application can create a new instance of the same thread each time the user opens a new spreadsheet.
thread synchronization
The method used to coordinate the execution of two or more threads. There are two states in synchronization: signaled and nonsignaled. Threads can either modify the state of the synchronization object or wait for the object to reach a signaled state.
Time to Live
A header field for a packet sent over the Internet indicating how long the packet should be held.

U

Uniform Resource Locator (URL)
The address of a resource on the Internet. URL syntax is in the form protocol://host/localinfo, where protocol specifies the means of returning the object, such as HTTP or FTP. Host specifies the remote location where the object resides and localinfo is a string, often a file name, passed to the protocol handler at the remote location. Also called a Uniform Resource Identifier.
URL
See Uniform Resource Locator.

V

Value
A data string in the registry.
VIGUID
A version independent globally unique identifier (GUID). An identifier for a set of objects that represent different versions of the same principal. For example, VIGUID identifies the component as a specific DLL. The VIGUID remains constant for a component. See also globally unique identifier.
VSGUID
A version specific globally unique identifier (GUID). An identifier of a specific version of an object. The VSGUID for a component changes each time the component is upgraded to a newer version after the component definition is released. See also globally unique identifier.

W

wait function
A function that allows a thread to block its own execution. Wait functions do not return until the specified criteria have been met.
Win32
The API in Windows that enables applications to use the 32-bit instructions available on 80386 and higher processors.
Windows Management Instrumentation (WMI)
A management infrastructure that supports managing and controlling system resources through a common set of interfaces and provides a logically organized consistent model of Windows operation, configuration, and status. WMI was formerly WBEM (Web-Based Enterprise Management).
WMI
See Windows Management Interface.
write filter
A device that redirects write requests to a cache kept in RAM, enabling the embedded run-time image to run from any read-only media that emulates a disk drive or to write-protect any single disk partition. The write filter satisfies the read requests from either the underlying disk device or from the cache.

X

There are no glossary terms that begin with this letter.

Y

There are no glossary terms that begin with this letter.

Z

There are no glossary terms that begin with this letter.


SAK 3.0 - Glossary

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z


Customizing the Web UI

Add device-specific resources, registry contents, help files, and Active Server Pages (ASP) as required.

The Windows icon in the upper-right corner of the Web UI display must be left unaltered.

The WWW default root is configured by the Server Appliance Kit Installer package.

Related Topic

For more information on how to customize the Web UI, see Extending the Web UI.


Copyright

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, people, and events depicted herein are fictitious and no association with any real company, organization, product, person, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means–electronic, mechanical, photocopying, recording, or otherwise–or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Copyright © 2000-2003 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

Sample Code Rights and Restrictions

See the End User License Agreement for specific information regarding the rights and restrictions that apply to your use of the code samples provided.